DGS Templates (WEB Mode)

A Data Grid Store (DGS) has two modes. In the api mode, the DGS returns JSON. In the web mode, the DGS renders HTML from templates. The web mode is the default.

This page tells you:

• which templates the DGS uses
• where the DGS looks for a template
• how to replace a template without a change to the default theme

Related pages:

• Templates describes how a template works.
• Custom DGS Fields describes the templates of a field.
• Theme package contains the default DGS templates.

The view object

Each store has a view object of the class StoreView. It extends Template. The actions of the store render their templates with this object.

In a DGS template, $this is the StoreView.

<?php
/**
 * @var StoreView $this
 * @var Store $store
 */
?>
<div id="orders-<?php echo $store->getIdent(); ?>">
    <?php echo $this->fetch('store/view/list/template.phtml'); ?>
</div>

A plugin template and a DGS template are different objects. A DGS template does not have the variables that the plugin assigned.

Where the DGS looks for a template

The StoreView looks in these directories, in this sequence. It uses the first file that it finds.

Important facts:

• The templates directory of the plugin is the last step. Thus a file plugins/<Name>/templates/store/list.phtml has no effect: the theme or the Theme package has a file with this name, and the DGS finds that file first.
• The plugin directory gives the DGS a template that steps 1 and 2 do not have, for example a template that your template includes with fetch().
• A store that has no plugin has only steps 1 and 2.
• The DGS does not look in the project templates directory (Core::OPTION_TEMPLATE_PATH).
• Each fetch() in a DGS template uses the same lookup. Thus you can replace one small part.
• You can add directories to the lookup of one store. See Replace a template for one store.

The templates

All default templates are in the templates directory of the Theme package.

List

Variables of store/list.phtml:

Forms

Variables of a form template:

A listener for Store::EVENT_ON_FETCH_FORM can change each of these variables before the template gets them. See DGS events.

The form template of one action

Before an action renders its form, it looks for a template with the action name:

Example: the edit action uses store/form_edit.phtml, if a lookup directory has this file. This is how store/form_remove.phtml works.

Fields and filters

A field does not use the lookup of the StoreView. A field renders its templates from one directory. See Custom DGS Fields.

How to change the look of a DGS

First, find out if you need a template. Most changes do not need one.

Replace a template only when the other methods are not sufficient. A replaced template does not get the corrections of later framework versions.

Replace a template for one store

Add a directory of your plugin to the start of the lookup of the store. Do this after you make the store and before onRequest().

public function onDisplayOrders(Response &$response): bool
{
    $store = $this->createStoreInstance('orders');

    $view = $store->getView();

    $paths = $view->getTemplateLookupPaths();
    array_unshift($paths, $this->getPluginTemplatePath().'dgs/');
    $view->setTemplateLookupPaths($paths);

    $store->onRequest($response);

    return true;
}

Then put the template in that directory, with the same relative path as the default template:

plugins/
`-- Orders/
    `-- templates/
        `-- dgs/
            `-- store/
                |-- form_edit.phtml                 the form of the edit action
                `-- view/list/parts/
                    `-- row-actions.phtml           the action buttons of a row

• The DGS uses your file for this store only.
• The DGS uses the default file for each template that your directory does not have.
• Replace the smallest part that contains the change. Do not copy store/list.phtml to change the row buttons.
• Start from a copy of the default template. Keep the CSS classes and the id attributes. jimbo.js and the theme use them.

Replace a template for all stores

There are two methods.

In your own theme. Put the template in the templates directory of the theme, with the same relative path. This is step 1 of the lookup.

themes/
`-- mytheme/
    `-- templates/
        `-- store/
            `-- list.phtml

Use this method only in a theme that the project owns. Do not add files to a theme that comes from a package or a submodule (for example SmartAdmin).

With an event. Add a lookup directory to each store when the framework makes it. This method needs no change of a theme. Put the listener in the init.php of a plugin:

$this->addEventListener(Core::EVENT_ON_CREATE_STORE, function (FestiEvent &$event) {
    $store = $event->getTargetValueByKey('store');

    $view = $store->getView();

    $paths = $view->getTemplateLookupPaths();
    array_unshift($paths, __DIR__.'/templates/dgs/');
    $view->setTemplateLookupPaths($paths);
});

A different view class

The store option store_view (Store::OPTION_VIEW_MODEL) replaces the view object. Use it when a project needs a different render logic, not only different templates.

Rules

• Do not edit the templates in vendor/ or in a theme that comes from a package.
• Use schema attributes and events before you replace a template.
• Replace the smallest template part.
• Keep the CSS classes of the default templates (b-db-table, e-db-action, f-db-form, e-input). The JavaScript of the DGS finds the elements with them.
• Use HUI components in your templates. Do not write the HTML of buttons and dialogs again.