Helpers

Contents...

Each application can provide its own methods to add extra content to frontends of other applciations. For example, some analytical application may use such methods to display a chart on website pages.

When designing your own Webasyst application, it is convenient to group methods to be used in frontend templates in a special helper class. The helper class should be placed in the wa-apps/[app_id]/lib/classes/ directory, the file class should be named according to rule [app_id]ViewHelper.class.php, and the class name should be constructed using the following pattern: [app_id]ViewHelper.

For example, for some application with stats ID, the helper file should be located at wa-apps/stats/lib/classes/statsViewHelper.class.php and have the following structure:

<?php
  
class statsViewhelper
{
  
    public function getChartHtml()
    {
        …
        return …;
    }
  
}

To display some chart using the HTML code generated by method getChartHtml() from the above example, call that method in a frontend template as shown below:

{$wa->stats->getChartHtml()}

Custom template helpers

In addition to existing helpers described in the "Cheat sheet" section of the built-in design editor (read more about it in the article about integration with the "Site" application) and the ability to write own plugins, the framework also offers the option of creating custom helpers (functions) available in design theme templates.

The basic difference of a helper from a plugin is that a helper is not limited by existing hooks to be embedded in a template. A helper also usually has more limited functionality (unlike helpers, plugins can offer their own backend setting screens and can store data in their own database tables). You can regard helpers as "mini plugins".

Custom helpers are accessible only within frontend templates of the application for which they have been written.

To write your own helper for some application, create custom class file with the name of the form [app_id]Custom.class.php inside directory wa-apps/[app_id]/lib/classes/ of that application. For example, custom class file for Shop-Script must be located at wa-apps/shop/lib/classes/shopCustom.class.php. The class name must be created in accordance with rule [app_id]Custom, e.g.: shopCustom.

Custom class name (and its filename) may be different, not necessarily matching the above rule. Use of the Custom identifier suggested in this rule ensures that no standard class with the same name is likely to appear in the future and thus prevents eventual naming conflicts. For convenient arrangement of custom helpers, you may create multiple classes named with this principle taken into account (e.g., shopMyHelper or shopExtraSnippets).

Helpers are declared as public static methods of the custom class.

Custom class files are not affected by updates installed via the Installer.

Below is provided an example of a custom class file containing declaration of sample method someHelper() to be used in storefront templates of Shop-Script:

<?php

class shopCustom
{

    public static function someHelper()
    {
        ...
        return ...;
    }

}

To call method someHelper() from this example, use the following syntax:

{shopCustom::someHelper()}
You may need to clear cache in Installer for your custom helper to work correctly.