Anatomy of a theme
One of our primary goals with Easy Eatery is to ensure that our website builder is as developer-friendly as possible. To that end, we've struck a balance between ease of use and features to make it easy to modify an existing Easy Eatery theme or create a new one.
With Easy Eatery, you don't need knowledge of any CSS or JS frameworks. Nor do you need to learn a complex templating language — you only need a decent knowledge of HTML, CSS, and JavaScript.
Theme structure
Easy Eatery themes all share the same file structure. All of our themes group files into five top-level directories, depending on their file types:
| Directory: | Description: |
|---|---|
| /css/ | Contains all style sheets associated with your theme. |
| /email/ | Contains email templates. |
| /html/ | Contains the HTML files for each component in your theme. |
| /js/ | Contains all JavaScript files associated with your theme. |
| /svg/ | Custom SVG assets can be stored in this directory. |
Understanding component types
Both the CSS and HTML directories within your theme have subdirectories, which group files based on the type of component they are associated with.
| Subdirectory: | Description: |
|---|---|
| /base/ | CSS only. Stores files that are common to the entire theme, such as button and typography styles. |
| /blog-blocks/ | CSS and HTML. Stores files associated with post builder blocks. |
| /layouts/ | HTML only. Stores files that define the overall layout for different page types. |
| /page-blocks/ | CSS and HTML. Stores files associated with page builder blocks. |
| /panels/ | CSS and HTML. Stores files for key components within your theme, such as the main header and footer. |
| /snippets/ | HTML only. Stores small snippets of HTML, used within HTML blocks or panels on the website. For example, a snippet of HTML for a single blog post tile, within block that displays a list of blog posts. |
Theme.xml
Within the root directory of your theme is theme.xml. This file stores the general configuration of your theme, including both the name and description of your theme, author information, plus any options defined for the theme you're editing.
These options are used within Easy Eatery's theme customiser to allow site owners to make 'no-code' customisations to their website's appearance.
The execution of Ruby, ASP or PHP code within your theme files is not supported in Easy Eatery. Any server-side code added to your template will be output as plain text. If you want to enhance the functionality of your theme, we recommend using JavaScript or jQuery to achieve this.
Outputting CMS-driven content.
Easy Eatery gives you complete control over your website's source code and allows you to hard-code content as you wish. But you might be wondering, how do you get user-defined content from the control panel into the website? To do this, you use variables.
What are variables?
Variables are text snippets placed within your template's HTML files which are replaced with CMS-driven content when someone views a page on your website.
Every HTML file within your theme can access many global variables, but each of these files typically have their own unique set of variables.
For a complete list of variables, please refer to our theming docs.
How do I use variables?
You can access the content associated with a given variable by adding the variable tag into your theme file. Variable tags are created by wrapping the name of the variable within curly brackets, with an '@' symbol placed before the variable name, for example:
{@globals.site.name} or {@button}
Advanced variable usage
Easy Eatery supports a number of parameters that you can add within variable tags to modify how the content of a variable is rendered:
The "tag flag"
The tag flag delcares that the specified variable should be wrapped within the indicated HTML tag when output. Tag flags are formed by two dashes, followed by the tag letters and must be added after the name of the variable, but separated by a space.
Example usage: {@globals.site.name --h1}.
<h1>Easy Eatery</h1>In the above example, the name of the website would be output, wrapped within a Heading 1 tag.
In the scenario where the contents of a variable has no value, nothing would be output.
Tag flag quick reference:
| Flag | Rendered HTML tag |
|---|---|
| --div | <div> Div element |
| --span | <span> Span element |
| --h1 | <h1> Heading 1 |
| --h2 | <h2> Heading 2 |
| --h3 | <h3> Heading 3 |
| --h4 | <h4> Heading 4 |
| --h5 | <h5> Heading 5 |
| --h6 | <h6> Heading 6 |
| --p | <p> Paragraph |
| --ul | <ol> Numbered list |
| --ol | <ul> Bullet list |
| --li | <li> List element |
| --strong | <strong> Strong (bold) element |
| --figcaption | <figcaption> element for use within <figure> elements |
Attribute flags
There are also two supported attribute flags. These work in a similar way to tag flags however instead of wrapping the variable in a HTML tag, these tags wrap variables in the markup required to add an attribute to a HTML tag.
Example usage: {@globals.site.url --href}.
href="https://easyeatery.co.uk"Unlike tag flags, attribute flags cannot be used with the css class, ID or date formatting parameters.
| Attribute tag | Description |
|---|---|
| --href | Wraps the variable output in a "href" attribute. For example: href="https://easyeatery.co.uk". |
| --aria-label | Wraps the variable output in a "aria-label" attribute. For example: aria-label="Easy Eatery". |
CSS class parameter
This parameter has the effect of appending the specified CSS classes within a class attribute to the output of the variable. You can add multiple classes within this parameter, simply write the classes you want them to appear on the page - any invalid characters will be removed.
Example usage: {@globals.site.name --h1 [class:your class-here] }.
<h1 class="your class-here">Easy Eatery</h1>ID parameter
This parameter has the effect of appending the specified ID within an ID attribute to the output of the variable. Any invalid characters, including spaces will be removed.
Example usage: {@globals.site.name --h1 [id:example_id] }.
<h1 id="example_id">Easy Eatery</h1>Class and ID parameters are designed for use as an extension of the tag flag. In order to use them you MUST also specify a tag flag within the desired variable. Failure to do so will not cause any errors, it will simply be that the parameters are discarded.
Putting it all together
You can use both class and ID attributes at the same time, for example:
{@globals.site.name --h1 [class:your class-here] [id:example_id] }
<h1 class="your class-here" id="example_id">Easy Eatery</h1>Formatting dates & times
For any template variables that represent dates (such as blog post publish dates), it's possible to use the datetime formatting parameter to control how the dates are formatted when rendered. For ease of adoption, we've decided to follow PHP's DateTime formatting practices.
Example usage: {@post.date [dt-format:F jS Y] }, which would be rendered as January 22nd 2023.
This parameter can also be used with the tag flag, as well as the CSS class and ID parameters.
Cascading style sheets (CSS)
To ensure Easy Eatery themes are easy to maintain, we provide a separate stylesheet for each component in your theme.
Every style sheet is minified when loaded into the website but will retain all comments and indentation when viewed in the theme editor.
While you may load CSS files on your website individually, we strongly recommend using the main style sheet, style.min.css, as this file can merge all stylesheets into a single, minified file.
JavaScript and jQuery
Within the /js/ directory in your theme, you'll find several .js files. These files each contain code for a specific part of your theme.
As with stylesheets, each .js file is minified when loaded into the website, and can be loaded individually, however it is best to rely on the file app.min.js, which can merge all JS files into a single, minified file.
While many Easy Eatery themes use jQuery to enhance the user experience and provide certain functionality, jQuery is not required and if you're creating your own theme and don't want to rely on jQuery, you can safely remove the library from the theme, which can be found in the file html/panels/site-js.html.