Integration with Site app

Contents...

System application Site provides a common and recommended design editor for all publicly accessible web pages (frontends). Each application may also have its own design-editing functionality and utilize a different template engine; however, if Smarty is used, then it is much easier for a developer to integrate his application with the Site, thus using its infrastructure for website building and further integration with other applications.

1. Design themes

If an application has a frontend, it is advisable to use design themes so as application users could customize the frontend within the Site application. To achieve this, you have to add the following record to the description file wa-apps/APP_ID/lib/config/app.php:

'themes' => true

and create your own default design theme (or several themes) in folder wa-apps/APP_ID/themes/.

A design theme constitutes HTML/Smarty templates, JavaScript, CSS, image files, and a manifest file theme.xml, all residing inside a common subfolder.

Below is the list of mandatory parameters of the manfest file theme.xml:

  1. id: must be the same as the theme folder name
  2. app: application identifier (APP_ID), for which the theme has been created
  3. name: theme name, at least in one language
  4. files: list of files accessible for editing via the Site app

Here is a theme description example of theme default for the Site app (theme is located in folder wa-apps/site/themes/default/):

<?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>
  <name locale="ru_RU">Основная тема</name>
  <files>
    <file path="index.html">
      <description locale="en_US">Common layout</description>
      <description locale="ru_RU">Основной шаблон</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>

Additional information:

To ensure that frontend controllers and actions use template files in a specific theme's folder and not in folder templates/, specify the desired template file in the source code of such a controller/action:

$this->setThemeTemplate('page.html');

This method is available in class instances extending base classes waViewAction, waViewController, waViewActions, waLayout.

New apps and themes installed automatically via the Installer or manually, are placed in folder wa-apps/APP_ID/themes/.

When a user edits a design theme in the Site app, a copy of that theme is created in folder wa-data/public/APP_ID/themes/, which remains non-affected during updates of the application and the orginal theme, thus insuring that custom design changes are never lost.

2. Cheat sheet

In application design templates you can use the full functionality of the Smarty template engine including several system-level variables and methods of the Webasyst framework. For example, variable {$wa_theme_url} is available, which contains the path to the currently enabled design theme, as well as object {$wa} with several handy methods.

All methods available within the current template (or static page) are listed in the cheat sheet of the Site app. The cheat sheet is an interface description tool created to make web designing with Webasyst more user-friendly. A developer may add custom variables and structures for his application's design templates. Declaring such custom variables is not a requirement, but it can be very convenient for a web designer.

The standard list of cheat sheet's variables can be extended in file wa-apps/APP_ID/lib/config/site.php (you need to create this file, if it does not exist in your applications' folder). Below is provided sample content of such a file adding custom variable lists for several templates.

<?php

return array(
    'vars' => array(
        'page.html' => array(
            '$page.name' => _w('Page name'),
            '$page.title' => _w('Page title (<title>)'),
            '$page.content' => _w('Page content'),
            '$page.update_datetime' => _w('Page last update datetime'),
        ),
        'index.html' => array(
            'title' => _w('Title'),
            'content' => _w('Content'),
            'meta_keywords' => _w('META Keywords'),
            'meta_description' => _w('META Description'),
        ),
        'error.html' => array(
            '$error_code' => _w('Error code (e.g. 404)'),
            '$error_message' => _w('Error message'),
        )
    )
);

The key of the array item should be the template file name, and its value is an array of custom variables. If an applications offers variables accesible in all templates, they can be described with the "all" key instead of the template file name.

3. Pages

A complete description of the integration between an application and the static pages management mechanism in the Site app is currently under development.