Webasyst framework provides a design editor for all publicly accessible web pages (frontend). Each app may also have its own design-editing functionality and utilize a different template engine other than Smarty. But, if Smarty is used, it is easier for a developer to use the built-in design editor.
Design themes
If an app has frontend, i.e. has its pages published on a website, then it is advisable to use design themes so that app users can customize the frontend app’s frontend pages. To achieve this, add the following parameter to app’s main configuration file wa-apps/app_id/lib/config/app.php
:
'themes' => true,
Then create a default design theme in wa-apps/app_id/themes/default/
directory.
A design theme constitutes a set of HTML/Smarty templates, JavaScript, CSS, image files, and the manifest file theme.xml
, all residing in one common directory.
Below is the list of mandatory parameters of the design theme manifest file theme.xml
:
- id: must be the same as the theme folder name
- app: app identifier (app_id), for which the theme has been created
- name: theme name, at least in one language
- files: list of files accessible for editing via the Site app
Developer info
In theme.xml
file you can add a link to a user manual explaining how to use the design theme. You can do it with a instruction
element. A link specified with that element will be displayed in design theme settings-editing screen.
To show different links to users with different locales, add several instruction
elements, each with a locale
attribute containing the corresponding locale name.
Example
<instruction locale="en_US">https://support.webasyst.com/26761/design-theme-hypermarket/</instruction> <instruction locale="ru_RU">https://support.webasyst.ru/26716/design-theme-hypermarket/</instruction>
You can also add a link to a website where a user can ask you a question, or an email address to send you a message. To do so, use a support
element. It supports the locale
attribute, too.
Example
<support locale="en_US">https://support.webasyst.com</support> <support locale="ru_RU">https://support.webasyst.ru</support>
System requirements
You can specify system requirements for a design theme to be taken into account when a theme is being installed via Installer. Add requirements to file theme.xml
by means of a requirements
element as shown in this example:
<requirements> <requirement property="php" value=">=7.2" strict="true"> <name locale="en_US">Minimum PHP version</name> </requirement> <requirement property="app.shop" value="8" strict="true"> <name locale="en_US">Minimum Shop-Script app version</name> </requirement> <requirement property="phpini.max_exection_time" value=">60"> <name locale="en_US">Maximum PHP script execution time</name> </requirement> </requirements>
Example of theme.xml file
Below is an example of a theme.xml
file for Site app’s default design theme for the Site app, residing in wa-apps/site/themes/default/
directory:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE theme PUBLIC "wa-app-theme" "http://www.webasyst.com/wa-content/xml/wa-app-theme.dtd" > <theme id="default" system="1" vendor="webasyst" app="site" version="1.0.0"> <name locale="en_US">Default theme</name> <files> <file path="index.html"> <description locale="en_US">Common layout</description> </file> <file path="page.html"> <description locale="en_US">Page content</description> </file> <file path="sidebar.html"> <description locale="en_US">Page navigation</description> </file> <file path="error.html"> <description locale="en_US">404 and other errors</description> </file> <file path="default.css"> <description locale="en_US">CSS for common desktop and laptop computers</description> </file> <file path="mobile.css"> <description locale="en_US">CSS for multi-touch mobile devices</description> </file> </files> </theme>
See also:
To ensure that frontend controllers and actions use design theme template files, specify the desired file name using this example in a controller or action PHP code:
$this->setThemeTemplate('page.html');
This method is available in app’s subclasses extending system classes waViewAction, waViewController, waViewActions, waLayout.
By default, design themes reside in wa-apps/app_id/themes/
directory.
When a user edits a design theme in the built-in editor, a copy of the theme is saved in wa-data/public/app_id/themes/
directory. That copy gets applied to website pages. Even if you install updates for the app or the design theme, the previously saved old design theme copy is still applied to website pages. To cancel it and to switch to the new design version, reset theme settings in the design editor screen—this will delete old design theme copy, and the original theme will be applied to the website until a user saves its settings again.
Cheat sheet
In design theme templates you can use virtually any functionality of the Smarty template engine including several variables and methods provided by the
Webasyst framework. For example, variable {$wa_theme_url}
is available, which contains the path to the currently enabled design theme, and the {$wa}
object provides several handy methods, which can be used in templates.
Variables and methods available within the template currently being edited are listed in the cheat sheet section to make design editing with Webasyst easy. The default list of cheat sheet’s variables and methods can be extended in app configuration file wa-apps/app_id/lib/config/site.php
as shown in this example. Here various variables’ descriptions are provided for different template files.
<?php return [ 'vars' => [ 'page.html' => [ '$page.name' => _w('Page name'), '$page.title' => _w('Page title (<title>)'), '$page.content' => _w('Page content'), '$page.update_datetime' => _w('Page last update datetime'), ], 'error.html' => [ '$error_code' => _w('Error code (e.g. 404)'), '$error_message' => _w('Error message'), ] ] ];
The keys of the main array’s items must be the names of template files, and their values must be arrays of custom variables and methods. If an app offers variables accessible in all design templates, then they must be described in an item with all
key instead of a file name.