For more information on using liquid filters read: http://wiki.github.com/tobi/liquid/liquid-for-designers

The following linking helpers are available for use with Hot Ink template data:

link_to_article - Link to an article’s page. Operates on the article
itself, eg {{ article | link_to_article }} or {{ article | link_to_article:”Check out this article” }}
link_to_section - Link to a section page. Operates on a section variable.
link_to_issue - Link to a issue’s page. Operates on an issue variable.
link_to_blog - Link to a blog’s page. Operates on a blog variable.
link_to_entry - Link to a blog entry. Operates on an entry variable.
link_to_page - Link to a static page. Unlike other link helpers, this helper operates on the name of the page in quotation marks, eg {{ “About Us” | link_to_page }}

The main way you will access your newspaper’s sections is through the newspaper drop using ‘newspaper.sections’. You can access the categories that an article belongs to using the ‘article.categories’ array from the article drop.

For each section/category the following data is available:

category.name - the name of the category
category.id - the category’s unique Hot Ink id number
category.subcategories - an array of the article’s subcategories

For more information on how to work with Liquid data types like hashes and array, read: http://wiki.github.com/tobi/liquid/liquid-for-designers

Blog entries are available through the Article drop, with one added variable, an ‘entry.blogs’ array of all the blogs this entry is belongs to. In all but a few rare cases, you can access the entry’s blog data using the syntax ‘entry.blogs.first’.

The blog drop contains the following data:

blog.title - the title of the blog.
blog.description - the description of this blog
blog.id - the unique Hot Ink id number for this blog.

Issue are generally accessed through the newspaper.latest_issues array, newspaper.latest_issue or through the “issues” array on an issues index page template.

For each issue, the following is available:

issue.date - this is the date of the issue and can be parsed with the Liquid “date” filter.
issue.name - this is the special name given to this issue, if any
issue.description - this is the special description given to this issue, if any
issue.volume - the publication volume this issue belongs to
issue.number - the number of this issue within the current volume
issue.press_pdf_url - a link to the press-quality PDF of this issue (try not to use this, use the screen quality version instead), relative to “http://hotink.theorem.ca”
issue.screen_pdf_url -  a link to the screen-quality PDF of this
issue, preferred over the press-quality PDF, relative to “http://hotink.theorem.ca”
issue.large_cover_image - Url of a 400px wide issue cover image, relative to “http://hotink.theorem.ca”
issue.small_cover_image - Url of a 175px wide issue cover image, relative to “http://hotink.theorem.ca”
issue.id - the issue’s unique Hot Ink id number
issue.account_id - your account’s unique Hot Ink id number
issue.articles - an array of all the articles in this issue.

To learn more about Liquid, the templating language used by Hot Ink, read the Liquid wiki at http://wiki.github.com/tobi/liquid

Your newspaper’s drop is the main piece of data used for building your template’s structure. If you’re interested in fleshing out your template with a little more data, be sure to take a good look at what’s inside this drop. We’re still adding new features to the site, so look forward to this drop expanding significantly over the next few month.

Before getting into exactly what data is included in the newspaper drop, it’s important to note one key detail: your newspaper drop does NOT contain real-time data. That is, the data in this drop is not reloaded with each user/reader page-view. The newspaper drop contains a wide selection of data, such a wide selection that reloading it all with each page view would slow down your site’s performance significantly. Instead, the various pieces of data in this drop are loaded at a regular frequency from your newspaper’s Hot Ink archive.
This means that changes made in your archive to the data in this drop can take a few minutes to become reflected on your site’s front page. If you add a category/section to your paper, for example, it may take a few minutes to for that category/section to appear on your site’s front page.

The newspaper drop includes the following data:
newspaper.name - the name of your newspaper’s account
newspaper.homepage_url - the relative url of your site’s front page, used to link back to it.
newspaper.root_url - the root url of your site that’s used to build composite urls, ie <a href=”{{newspaper.root_url”/blogs”}}>Blogs</a>.

This sometimes differs in value from the homepage url, so be sure you’re using the right one.

Regardless of what type of mediafile you’re dealing with, its data is contained inside a “mediafile drop”. For more information on Liquid, the templating language used by Hot Ink, read “Liquid for Designers” on the Liquid wiki: http://wiki.github.com/tobi/liquid/liquid-for-designers

It’s important to note that you’ll most often access mediafiles in association with articles, specifically mediafiles returned through the article.mediafiles array. A convenient way to use the mediafiles array, especially in front page teasers, is to simply access the first mediafile in the array using the syntax: “article.mediafiles.first”. The alternative is to loop over the mediafiles array using a Liquid for loop: “{% for mediafile in article.mediafiles %}” to access an
articles images. You need to use one of these methods even if you’ve only got one mediafile attached to your article.

You access the data using what’s called “dot-syntax” which really just means that the data is in the format “variable_name.data”. To output data in a template, you should use liquid output tags (they look like this: {{ your_data_here }} or {{ article.title }} ). Follow the liquid link above for a better idea of how to use data in your templates, including how to use for loops on arrays (a common task).

For each article the following data is available:

article.title - an article’s title or headline
article.subtitle - an article’s subtitle, subheadline or ‘deck’
article.authors_list - a formatted list of an article’s authors
article.id - an article’s unique Hot Ink id number
article.mediafiles - an array of an articles attached mediafiles
(including both articles and images). Follow the Liquid link above to
learn how to work with arrays.
article.images - an array of an articles attached images
article.audiofiles - an array of an articles attached audiofiles
article.published_at - a Gmail style date for the article (ie.
“12:33pm” for a recent article, “Apr 2″ for one this past April and
“12/28/08″ for one last December)
article.published_at_detailed - a detailed date output for this
article, useful with the Liquid “date” filter for custom date
formatting.
article.section - the name of the article’s primary section
article.categories - an array of all the sections (also called
categories) this article is a member of.
article.excerpt - either the article’s summary or truncated article
bodytext if no summary is present. Use Liquid’s truncatewords filter
to cutomize its length.
article.bodytext - the article’s full text. Since Hot Ink stores all
text formatted with “Markdown” you should use the “markdown” filter to
display bodytext (ie {{ article.bodytext | markdown }}).
article.url - the url of the article.
article.issues - an array of issues that this article was printed in
article.comments - an array of this article’s comments

Additions to the article drop:

article.tags - an array of this article’s tags.
article.tags_list - a tag-delimited list of this article’s tags
article.tags_list_with_links - a tag-delimited list of this article’s
tags with each tag name linking to a search for that tag.

article.authors - an array of this article’s authors.
article.authors_list_with_

Publishing with Hot Ink is different from publishing with any other content management system. Hot Ink strives to make it possible for you to exercise the same kind of careful control over the structure, appearance and composition of your website as you do over the print edition of your publication. Because it’s so flexible, the templating system can be a little overwhelming at first. To help make it a little easier to understand by defining some key terms.

In order to be visible to the public, your website must have a design and it must be set to be your website’s current design.

A design is a collection of layouts, templates, stylesheets, javascript files and images that together define the complete visual
presentation of your website. You can have as many designs as you like, but only one of them may be current at any one time. The design
designated as current is the one shown to readers when they visit your website.

Designs control the appearance of your site using templates. Templates are dynamic HTML files written using a templating language called Liquid. Liquid is a simple, easy-to-learn addition to standard HTML that makes it possible to build complex templates that accommodate a variety of individual types and forms of content gracefully. For example, a well written Liquid template for your article page will display the article differently depending on whether the content is
horizontal or vertical, an image or an audiofile, has a subhead or no subhead.

To learn how to use Liquid to design your site visit: http://wiki.github.com/tobi/liquid/liquid-for-designers

To cover the various functions of your website, Hot Ink supports five types of design template. There are layouts, page templates, partial templates, widget templates and front-page templates.  Layouts are like “wrapper” templates for page and front-page templates. The layout contains the content for the top and bottom of the web page, with the page template going in the middle. Many websites have common top and bottom portions that are shared across
many pages; layouts make it easy to write that code once and update it only once when a change needs to be made.

Page templates contain the actual page code for your site. Hot Ink supports page templates for the following “pages”: article page, section index page, search results page, blogs list page, blog home page, blog entry page, issues list page and issue contents page. Each page has a different set of data available for display, so be sure to pay close attention to what’s available on the page you’re working on. You can find the data availability information at the end of this
guide along with  little more information about each page type. Page templates can be wrapped in a layout for consistent visual style across multiple pages.

Partial templates are time-savers. They are small templates that can be rendered (that’s what we call it when we “display” a template) inside of any other template, even other partial templates. This is good for building pages that reuse code and makes the maintenance of your site a lot easier in the long run.
For example, you would use a partial template to outline a story teaser structure for your front page that’s reused over and over again with different articles inside (if you’re smart you’ll do this with a Liquid “for loop”). You could also use a partial template to build a media box you’d like to see on the right hand side of all your pages. Though you would include that partial on 5 or 6 pages, you would only have to edit it once when it was time to change.

Partial templates are a powerful part of Hot Ink site design.

Widget templates are even more powerful. They are similar to partials in that they can be rendered inside any template except other widget templates. However, widget templates are different from partial templates in that they include a special set of data that should appear inside them.

When designing a widget template the first thing you should do is build the template schema. A schema is an outline of entities, basically sets of content (like articles or blog entries), which could appear on the page. To create a schema for your widget template, click the “add entity” button. You should see a box appear with text fields to add a name and description and dropdown lists to select what data type of item will populate the widget, for example, “articles,” and
the quantity of items that it will fit. In the future, data types will expand to include media, blogs, blog entries and other content. For now, they are sets of articles only.

Inside the widget templates, an entity can be accessed as a ‘Liquid array’ using the name you give to it. I.e., feature_articles can be accessed using the liquid “for loop” with code that looks like:

{% for article in feature_articles %}
{{ Your article content here }}
{% endfor %}

So, the schema is made up of these entities and the widget template refers to them to fill its structure with data. You will be able to make many different types of content available to each widget template depending on which of these entities you use. Remember, right now we are just putting the template together.  The widget template provides the structure, but it doesn’t get fed with content until you create the actual widget.

To create a widget, go to the publisher dashboard and click on the “new” button next to “Current Widgets.” When you create a widget you can fill in the  schema from the template with real articles by dragging and dropping articles into the appropriate places.

You can then include that widget in a page template using the Liquid “widget” tag with the name you give to your new widget.

It might look like this: {% widget “News feature box” %}

The above code would render the “News features box” widget in whatever template you placed it in. It’s likely that this widget was built from a widget template named “Feature box” and that there could also be other widgets built from that template, like “Arts feature box”, but containing different content.

Front-page templates are exactly that, templates for the front page of your site. Specifically, they’re a special type of widget template. Since the front page of a newspaper website is the most complicated aspect of the site to design and manage, Hot Ink uses the flexible widget template system to give you full, granular control over your front page’s appearance.

A good front page should have a wide variety of content to help draw in readers with a variety of interests. It should also change frequently to reward readers who check back often for new content. Those readers are the bread and butter of web publishing. To accomplish this, simply create a front page template with a schema, just like a widget template. Then, from the Dashboard, build a new front page, fill it with content, preview it and—when you’re ready— make it your current front page.

Special tip: When combined with partial templates and a Liquid for loop, the front page template system is a powerful tool.

Hot Ink Publisher currently supports only one page template for each page type (blog, article, section index, static page, etc) except the front page, which can and should alternate from template to template. Creating more than one template for a page can lead to unpredictable results, so be warned. If you want to test a new template, consider building a new ’scratchpad’ design that copies your existing one and play with the templates there.

Widgets can be placed inside any template other than another widget template.

Your site only has one front page at a time. You control which one is current on your dashboard, which is available on the Publisher sub-menu. If no front page is set as the current one your site will appear offline to readers. Similarly, if no design is set as the current design, your site will appear offline to readers trying to view inside-page content.

If you’ve got any questions about the use of Hot Ink, especially during the Fall 2009 beta period, please send them along to chris at hotink dot net.

I’m about to post a ton of HotInk documentation that was previously only available on our email list serv and authored by Chris and Andrew. These articles are easy to find: they’re all in the Documentation category.

You can thank me later.

Mark