Go to the new documentation
EN IT

Instructions

Instructions turn HTML pages into pages that adapt to context based on content entered in the admin. For example, a department HTML page will show different products depending on the department.

There are three instructions used to define the site structure:

<!-- .extend "layout.html" -->
<!-- .region "name" --> ... <!-- .end region -->
<!-- .include "include.html" -->

three instructions that manage content display:

<!-- .show variabile --> ... <!-- .end -->
<!-- .if variabile --> ... <!-- .end -->
<!-- .for variabile --> ... <!-- .end -->

the extract instruction:

[% variabile %]
[% variabile.attributo %]

and an instruction to display app snippets:

<!-- .snippet name --> ... <!-- .end -->

For each instruction you must indicate a variable it should operate on. Variables are available to display a product name, variables to display the department list, variables to determine if a user has logged in, etc. Variables vary based on the HTML page, and a complete list is available in the next chapter.

Inside the instructions, instead of the ellipsis, there can be any HTML code. In the case of the if and for instructions this HTML code can also contain other instructions.

A good way to understand how instructions and variables work is to experiment with the HTML page code provided with the software.

After the word end of each instruction you can write the name of the instruction itself:

<!-- .show variabile --> ... <!-- .end -->
<!-- .if variabile --> ... <!-- .end -->
<!-- .for variabile --> ... <!-- .end -->

By doing this you can make the code more readable and the software will perform an additional check on proper instruction closing.

Site structure

Building a complex site composed of many pages requires tools that speed up construction and later maintenance. Open2b provides the extend, region, and include instructions that are specifically meant for this purpose.

extend and region instructions

In every site, including e-commerce sites, there are pages that differ from each other but share the same structure. In Open2b the HTML code that defines the common structure for multiple pages can be placed in a dedicated HTML page, which we call the layout page. The individual site pages will extend a layout page by defining only the HTML code that differs for each page.

In the templates provided with Open2b, layout pages are found in the layouts folder, but nothing prevents you from placing them elsewhere, as long as it is inside the template folder.

Layout pages, in addition to the HTML code that defines the page structure, contain region instructions that indicate the points in the page where HTML code will be defined in the site pages that extend that layout page.

<!-- .region "body" -->

<!-- .end region -->

A region instruction can be placed anywhere in the layout page, as long as it has a unique name within the page.

Once a layout page is created you can use it as a model to speed up creating site pages. Just indicate the layout page to extend and write the HTML code for each region:

<!-- .extend "layouts/standard.html" -->
<!-- .region "body" -->
  <h1>Title</h1>
  <p>content</p>
<!-- .end region -->

Include instruction

include instructions, as a complement to layout and region, are a powerful tool that lets you further structure the source code of HTML pages to minimize repeated code and have a single point of change for visual updates across multiple pages.

While layouts are great for managing page structure, includes are ideal for sharing repeated code blocks in multiple pages, such as menus, the login form, and search.

Common code is saved in a file, which we call an include file, and then referenced inside HTML pages:

<!-- .include "includes/header.html" -->

In the templates provided with Open2b, include files are found in the includes folder, but nothing prevents you from placing them elsewhere, as long as they are inside the template folder.

show instruction

The show instruction displays dynamic content in the site page represented by the specified variable. For example, the following code, usable on a product page, shows the product image:

<!-- .show image --> <!-- .end -->

The following, usable on any page, shows the login button:

<!-- .show login --> <!-- .end -->

The following, usable on certain pages, shows a message informing the outcome of a user action such as completing the registration form:

<!-- .show statusMessage --> <!-- .end -->

if instruction

The if instruction lets you display HTML code based on a condition given by the specified variable. For example, the following shows a message if the user has logged in to the site:

<!-- .if isLoggedIn --> <em>Welcome</em> <!-- .end -->

If instead, conversely, you want to display a message if the user has not yet logged in, you can use the not operator:

<!-- .if not isLoggedIn --> please log in <!-- .end -->

The next chapter lists all markers grouped by the page where they can be used.

for instruction

Some variables represent a list of items, such as a list of departments or a list of products. To display items from this list, use the for instruction.

For example, the following displays a list of departments:

<!-- .for departments -->
  <!-- .show name --> T-shirts <!-- .end -->
<!-- .end for -->

If you want to show just one item in the list, indicate its index in parentheses:

<!-- .for departments(5) -->
  <!-- .show name --> T-shirts <!-- .end -->
<!-- .end for -->

The first index in the list is number 1.

For example, the menus variable represents the list of menus that can be managed in the admin. With the following code you can display menu 3:

<!-- .for menus(3) -->
  <!-- .show title --> Title <!-- .end -->
  ...
<!-- .end for -->

extract instruction

The extract instruction applies to the same variables as the show instruction but lets you extract only a part of the HTML code produced by show. Specifically, it extracts either the content of the HTML tag or a single attribute of the first tag.

For example, if <!-- show name --> <!-- .end --> generates the following code:

<a href="/custodia-per-cellulare">Custodia per cellulare</a>

then [% name %] extracts the content by removing the HTML tags:

Custodia per cellulare

while [% name.href %] extracts the value of the href attribute of the first tag:

/custodia-per-cellulare

This allows a more flexible use of show, which can be very useful in various situations.

As a further example of its effectiveness, referring to the previous example, if you want the page to open in a new browser window you can write:

<a href="[% name.href %]" target="_blank">[% name %]</a>

and the generated code will be:

<a href="/custodia-per-cellulare" target="_blank">Custodia per cellulare</a>

Unlike show, the extract instruction can safely be used inside a tag attribute, for example:

<html class="[% page %]">

The HTML code remains well-formed and any characters not allowed in an attribute are escaped.

snippet instruction

The snippet instruction is used to insert app snippets inside pages. To know which snippets you can use, consult the documentation for the apps installed in the store.