Plain Text - The blog of Plain
- Home
- Projects
- Blog
- Contact
DRAFT: Barley Template Documentation
This document should now be considered out-of-date. Please refer to the main Barley website for any updates to this document.
May 9, 2013
The following is a work-in-progress document that is subject to change at any time. But we wanted to share how we're setting up templates as quickly as possible since so many designers and developers around the globe have asked to begin developing Barley templates.
Template Structure
Barley templates are created using only HTML, JS, CSS as you normally would develop to work in-browser. Here is a typical Barley template structure.
- /styles
-/javascripts
-/images
- index.html
- about.html
- blog.html
- post.html
- favicon.ico
/styles - Store CSS files in this directory. Surprised?
/javascripts - Guess what? JavaScripts go in here. No Celine Dion MP3s allowed.
/images - All flavors of images; png, gif, jpg, svg.
index.html - Main home page.
about.html - Any new pages should be named pagename.html. pagename becomes the URL when the site is live E.g. /about
blog.html - If you're including a blog in your template (you don't have to) simply include a blog.html (more information below)
post.html - This would be where the individual post would be layed out.
favicon.ico - Cute icon for your page. We recommend kittens.
Using frameworks
You can feel free to use any frameworks you'd like in your templates. We like jQuery, Foundation, and a few others but we've decided not to limit anyone with the frameworks they'd like to use. So go crazy and we'll adjust to your needs.
Editing with Barley
As the designer of your template you can choose what can and cannot be edited about your template's content. So if you'd like someone to be able to edit the title of their About page, they can. But if you'd rather not allow that, don't. Here is how you make an element in Barley able to be edited.
Barley reads HTML attributes on all elements to decide two main things: 1) Is the element able to be edited? and 2) What tools can the author use to edit those elements? Here is the HTML we use to determine that showing an example H1 tag.
h1 data-barley="main_title" data-barley-editor="mini"
In this example Barley is showing that the H1 tag on this page is able to be edited by the author using Barley's mini editor. The main_title value on the attribute is used to track changes to that tag for a specific domain. In other words, every tag that is able to be edited on your template must have a unique ID. We'll get more into this in a second.
Barley Editor Types
There are several editor types that are available currently and we hope to extend this list as the needs of our customers and template designers become more clear.
- mini - No tools at all. Only the text can be changed.
- simple - The text can be changed. Emphasis can be added using both bold and italicized text.
- plus - In addition to the above: links, text-alignment (center, left, right), lists.
- advanced - In addition: image uploading.
- blog - All tools are loaded.
We'll have more details about the editors including screenshots, videos, and much more coming soon. A lot of how this all works is still being designed, developed and tested.
Repeatable Sections
From time-to-time a section of a template needs to be repeated such as a blog's index page or a search result page or a photo gallery. For this we've created repeatable sections and here is how they work.
1 2 3 4 5 6 7 |
view raw
barley_repeatablesections
This Gist brought to you by GitHub.
Yes, it is as simple as adding a HTML comment to your document and you can have a blog index! It works pretty great for anything you'd like to be repeatable. Just change the blogpost keyword to something else, as you see in the example above.
Template Tags
Individual template tags to be used within repeatable sections are generally available. So inside of a repeatable section for a blog post you may have the following:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
view raw
Barley_blogindex
This Gist brought to you by GitHub.
Here are the template tags that are pre-built into Barley:
Keyword | Attribute Value | Description |
---|---|---|
%BODY% | blogpost_body | The entire blog post body |
%EXCERPT% | N/A | The first two paragraphs of the body |
%ID% | N/A | This will output the actual post id and is not used with the data attribute |
%PUBLISHED_ON% | data-barley-publish-post="%ID%" | The data/time the post was published or 'Not Published' if not published yet. You will also notice you do not use a typical data-barley attribute. Set the attribute `data-barley-publish-post="%ID%"` to the published markup. This will tell Barley to publish a post with a click of a button. (To be improved soon) |
%TITLE% | blogpost_title | The title of the post |
%URL% | N/A | The permalink of the post |
We'll be releasing more information about keywords when we update this document again. Please keep watching this document.
Default Template Data
When you ship a template you want to ship it in its best light. You want the first experience with that template to be one that truly shows off all of the template's best qualities. Or, if you're building a template for a very specific market or for a specific business, you may even have recommended content for the customer to use. For these cases we've created something special.
When we receive your template Barley will import your HTML, CSS, and JS and turn it into a real Barley-powered web site. It will also save the content that you included with your template as "default template data" that the customer can always revert back to.
Good examples of how this could be used might be with professional service descriptions. Nearly all accountants provide a payroll service to their customers. What payroll is, how it works, and how it can be used can generally be described for the customer of your template and they can choose to use, edit, or rewrite that content using Barley. Or, if they've written their own definition and are not satisfied with it later - they can go back to the default template data that you've provide. We'll explain how this all works in an upcoming document.
How to submit a theme
We've had so many designers and developers email us about how to send in a theme. And we couldn't be more excited to see what kinds of themes are created. So please create your themes in HTML, CSS, JS and zip them up and send them to us at barley@plainmade.com
Help us improve Barley
If you think any of this can be done better we want to hear from you! Send us your feedback to barley@plainmade.com
This document last updated: Friday, February 15, 2013 at 4:45 EST
Would you like to receive updates from Plain? Subscribe to our mailing list:
for its contents. This is a safe-cache copy of the original web site.