Big Read Builder (Tarbell template)

Table of Contents:

1. Install & setup
2. Working with Tarbell
3. Using the template
4. Customizing the template
5. Publishing a Tarbell project
6. Creating multiple pages
7. Breaking down the template files
8. Support

Install & setup

Warning: This install process looks intense, but you only have to do it once. After all this is installed, you can literally spin up a project in minutes.

Tarbell requires the following:

1. Python. To make sure you have this, open the Terminal/command line and type which python. If you don't have it (you probably do), follow these download instructions.

2. pip. Pip comes packaged with Python 2.7.9 and 3.4, so you also probably have this. To check if this is installed, type which pip. Otherwise, install here.

3. virtualenv. To check for this, type which virtualenv.

   1. Install virtualenv with [sudo] pip install virtualenv
   2. Run which virtualenv. On a Mac, it should read /usr/local/bin/virtualenv.

4. virtualenvwrapper (optional, but highly recommended)

   1. Install virtualenvwrapper with [sudo] pip install virtualenvwrapper (Typing which
   2. Copy the following into your shell file (e.g. ~/.bash_profile): export WORKON_HOME=$HOME/.virtualenvs; export PROJECT_HOME=$HOME/Devel; source /usr/local/bin/virtualenvwrapper.sh
   3. Close your shell and open it again.

Once you've installed the above, install Tarbell!

1. Make a new virtualenv by typing in mkvirtualenv tarbell1.0.4 (You can replace tarbell1.0.4 with anything you want to name your virtualenv). Tarbell1.0.4 is simply the newest version of Tarbell.

2. Then, install Tarbell. Using a virtualenv is recommended because it helps you isolate different versions of Tarbell and it's dependencies. As new versions come out, you want to be able to separate the older from the new.

   1. Now install Tarbell into your virtualenv by running pip install tarbell
   2. Expand your terminal window so that it fills your screen (there's a bug that occurs if your text overflows over one line).
   3. Configure tarbell with tarbell configure. Follow the directions at http://tarbell.readthedocs.org/en/1.0.4/install.html

3. Install the blueprint: tarbell install-blueprint https://github.com/ajam/tarbell-big-read-template.git. The blueprint is the actual HTML and CSS template.

4. Run tarbell newproject and select the Big Read blueprint.

Working with Tarbell

If you installed Tarbell into a virtualenv, go into your virtualenv by typing in workon <name of virtualenv> (e.g. workon tarbell1.0.4). Create a new project using tarbell newproject. If you use Google Spreadsheets, this command will create a new spreadsheet and send you an invitation to edit. You can begin putting in content through your Spreadsheet. To preview the changes you make to your spreadsheet, run tarbell serve in the folder where you project lives and open your browser to localhost:5000. Your project preview is there. Anytime you make a change to the spreadsheet, simply refresh your browser window.

(For more information, check out the main Tarbell site)

Using the template

(Note: Directions for using this template is specific to the template in this repository, not all Tarbell templates)

Generating a new project with tarbell newproject should generate a Google Spreadsheet for you. Your Google Spreadsheet should have the following sheets. Do not modify any sheet names (order of the sheets does not matter). Do not change any headers in the sheets. (If you encounter an inexplicable error, it's likely someone accidentally changed the name of a header.)

Sheet name	Description
values	global values for the project
header	values that distinguish this project from other projects (like a name or headline)
chapters	each row represents a chapter in a series (can be left blank)
content	each row represents one piece of content on the page (text, image, subhead, graphic, etc...)
right_rail	each row represents one piece of content in the right rail
images	each row represents one image
bylines	each row represents one person who worked on the project and his/her role

Values for each sheet

rows in values	possible values	description
google_analytics_id	string	your unique ID from Google Analytics (can be left blank)
chartbeat_uid	integer	your unique ID from Chartbeat (can be left blank)
chartbeat_domain	string	the domain you've configured in Chartbeat
organization_name	string	the name of the organization you'd like to see in the upper left hand corner of the page
og_site_name	string	name of your site you've registered on Facebook
og_app_id	integer	unique app ID from Facebook
og_article_publisher_url	url	the URL of your app on Facebook
twitter_site_handle	string	your organization's Twitter handle (include the @)
twitter_domain	url	the root URL of your site

rows in header	possible values	description
splash_image_source	url	The path to the opening image (the big one on top). Does not need to be a full URL (e.g. images/portrait_01.jpg works)
headline	string	The headline of the project
subhead	string	The subhead of the project
opengraph_url	url	The full URL of the project for Facebook sharing
opengraph_image	url	The full URL to the image we will use for Facebook
opengraph_image_width	integer	Width of opengraph_image in pixels
opengraph_image_height	integer	Height of opengraph_image in pixels
opengraph_description	text	The text you want to use for Facebook sharing
twitter_description	text	The text you want to use for Twitter sharing
twitter_image	url	The full URL to the image we will use for Twitter

column in chapters (optional)	possible values	description
name	string	The name of the chapter
link	url	The url (can be full url or just the path) to each chapter
_notes	text	Anything you want. Isn't being used.

column in content (order matters!)	possible values	description
content_type	text, subhead, image, markup	The type of content you want to put in
id	string	If you need to target a specific content block, include a unique id here. Can leave blank.
value	text	For text, include the article text (to add in hyperlinks, use <a href=linkhere target=_blank>hyperlinked text here</a> without any quotes). For subhead, include the subhead. For image, include a unique image_group id (e.g. image-group-1). For markup, include the name of the HTML markup file to grab (e.g. _graphic.html) or type in the markup you'd like directly into the cell
right_rail_id	string	The unique id that you use to link the text content with the right rail content in the right_rail sheet.
_notes	text	Anything you want. Isn't being used.

column in right_rail	possible values	description
right_rail_id	string	The right rail id connects right rail information to where it should go within the content. Right_rail_id should also be found somewhere in the content sheet under the right_rail_id column.
content_type	text, subhead, image, markup	The type of content you want to put in
id	string	If you need to target a specific right rail block, include a unique id here. Can leave blank.
value	text	For text, include the article text. For subhead, include the subhead. For image, include a unique image_group id (e.g. image-group-1). For markup, include the name of the HTML markup file to grab (e.g. _graphic.html) or type in the markup you'd like directly into the cell
_notes	text	Anything you want. Isn't being used.

column in images	possible values	description
image_group	string	Image group connects image information with the content information in the content sheet. Image_group should also be found somewhere in the content sheet under the value column.
image_id	string	If you need to target a specific image, you can include a unique id here. Can leave blank.
image_layout	full, half left, half right, third left, third middle, third right, <blank>	Specify how you want the image to show up.
image_source	url	Path to the image (can be full URL or just path)
caption	text	Caption for the photo(s). Only fill out the caption for the first row out of each group (put all captions for the group in one row). If you leave this blank, you will get rid of space below photo (e.g. if you want to stack photos on top of each other, you can leave the caption for the top full image blank).
_notes	text	Anything you want. Isn't being used.

column in bylines	possible values	description
role_prefix	string	Role in the project (e.g. "By", "Produced by", "Photos")
name	string	Person's name
miscellaneous	string	Stuff you append to someone's name, like "for Al Jazeera America"
link	url	a link to someone's profile or Twitter profile (shows up as a link on the byline). Can be blank.
facebook_profile_url	url	a link to someone's Facebook profile. Optional. Only used for the author ("written").
byline_position	top or bottom	specifies whether you want the byline at the top of the piece or the bottom of the page
_notes	text	Anything you want. Isn't being used.

Customizing the template

If you would like to make any style changes, etc... you should modify the files that are in the project folder, not the _blueprint/ or _output/ folders.

Publishing a Tarbell project

1. Run tarbell generate _output. This takes the template and your spreadsheet and bakes a standalone folder with the main index file, and all necessary JS, CSS, images and other assets. Remember to re-generate whenever you make changes to your spreadsheet or to any of your template files.
2. Take the contents of your _output folder and upload these to a server (example: projects.aljazeera.com). You can also use the built-in tarbell publish <target> command in Tarbell to move your files onto your staging and production servers.

Creating multiple pages

(In late October 2015, Tarbell will have a better and easier way of creating multiple pages. The directions below, however, do work for now.)

1. Rename _story2.html to story2.html or a better, more SEO-friendly name.
2. Duplicate the following sheets in your spreadsheet and rename them all with the same suffix: header to header2, content to content2, right_rail to right_rail2, images to images2, bylines to bylines2.
3. In story2.html, add the suffix from the Google Spreadsheet so that the tab names match the variables: header2, bylines2, content2, images2 and right_rail2.
4. Repeat for any additional pages you may need.

Breaking down the template files

(Note: You don't need to know any of the following to use the template. These are just useful notes in case you want to modify the template.)

List of files

Tarbell using Jinja2 as its templating engine.

file name | description ---|---|--- _analytics.html | Code snippets for analytics (e.g. Google Analytics & Chartbeat) _base.html | Code snippet to connect all code snippets together into one page _content.html | Code snippets for all the content on the page under the intro _example-markup-file.html | An example file with markup _global-variables.html | Includes variables from your spreadsheet that your javascript references. It's generally bad practice to put javascript variables in your markup, but this allows you to use one javascript template file and apply it to multiple HTML pages. _intro.html | Code snippets to create the top image + headline + subhead _macros.html | This file does the heavy lifting. Includes templates for all content components (e.g. text, image, markup, subhead) _meta.html | Code snippets for HTML meta tags (e.g. open graph tags, twitter tags) _navigation.html | Code snippet for the top navigation header bar _spreadsheet.xlsx | This spreadsheet holds the template spreadsheet file for this particular Tarbell layout template (same as the Google Spreadsheet that gets created when you start a new project). After production, download your Google spreadsheet as _spreadsheet.xlsx to save it as a backup. _story2.html | A demo page for how to create new HTML pages within one project (e.g. with one spreadsheet) _title.html | Holds the <title></title> tag blueprint.py | Holds python functions (called "filters" in Jinja) that can help you manipulate content in your template. Holds some of the python scripts that make Tarbell work. index.html | The main file of your project that calls the _base.html file, which wires everything together.

Support

File a ticket.