EEsaver is a starting point for building ExpressionEngine-powered sites that take advantage of the Treesaver layout engine. We love EE, and we think that its highly-customizable nature (not to mention its low price) makes it an ideal system for delivering the long-form, magazine-style content Treesaver was designed to publish.
What we've put together is a free set of ExpressionEngine templates, plus instructions for configuring EE to make them work. Drop in some content and you've got the beginnings of your own cross-platform magazine.
What is Treesaver?
In a nutshell, Treesaver is a JavaScript framework for creating magazine-style layouts using standards-compliant HTML and CSS. The makers of Treesaver have released the framework on GitHub. You should go read about it; it's pretty dang sophisticated.
The EEsaver Demo
Starting with the open-source treesaver.js files (and adding a few bits and pieces of markup from our own HTML5 Reset) we've developed a simple set of requirements for integrating Treesaver and EE, as well as a clean starter theme to get you going.
We then had a little fun (thanks to Google Books) and dug out some public-domain content from some of the very earliest issues of Harper's Magazine.
(Do some window resizing to see Treesaver's responsiveness in action.)
The design is a custom theme we developed and is free to use; we hope to release a really cool premium theme we've been working on very soon. (You should consider following @eesavr on Twitter to get the latest news.)
Instructions
Since what Treesaver creates is sort of a metaphorical magazine, let's extend that metaphor to explain how we're using ExpressionEngine for EEsaver:
The installation of ExpressionEngine is the magazine.
Channels within ExpressionEngine are the issues.
Individual entries within channels are the articles.
There are other ways to do it (using categories as issues for example), but at the moment this seems like the most efficient and workflow-friendly way.
Download and install the theme assets into your web root directory (the same directory as your index.php file).
Once EE is up and running (no special changes to the normal set up procedures are required), we can really get going.
Step One: Set up a channel.
This is easy, which is good considering we will be creating a new channel each time we release a new issue of our magazine.
First, set the General Preferences:
Full Channel Name: Harper's Magazine, Volume 9 (the name of the issue)
Channel Name: harpers-9 (EE will use this as the URL trigger for the issue)
Channel Description: This is optional; we're using it to populate meta tags.
Next, set the Channel Posting Preferences:
We need to be able to put whatever HTML tags we want into our articles
We also don't want EE to turn any URL into a link. (It baffles us that EE still does this by default.)
Feel free to do other things, but these settings are all we need right now. The next time we need to set up an issue, we can duplicate the previous channel's preferences to save a few seconds of clicking.
Step Two: Custom Fields
This can get as complicated as you want once you've gotten the hang of Treesaver, but we've kept it fairly simple:
Excerpt: Again, this is optional, and we're using it for meta tags.
Content: The full text of your article. No pagination is required; Treesaver handles that.
Spillover Content: This is very optional. Even though ExpressionEngine doesn't set a character limit for textareas, MySQL does. That limit is about 65,000 characters which is a lot when you're talking about magazine articles, but not when you're talking about short stories, so drop any spillover text in here.
Figures: This is where you put images, videos, etc. Technically, there's no reason you can't just put these in the Content field with the text of your article, but since Treesaver places images how it likes based on the layout it renders (more on this later), it makes more editorial sense to split them out.
A note on markup: You don't want to let ExpressionEngine do your text formatting for you. EE's formatting options (either "Auto <br />" or "XHTML") don't play well with some of the HTML5 tags you'll probably be using (like figure). Until a better parser comes along, set all your fields' Default Text Formatting to "None" (the default is "XHTML"), and add p tags to your content fields by hand.
Step Three: Templates
Each template we'll be creating corresponds to a text file in the templates folder you got from GitHub. Just copy and paste.
article: A single article page.
index: This is our cover page. It pulls its content from a Global Variable (more on this in a moment).
resources: This is the heart of the operation; Treesaver looks at this file to determine how we want our pages to be assembled. (For more on this, visit the Treesaver wiki.)
toc: The Table of Contents.
All our templates are set to be of the type "Web Page," since they all have ExpressionEngine tags in them.
The name of the template group is essentially whatever we want to show up in our URLs; here it's the name of our magazine ("harpers"). If our domain name were already the name of our magazine, we'd probably name the group "issues" rather than be redundant.
Step Four: Snippets & Global Variables
We have one Snippet and one Global Variable (accessed through the Template Manager).
Snippet: analytics-id (optional) If this exists and contains your site's Google Analytics UID, the templates will automatically include the javascript that calls Google Analytics, as well as some extra scripting provided by Treesaver that passes article change events, allowing them to be tracked as page views.
Global Variable: cover-volume-9 (non-optional) This holds the contents of our cover page. Since each issue of our magazine will need its own cover, we will need to create a new variable for each new issue. As I'm sure you've sussed out, the variable's name needs to match the "Channel Name" of that issue's channel, preceded by "cover-". We've included a sample-cover.txt so you can see what ours looks like.
There are technical reasons why one is a Snippet and the other a Global Variable, but we need not discuss it here.
Notes on Images/Figures
Putting images into articles is one of the more counter-intuitive aspects of working with Treesaver. In order to achieve a fully flexible and responsive layout engine, it's often not possible to ensure that an image is adjacent to a related piece of text.
Let's look at a sample figure from our Harper's demo and break down the important bits:
Multiple image tags: There are two image tags here, one for large layouts and one for small ones. The small one is called first, but if the layout engine determines that the viewport is large enough to accommodate the larger version, it will swap it in.
data-sizes: This data attribute tells Treesaver how many columns this image is allowed to take up.
src / data-src: These attributes are where the system looks for the URI of an image. We use the data-src attribute for the images we don't want the system to load unless it determines it can accommodate them, e.g. large ones.
In the EEsaver templates, we've set it up so that images are only shown on every other page of an article. This is our way of preventing images from clumping up at the beginning of an article, leaving later pages image-free. You can edit the resources template to re-configure this scheme as you see fit.
And there you have it.
Treesaver is a really interesting beast with a lot of potential. There's a lot that can be done with it once you learn how to manipulate it.
One of the most important things to understand is that Treesaver doesn't allow for traditional approaches to page layout. Based on viewport size and other considerations, the framework lays out each article as it understands the constraints set up in the stylesheet and the resources template.
As a framework it's still brand new and not fully documented. We encourage you to give the wiki a good read, as well as take a close look at the examples on TreesaverJS.com before getting started. (Look and learn, but the designs aren't open source...)
We hope we've made getting started a little easier (actually we hope we've made it very easy), and we hope to see some new Treesaver sites very soon!
Licensing
Both these files and the Treesaver JavaScript framework are free, open-source projects and are made available under the MIT or GPLv2 licenses.
