Chapter 7 Modifications
Ben Marwick
In this template book, I have made some modifications inspired by Matthew Salganik’s Open Review Toolkit. The ORT is an excellent project to enable low-friction engagement between the author and readers. However, it pre-dates bookdown and lacks some of its flexibility, so this is an effort to bring some of the features of the ORT into bookdown. I’ve made three modifications: an open review block, a call-to-action block, and added google analytics.
7.0.1 Open review block
This is a custom block that is appearing at the top of each page informing the reader that they can give immediate feedback directly on the page. The HTML for this block is in open_review_block.html
The feedback tool is hypothes.is, which enables sentence-level annotation directly on the page. There is a script in hypothesis.html, which we call in _output.yml like this:
bookdown::gitbook:
includes:
in_header: [hypothesis.html, google_analytics.html]
before_body: open_review_block.html
after_body: call_to_action_block.html
css: style.cssThe hypothesis.html file contains a short script that activates the tool on this site. It also enables us to use the icons in the block above. The ORT also had code to track the use of hypothes.is, but I don’t understand how that works, so I haven’t done it here.
There are also additions to style.css to add a little styling to one of the inline images in the custom block (named rmdreview), and adds the speech bubbles on the left side of the block:
.h-icon-chevron-left {
background: white;
padding: 3px;
border: #eee 1px solid;
color: #666;
}
.fa-rotate-315 {
-webkit-transform: rotate(315deg);
-moz-transform: rotate(315deg);
-ms-transform: rotate(315deg);
-o-transform: rotate(315deg);
transform: rotate(315deg);
}
.rmdreview {
padding: 1em 1em 1em 5em;
margin-bottom: 0px;
background: #f5f5f5 5px center/3em no-repeat;
position:relative;
}
.rmdreview:before {
content: "\f0e6";
font-family: FontAwesome;
left:10px;
position:absolute;
top:10px;
bottom: 0px;
font-size: 60px;
}
7.0.2 Call-to-action block
The call-to-action block appears at the bottom of each page to invite the reader to submit their email address to receive updates on the book. This enables us to collect email addresses into a google sheet. The custom block looks like this:
This custom block is called rmdsale, the html for it is stored in all_to_action_block.html, which we refer to in the _output.yml file, as above.
The call-to-action block is styled with some css:
.rmdsale {
padding: 1em 1em 1em 4em;
margin-bottom: 0px;
background: #f5f5f5 5px center/3em no-repeat;
position:relative;
}
.rmdsale:before {
content: "\f07a";
font-family: FontAwesome;
left:10px;
position:absolute;
top:15px;
bottom: 0px;
font-size: 40px;
}The text field for readers to enter their email address is created by code in email_submit.html, which inserts some elements from a google form into the page.
To make this work, we have to create a new google form (using the ‘old google forms’, not the current version), and copy over the key and HTML element details from the default form view. Chrome’s element inspector is very handy for identifying the element details that need to go in email_submit.html.
The confirmation page that the reader sees after they submit their email is not yet elegant, it’s just the default google forms page. I’m not sure what to do about that.
The email addresses collected by this block are visible in my google sheet https://docs.google.com/spreadsheets/d/17Iyr_U-2AnrOVZBRVMhxihD8Ndpw_Pa2vdmCcFzKuPo/edit#gid=688456476
7.0.3 Google analytics
This is already used in many bookdown projects, and is easy to enable. We go to https://analytics.google.com, create a new account, and get the code snippet and paste it into google_analytics.html. After that, we add a reference to google_analytics.html in _output.yml, as noted above. And that’s it for setting up the analytics.
7.0.4 Not yet implemented
Matt’s ORT contains several other features that are not implemented here. These include tracking of hypothes.is use, A/B testing, a tool to translate the book into numerous languages. I’m not sure how to implement those, and would welcome assistance!
7.0.5 Issues
It is important to keep style.css and the custom html files in the top level directory of the book. I tried putting them all in a directory together, but couldn’t get it to work.
7.0.6 Reuse
The code for the Open Review Toolkit has an MIT license, and so is freely available for reuse. Because this implementation includes some code from that project, the license is used here also:
MIT License
Copyright (c) 2016 Open Review Toolkit & Ben Marwick
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.The text of this chapter is licensed under a Creative Commons Attribution 4.0 International License. This means it may be freely reused if appropriate credit is given.