Introduction

Welcome! This is the documentation for our Template Editor and its markup language. Want to modify one of the default templates? Want to make your own? You're in the right place.

The Template Editor is used to created and modify template styles that descrbe how our users' menus appear on their sites, their facebook pages, on mobile, and in print. The templates are written in a custom markup language that makes it easy for them to look great for any menu, without the need for much customization. Based on HTML5, CSS3, and Javascript, Locu templates help our users' menus to shine.

The Template Editor and its markup language were created to make it easy to create a single, cohesive, beautiful theme that looks great across different media (web, mobile, Facebook, and print). Our markup language allows you to share styles across these media, but to customize the look as necessary.

Features

We've worked hard to build a system that's simple to learn, familiar to anyone who's developed for the web before, and easy to customize.

We're happy and honored to be working with you, and we can't wait to see what you come up with!

Getting Started

We provide an in-browser editor with real-time previews of the template you're working on. After signing up or logging in, visit the Design page. Pressing the 'Customize Design' button in the upper right of the page will bring up a sidebar with a list of templates. Select one and press the "Choose" button at the top of the sidebar. You'll see a list of controls for customizing the template — these are Editables, which we'll describe soon. At the bottom of the sidebar, click the "Edit Source" button. You'll see three tabs -- HTML, Style, and Images. These tabs respectively hold the template's structure, its style, and any additional content that you may be needed.

Markup — The HTML Tab

The markup in this tab describes the structure of the menu that you see in the preview, or on the business' web site, facebook page, or print menu. The markup here is based on HTML — you can create as many <div> s, <span> s, or other arbitrary HTML tags as you'd like. When the template is rendered on our users' websites this markup will be embedded directly, so keep away from <html>, <head>, and <body> tagss. Other than that, any HTML element is fair game.

The magic to the markup comes from Handlebars template tags, which allow for variable substitution and enough logic to make the template you build adaptable to different kinds of menus. Our markup language, which is built on Handlebars, takes advantage of Handlebars' expressions and its block helpers.

If you're new to Handlebars, or just want to get the most you can out of Locu's templating language, we recommend reading the Handlebars Documentation as a supplement to this guide. We fully support everything that can be done in Handlebars.

Template Expressions

Template expressions, or tags, allow for simple substitution of data into your template. {{<variableName>}} is look up in a mapping and replaced with the addociated value or an empty string (nothing). The mapping, or context, is provided by our server, and includes a description of each of the users' menus as well as their business. The context is described in greater detail below, but is simply a Javascript object mapping variable names to values.

For example, to display the address of any venue using your template, simply write:

venue_street_address would be looked up in the render context and the output would be the street address associated with the venue, such as:

By using these tags instead of hardcoding specific text, your template will work with any of our users' menus — we simply change the render context and the content changes entirely!

We've also added some special tags for additional control beyond the current context.

Special Template Tags

{{price}}

This template tag can be used as a standalone tag to display the price. It also accepts two arguments:

decimals=<integer> The minimum number of decimals to display in the price.
editable=<boolean> If true, expose controls so that Locu customers can change the number of decimals through an Editable.

For example, to show all prices with at least two decimal points and to let the Locu customer change this easily:

{{like}}

This template tag is used to show a "Like" button for Facebook templates. When rendered, it is replaced with an <a> tag that our custom Javascript uses to enable liking and disliking of a specific menu item. It accepts two arguments:

like_message=<string> The text to display in the tag when the user has not yet liked this item. Defaults to "Like".
unlike_message=<string> The text to display in the tag when the user has already liked this item. Defaults to "Unlike".

For example,

is rendered as:

The class of the element will be locu-like-btn if the user has not yet liked the item; once the user clicks the button, the class will be locu-unlike-btn.

{{powered_by_locu}}

This template tag will be replaced with an image of the Locu icon, which links back to our home page. If a Locu customer has an account that requires attribution (e.g., the free Basic Plan), this tag is required to exist within the template, so we recommend that you add it wherever you'd like. If a user whose account requires attribution selects a template which does not contain this tag, it will be automatically added to the bottom of the template.

The tag accepts a single argument:

color=<string> A string, one of "color", "white", "black", or "gray", which determines the color of the attribution image. The default is "color".

If the Locu customer using the template has an account that does not require attribution, the tag will render as an empty string. If the customer's account does require attribution, the tag renders as an <a><img/></a> structure.

{{photo_url}}

If a menu item has a photo associated with it, this template tag will be replaced by the URL of the photo. If the menu item does not have a photo, the result will be an empty string. Menu item photos only exist in the context of a Menu Item, so this tag will only work in that context, too. See the template context section for more information on context variables.

The photo tag accepts the following optional arguments; none are required.

width=<integer> The pixel width of the image at the URL that is returned. Our server will dynamically resize the image so that it is the specified width.
height=<integer> The pixel height of the image at the URl that is returned. Our server will dynamically resize the image so that it is the specified height.
saturation=<integer[0,100]> The saturation of the image, on a scale of 0 (desaturated) to 100 (normal saturation). Useful for creating more subtle designs.

We recommend that you include the width and height parameters so that your template will load as quickly as possible. If the image is going to be displayed at a certain size, it is a waste of resources to load the full-size image and then scale it down with CSS.

Embedding photos in widgets is not currently a feature of our free Basic plan. Although Locu customers using this plan will be able to preview a template that uses the {{photo_url}} tag, their photos will not display outside of the preview.

{{venue_logo_widget}}

Some templates may want to add a venue’s logo to the Print format. Although we provide the venue_logo_url context variable, if the user has not already uploaded a logo, we render a simple AJAX-based form to upload a logo directly from the design page. Once a logo has been uploaded, the tag is replaced by the following:

which is easily stylable. We recommend providing an explicit width and height to either the outer <div> or inner <img> so that our pagination code will function correctly.

Another nice benefit is that once an image has been uploaded, we add simple mouseover tools for changing the logo at any time.

Tips & Tricks

Block Helpers

In addition to variable substitution with tag expressions, Handlebars also supports block helpers, which allow for more advanced interaction with the rendering context. Examine our context example and you'll find that there are lists and nested data. To iterate through one of these lists, or to look up values in a nested context, you must use block helpers, which take the form {{#block <variableName>}}.

The {{#block}} tag is used like a "for-each" loop to iterate through nested contexts. For instance, with a context like:

To display the names of each of Locu's menus, we would use the following template:

When rendered, the final result would be:

The {{#block}} tag renders its contents once using the value of whatever variable is passed in. Each mapping in the result is used as the render context, which is what lets us write "{{name}}" and not something that might look like {{menus.<current>.name}}.

In the case that the variable used in the {{#block}} tag is nonexistent or an empty array, such as with a context:

The contents of the block are simply not evaluated. In this case, the result would be:

And in the case that the variable used in the {{#block}} tag is an object or mapping ({}), not an array ([]), the contents of the tag are simply rendered once, with the object or mapping used as the new render context. For instance, with the context:

we could render the type and description using either of the following templates:

Another useful block tag that we like to use is {{#if}}, which can be used to check conditions and the existence of variables. For instance, if we had a list of menu items:

and wanted to only display the "cheap" items, we could use the following template:

to get the following result:

Using the accompanying {{else}} tag, we could even show both types of menu items at once:

resulting in:

We've also added a small number of equality tags for comparing values inside the context. The <variable1> and <variable2> tags are strings. The variables are used as keys to look up in the current context; if they are not in the context, they are treated as Javascript literals. This means that strings must be passed in the format "'Example String'".

Tag Description
{{#equal <variable1> <variable2> True if <variable> is equal to <variable2>
{{#unequal <variable1> <variable2> True if <variable> is not equal to <variable2>
{{#lt <variable1> <variable2> True if <variable> is less than <variable2>
{{#lte <variable1> <variable2> True if <variable> is less than or equal to <variable2>
{{#gt <variable1> <variable2> True if <variable> is greater than <variable2>
{{#gte <variable1> <variable2> True if <variable> is greater than or equal to <variable2>

An example use is in our default template, "Clean", which doesn't use columns for subsections that contain less than 5 menu items:

In the case that the subsection has less than 5 menu items, this wil output:

Otherwise, in the case that the comparison is not true,

Template Context

As mentioned earlier, the trick to making your template work with many different types of menus is using tags and block helpers to display content that comes from a given context. The following schema and example should give you a rough idea of how the context is structured, and what variables are available:

Schema

Example

Example HTML Skeleton

Style — The Style Tab

The "Style" tab is where you'll craft the style of your template. Any standard CSS rule you may need is supported, and you can create as many CSS rules as you would like.

Built on LESS

Of course, we also offer something better than plain CSS — LESS. It's everything you've ever wished CSS could be, with nested styling, variables, mixins, and functions. Locu takes advantage of LESS to implement some of our cross-browser-compatible features like columns, tabs, and flows. See the section on Modern Layout Support for more information.

This section of the documentation assumes a familiarty with LESS — if you'd like to get up to speed, check out the LESS documentation page.

Here's a quick overview of some of the nicer features:

Of course, there are lots of other niceties, so please check out the official documentation!

Editables — Customization Made Simple

Although we allow everyone to customize the structure and style of their templates, some changes are simple enough that they shouldn't need to learn how. Using a special Handlebars tag, {{editable}}, Locu supports the definition of LESS variables that can be updated from automatically-generated controls. Instead of wasting your time on small changes, let business owners make small changes like:

Syntax

Arguments

Argument Name Description
name The label that appears above the controls to change the value. Every editable must have a unique name, or different Editables that share the same name will end up sharing values.
type The type of variable, used to set the interface shown to business owners to change the value. A full list of types exists below.
default The default value for this variable, used if the Locu customer has not specified a custom value instead. The type of value depends on the type argument of the Editable: see below for a more in-depth explanation.
alternate Only used for Editables with a type of boolean, the second value to choose from besides default.

Optional Arguments

Argument Name Description
medium Optional argument for Editables that are customizable per medium. These Editables appear in a special medium specific panel. The options for medium are "all", "facebook", "print", "web", and "mobile" and any combination of these options, such as "facebook, web" or "web, mobile, print"
menuSpecific Optional argument for print specific Editables. This argument can only be used if the medium argument defines the Editable to be print medium specific (so medium="print", medium="all", medium="print, web", etc). If this is set equal to "true", this Editable will be customizable per print menu
unit Optional argument for Editables that sets the unit of the Editable and adds it to the Editable control. Examples would be "in." for inches or "px." for pixels

Types

Editable Type Description Example default
number A unit-less number. Rendered as a text box with input validation ensuring that the value really is a number. default="15"
color A CSS color. Prefer hexidecimals for maximum cross-browser compatibility. Displays as an RGB color picker. default="#FFFFFF"
boolean A choice between two values. The alternate value is required to exist. Displays as a toggle between the two values. default="visible" alternate="none"
font-family The name of a font-family. Displays as a drop-down list of built-in Google Fonts. default="Vollkorn"
image An image's URL. Displays a preview of the image and a button for uploading a replacement. "default="http://mybusiness.com/images/header.png"

When the template is rendered, the {{editable}} tag will be replaced with the default value or a value chosen by the Locu customer through the visual controls.

The easiest way to use an Editable is to store the result to a LESS variable which you then use throughout your template. Here's an example of an editable allowing for finer control of the font color of a template:

Because the {{editable}} tag is simply replaced with the value, you can also use them inline with the styling without storing to a LESS variable. You might do this if the value is only used once. Here's the same example, written with an inline editable:

Editable tags also work in the HTML tab, although most of the time it makes more sense to use them along with your CSS. Some of our special tags take advantage of this to create editables as part of their use.

Medium Specific Editables

Medium specific Editables take the default value provided in the Editable construct. These Editables appear in a panel under the heading of the medium name and only appear for the medium currently being previewed. The Editables can be updated to different values for each medium such that, for example, the facebook menus all have blue text and the web menus all have 3 columns instead of 2.

Ideally, the LESS variable storing the Editable value or the CSS rule using the Editable should only pertain to the same media as the Editable. For example, a page width variable that is only defined for print should not be used on CSS rules that pertain to the web version of the menus. If this general guideline is broken, the Editable will just return the default value.

Menu Specific Editables

Menu specific Editables also take the default value provided in the Editable construct. These Editables are only menu specific for print menus. These are ideal for Editables such as page height and width or number of columns which commonly differ for dinner menus versus drink menus or dessert menus.

These Editables and all the CSS rules using these Editables must be written inside of a menus block that creates CSS rules specific to each menu class name. This example block would be put in the LESS section.

Additionally, for menu specific Editables to be functional, the HTML template must include a special data variable on the locu-menu div. This data variable is the data-separator variable which defines the menu class name for the pagination algorithm.

Responsive Design — Targeting Different Media

Our templates are designed to "just work" across four different types of media: web, mobile, Facebook, and print. Each of these media has a specific class name that is applied to the outermost element of the template; by targeting these class names, it becomes simple to customize the template's style to display in a format more friendly to the medium.

Medium Wrapper's CSS Class Name
Web .locu-web-menu
Mobile .locu-mobile-menu
Facebook .locu-fb-menu
Print .locu-print-menu

Using LESS, it's easy to target rules to these specific classes. See our example LESS skeleton below.

Example LESS Skeleton

Additional Resources — The Images Tab

This tab is where you may upload any additional images that you'd like to use in your template. Once a file is uploaded, you will see a small preview and a text link to that file on our servers.

Any file uploaded here is saved to our servers, and is guaranteed to be accessible at any time. Once the upload is complete, the URL will appear the in a text box. It is simple to copy and paste this URL for use in your template. See below for some examples.

Examples

Assuming that the file you uploaded was given the url "https://locu.com/imageurl.jpg", here are some example uses:

HTML

Style

As described in the Editables section, the {{editable}} tag with type of image will create an image preview and uploader so that restuarant owners can replace this image with one of their own.

Tips & Tricks

Modern Layout Support

Menu design, like all forms of print design, rely heavily on sophisticated uses of layout. As a company, Locu is committed to bringing the best that print design has to offer to your printed menus. We are proud to announce industry-leading support in cross-browser column compatibility, allowing designers show any or all of their menus in as many or as few columns as they desire. We are also announcing the most powerful and flexible print menu generator in the industry, with custom page break tools and region-based flow of your layouts allowing the on-demand production of beautiful print menus based on your CSS designs.

All of these tools are forward compatible, being built to best match specs for layout as they are developed and support by the internet's best browsers. All of these tools are backwards compatible as well, with full cross-browser support for columns down to IE7 and the template editor available to print designers down to IE8. Businesses using Locu menus will always have the best layouts that the web - and print - has to offer.

We believe layout support represents some of the most innovative and powerful technologies that Locu - and indeed, all of modern web design - can offer. We think some of the best gains for both business owners and designers can be found here, and we strongly encourage you to give it a try. We're here to help you with it, too: if you have any trouble with the tools in this section, drop us a line at support@locu.com. Throw "I Love Layout" in the subject line and we'll give you priority support. :)

Columns

Part of the CSS3 spec is a new CSS attribute: columns. A powerful new feature, columns allow you to quickly and easily lay out your html into vertical columns. This is quite nice for menus and pricelists, which are traditionally laid out in columns on paper but are oten forced into simpler, single column displays on the web.

Like most new things new and fancy, the columns attribute is currently not well-supported: only Firefox, Chrome and Safari, and IE 10 implement parts of the spec, and no browser implements all of it.

Because the columns attribute is not cross-browser compatible, we provide a LESS mixin to fill in the gaps: .-locu-columns().

.-locu-columns will let users with newer browsers see columns natively, but will fall back to a Javascript implementation for users on older browsers (we officially support IE7+). And of course, we've made sure it works great for your print menus as well.

Syntax

Argument Name Description Default Value Example Value
<columnCount> The desired number of columns into which the styled element will be broken. auto 2
<columnWidth> The desired width of the columns that will be created. auto 500px
4in
<columnGap> The desired size of the space between the columns that will be created. 1em 40px
1.5em
<columnRule> The rule or border to draw between created columns. Uses the exact same syntax as a border rule. none 2px dotted black
Heads Up! .-locu-columns and overrides the column-width, column-height, column-rule, column-gap, and list-style-image attributes — avoid using them if possible.

Usage

.-locu-columns() will work on any arbitrary container, and divvy its contents up into the specified number of columns. It works just like the CSS columns style, only with better cross-browser support. Apply it to an element whose contents you would like to columnize. For instance, to display all of this text:

in two columns, it's as simple as:

Tips & Tricks

Regions

Our print menus are powered under the hood by a simple implementation of CSS Regions. CSS Regions allow content to flow from a single source element throughmany different output elements, such as pages or columns. When the content has filled one output element, it "flows" to the next. This is a very powerful typestting tool, but it is still unsupported by most browsers. At the time of writing, no modern browsers support it by default.

We've implemented a small subset of the specifications by adding support for a single "flow" (named flow) that can be used to send content from your menu to our pagination software. The flow is created with the .-locu-flow-into() and .-locu-flow-from() LESS mixins, and can only be used within the context of a special {{#block pages}} template tag (which loops, creating pages for content to fill).

Syntax

Heads Up! .-locu-flow-into and .-locu-flow-from override the background-attachment and -ms-interpolation-mode attributes — avoid using them if possible.

Check out the example template style for an example of how we use this on our default template.

Pagination Control

Another core tool for making beautiful print menus with Locu is controlling how content is broken up from page to page. .-locu-break-before() and .-locu-break-after() are LESS mixins that we've written to this end. For example, use these rules for ensuring that menu names always start on new pages, or that section headers don't start at the bottom of a page.

These mixins provide similar functionality to the existing CSS attributes page-break-before and page-break-after, with the benefit that they're guaranteed to work in all browsers and are perfectly compatible with out print layout engine.

Syntax

.-locu-break-before():

.-locu-break-after():

Heads Up! .-locu-page-break-before and .-locu-page-break-after override the page-break-after, page-break-before, and -moz-binding attributes.

Custom Fonts and Typography

Locu's template language includes support for arbitrary fonts, as well as other resources. In the HTML Tab, simply add a <link> or <style> element linking to the resource that you'd like to use. For instance, to load a custom Google Font like Open Sans, one might write:

Then, in the Style tab:

Please be aware that these external resources are not guaranteed to be loaded correctly in the PDF menus that are generated, even if they load correctly in the preview. This is a current limitation of the software that we are working hard to fix (we do however support a large number of builtin fonts — see below).

Built-In Fonts

By default, Locu supports a broad range of Google Web Fonts. When using a font-family {{editable}} tag, Locu customers will be given a list of these fonts from which to choose among. The necessary font files will be loaded automatically for the font that is chosen. For example, if we wanted to make the section headers of a template default to Vollkorn, but allow the user to change it if necessary:

All of the Google Web Fonts we include are free to use for commercial and non-commercial purposes. Here is the list of fonts we support by default:

Template Submission

Locu will be adding support for directly accepting community created templates to the Locu template library. In the meantime, we are in an invite only phase for template design submissions. If you are interested in participating, please contact us at and include your portfolio.

Terms of Service

Use of menus created by the Locu template language is governed by Locu's Terms Of Service. In addition, obscuring, eliminating or hiding the "Powered by Locu" badge in any way without Locu's express consent (for instance, through purchase of a Premium account) is a violation of the terms of service.