Using File-Based Templates

By default LemonStand stores CMS objects (pages, templates and partials) in the database. If you enable the file-based templates mode, you can access your CMS objects as files. This enables you to use any text editor instead of the built-in LemonStand editor.

Enabling file-based templates

You can enable file-based templates on the System/Settings/CMS Settings page. Before you enable the file-based mode, you need to create an empty directory on the server. LemonStand will use this directory for storing CMS objects. The directory should be writable for PHP. It can be created anywhere on the server. It is not needed (and not recommended) the directory to be accessible from the Web.

After creating the directory click the Enable file-based templates switcher, enter the absolute path to your templates directory to the text field and click the Save button. When you enable the file-based templates mode, LemonStand copies all existing CMS objects to files. After enabling the file-based templates, you can open your templates directory and begin working with files. When file-based templates mode is enabled, you still can manage your CMS objects through the Administration Area. When you modify a CMS object in the Administration Area LemonStand updates its file automatically.

In the Path to the templates directory you can specify either an absolute path to your templates directory or use {APP} variable to create a path relative to your LemonStand installation directory. 

Please note that you can also configure the templates directory with TEMPLATE_PATH configuration parameter. This parameter overrides any value specified in the Path to the templates directory field.

File-based template mode and Theming

If you use Theming, you can combine theme resources directory and templates directory. Please read Themes article for details.

Disabling file-based templates

To disable the file-based template mode, go to the System/Settings/CMS Settings page and click the Enable file-based templates switcher. When you disable the file-based templates mode, LemonStand moves all content from files to the database.

Filesystem template layout

LemonStand creates the following directories in the template directory:

• pages - contains directories corresponding your website pages
• partials - contains files, corresponding partials
• templates - contains templates, corresponding templates

Partials and templates are represented with files in the corresponding directories. Pages are represented with directories in the pages directory, because each page requires more than a single file.

All files and directories corresponding to CMS object should be named on lower case.

Managing templates

In this section we describe page templates, which you can manage on the CMS/Templates page. Each template is represented with a file in the templates directory. File extensions depend on the option you chose in the Content file extension field of the file-based templates configuration form. If you create a new template file, LemonStand creates a new template CMS object automatically when you visit the CMS/Templates or CMS/Create/Edit Page pages in the Administration Area. If you create template files manually, you should follow the naming convention for the template files. Template file names should have the .htm extension and can contain only latin characters, numbers, dashes and underscores. 

When you create new templates in the Administration Area LemonStand automatically creates new files in the templates directory. You can edit the template file name with the File Name field in the Create/Edit Template form. File names should be specified without extension.

If you want to rename a template file, you have two options. First option is renaming the template file. Then LemonStand will detect the new file in the templates directory and create a new template CMS object. But in this case the old CMS object will remain in the system and you will need to delete it manually. The second option is renaming the template file from the Administration Area. Go to the CMS/Templates page and click a template which file you want to rename. Update the file name in the File Name filed and click the Save button. LemonStand will rename the file on the disk.

To delete a template, just delete the template in the Administration Area. When you delete CMS objects, LemonStand automatically deletes their files and directories.

When you click a template in the Administration Area CMS/Templates page and LemonStand cannot find the template file, it offers you to choose from two options - to delete the template CMS object, or to create a new template file. If you choose the second option, LemonStand creates a new template file using the template content from the database (if it does exist).

Managing partials

Managing partials is similar to managing templates described above, but with one exception. Partial names in the database can contain the : (colon) symbol, while file names do not support this character. LemonStand automatically replaces the colon symbol with the ; (semicolon) symbol when it saves partials to files. Thus, the shop:product_list partial becomes the shop;product_list.htm file. When LemonStand creates partials from new files, it automatically replaces semicolon symbol with the colon, so if you create the shop;product_list.htm file, LemonStand will create the shop:product_list partial. 

Managing pages

Each page represented with a subdirectory in the pages directory, which contains following files:

• page_[name].htm (or .php) - contains the page content. When the file-based templates mode is disabled edit the page content through the Content field on the Create/Edit Page form. The name of this file depends on the URL of the page. You can rename the file if you need, but its name should start with the page_ prefix. The extension of the file depends on the option you chose in the Content file extension field of the file-based templates configuration form.
• head_declarations.htm (or .php) - contains the page head declarations. When file-based templates mode is disabled, you edit this field through the Header Declarations field on the Head & Blocks tab of the Create/Edit Page form. The extension of the file depends on the option you chose in the Content file extension field of the file-based templates configuration form.
• pre_action.php - contains the PRE Action code. When file-based templates mode is disabled, you edit this field through the Pre Action Code field on the Action tab of the Create/Edit Page form.
• post_action.php - contains the POST Action code.  When file-based templates mode is disabled, you edit this field through the Post Action Code field on the Action tab of the Create/Edit Page form.
• ajax_handlers.php - contains custom page AJAX handler definitions.  When file-based templates mode is disabled, you edit this field through the AJAX Handlers field on the AJAX tab of the Create/Edit Page form.

If you have any content blocks defined on the page, they are represented with HTM files with the content_ prefix. For example, if you have a content block with the intro code, it will be represented with the content_intro.htm (or .php) file in the page directory. You can create new content block files manually. LemonStand will automatically discover them as soon as you render them on the page. Content block file names can contain only latin characters, numbers and underscores.

If your page contains any page blocks, they are represented with HTML files with the block_ prefix. For example, if you have the head block, it will be represented with the block_head.htm (or .php) file in the page directory. You can create page block files manually. LemonStand will discover them as soon as you render them on the page. Page block file names can contain only latin characters, numbers and underscores.

Unlike partials and templates, LemonStand does not create new pages automatically if it finds new subdirectories in the pages directory. However, it provides you with a tool which automates the operation. You can create new page directories manually, and when you visit the CMS/Pages page next time, LemonStand will suggest you that new pages are available with the indicator on the Create pages from files button on page list toolbar:

When you click on this button the new page opens, offering you to specify title and URL for each new directory:

File-based templates and page content blocks

If you added a content block to a page file, LemonStand will not know about it until it reload the page content from the file. Thus you will not see the Edit content menu item in the page content menu. To reload all pages from files, click the Reload pages from files button on the page list toolbar:

File-based template mode and CMS Export/Import operations

The file-based templates feature cannot replace the CMS Export/Import operations, because files do not contain all pages information. For example, in files you cannot specify a page URL, its security settings or visibility for different custom groups. If you need to copy CMS objects to another server, the best way to do it is the CMS Export/Import feature.

Next: Programming Pages
Previous: LemonStand Back-End
Return to LemonStand Back-End