Website design management


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.

<instruction locale="en_US"></instruction>
  <instruction locale="ru_RU"></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.

<support locale="en_US"></support>
  <support locale="ru_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:

      <requirement property="php" value=">=7.2" strict="true">
          <name locale="en_US">Minimum PHP version</name>
      <requirement property="" value="8" strict="true">
          <name locale="en_US">Minimum Shop-Script app version</name>
      <requirement property="phpini.max_exection_time" value=">60">
          <name locale="en_US">Maximum PHP script execution time</name>

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" "" >
  <theme id="default" system="1" vendor="webasyst" app="site" version="1.0.0">
    <name locale="en_US">Default theme</name>
      <file path="index.html">
        <description locale="en_US">Common layout</description>
      <file path="page.html">
        <description locale="en_US">Page content</description>
      <file path="sidebar.html">
        <description locale="en_US">Page navigation</description>
      <file path="error.html">
        <description locale="en_US">404 and other errors</description>
      <file path="default.css">
        <description locale="en_US">CSS for common desktop and laptop computers</description>
      <file path="mobile.css">
        <description locale="en_US">CSS for multi-touch mobile devices</description>

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 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.


return [
    'vars' => [
        'page.html' => [
            '$' => _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.