Components

An Energine page is a set of components. A component is a PHP object that does one job — a menu, a text block, a news list, an editor — and returns its result as XML. The components of a page make one XML document, and XSLT turns it into HTML; see XSLT views.

From an address to a page

  1. The web server sends every address that is not a file to htdocs/index.php; bootstrap.php loads Composer's autoloader and the configuration htdocs/system.config.php.
  2. DocumentController takes the language from the address and creates the Document. The document finds the page by the address and the visitor's rights on it: no rights — 403, no page — 404. A page with a redirect address answers with a redirect (302) to it.
  3. The page's layout and content templates are joined into one structure, and each <component> in it becomes an object; see Page templates.
  4. Every component runs: it reads its action from the rest of the address and prepares its data.
  5. If the address has segments that neither the page nor a component used, the answer is 404.
  6. The document is built as one XML document, and the transformer turns it into the answer.

The classes

Every component extends Energine\share\components\Component; most use one of its descendants:

Class What it adds
Component a name and params; the state — the action chosen from the address — with its config and rights; build(), which outputs a <component> element
DataSet a data description, data, toolbars, JavaScript behaviours and a pager; the types list and form
DBDataSet a database table (param tableName) and its <table>_translation table for the languages; the columns become the data description
Grid the admin's editor of a table: a list with a filter, sorting and pages, forms to add and edit, deleting, ordering and CSV export

A DataSet builds its XML in prepare(): the data description — the config's <fields> matched with what loadDataDescription() returns — the pager, the data from loadData(), the toolbar and the scripts. A subclass usually overrides loadData(), which returns an array of rows or false, or the data description.

Params

A template places a component with its params; this is the home page's top news:

<component name="topNews" class="Energine\apps\components\NewsFeed">
    <params>
        <param name="title">TXT_TOP_NEWS</param>
        <param name="limit" type="hidden">5</param>
        <param name="showAll">1</param>
        <param name="active" type="hidden">0</param>
        <param name="template">news</param>
    </params>
</component>
  • class is required and is the full class name: the object is created as written, with no lookup by the short name.
  • name names the component in the page's XML; without it a random name is made.
  • Each class declares its params; an unknown one stops the page with «Компоненту передан неизвестный параметр.» (An unknown parameter was passed to the component).
  • a|b|c becomes a list, and so do several <param> with one name.
  • Every component knows state, rights, config and active; DataSet adds recordsPerPage, title and template; DBDataSet adds tableName, onlyCurrentLang and editable.

States and the config

The actions of a component are its states, described in its config, <Class>.component.xml. Part of the text block's:

<configuration>
    <state name="main">
        <javascript>
            <behavior name="PageEditor"/>
        </javascript>
    </state>
    <state name="save" rights="3">
        <uri_patterns>
            <pattern>/save-text/</pattern>
        </uri_patterns>
    </state>
</configuration>
  • An active component — param active; every Grid is one — needs a config. It takes the state whose <pattern> matches the rest of the address and calls the method <state>State() or <state>() with the pattern's placeholders as arguments. If no pattern matches, it keeps its state param, main by default.
  • In a pattern [name] matches one segment of the address and [any]/ the rest: /get-data/[sortField]-[sortDir]/page-[pageNumber]/. States listed first are tried first.
  • A state can set rights, its own <params>, the <fields> of its list or form, a <toolbar> of <control> buttons, <javascript> behaviours and the <translations> its view needs.
  • The config is looked up by the config param, then as <Class>.component.xml in site/modules/main/config/, then in the module's config/, then the parent classes' configs. A site config with the class's file name therefore replaces the core one.

Rights

Level Constant Caption
0 ACCESS_NONE «Права отсутствуют» (No rights)
1 ACCESS_READ «Только чтение» (Read only)
2 ACCESS_EDIT «Редактирование» (Edit)
3 ACCESS_FULL «Полный доступ» (Full access)

Rights are set for each page and group on the tab «Права на страницу» (Page rights) of the page form; a visitor's rights on a page are the highest of their groups. The starter has the groups «Администратор» (Administrator), «Гость» (Guest) and «Пользователь» (User).

A component runs only when the visitor's rights on the page reach its level: the rights attribute of its current state, or else its rights param. With neither, the level is the visitor's own, and the component runs for everyone who can open the page: give your own editors <param name="rights">3</param>. A component above the visitor's rights is left out of the page's XML.

Edit mode on a page needs full access.

Admin windows

<page address>/single/<component name>/<action> builds only the named component of the page. Grids open their forms to add and edit this way, in a window over the list.

A component of your own

The starter's Composer autoloader maps EnergineSite\ to site/modules/:

  • the class EnergineSite\main\components\Hello lives in site/modules/main/components/Hello.php;
  • a template places it by its full name: <component name="hello" class="EnergineSite\main\components\Hello"/>;
  • its config, if it needs one, is site/modules/main/config/Hello.component.xml;
  • its view is an XSLT template for component[@class='Hello'] in the site's stylesheets — see XSLT views.

Your first site builds one step by step.