Widget development

Tutorials » #3. Development of "Shop statistics" widget for Webasyst dashboard

This guide contains a step-by-step description of how a Shop-Script 6 app based Webasyst dashboard widget is developed.

Widgets for other apps and system widgets are developed in a similar fashion. App widgets are created in directory wa-apps/[app_id]/widgets/ of the corresponding app, and system widgets are created in framework directory wa-widgets/. Read more about widget development basics.

If you are planning to publish your widget in the Webasyst Store, then we recommend you to take the software development requirements into account.

1. Developer mode

Before you proceed to the development, ensure that the developer (debug) mode is enabled in your Webasyst account configuration. In this mode any caching is disabled to facilitate debugging. You can enable developer mode in the settings of the Installer app or in file wa-config/config.php as shown below:

'debug' => true,

2. File structure

Create a convenient ID for your widget. An ID may contain basic Latin letters, digits, and underscores. For the simple widget described in this article we shall use ID stats; this widget will display common statistics of the online store: the total number of products, categories, images, customers, and orders.

Since this is an app widget, we shall create its subdirectory with widget's ID in the directory with app's files: wa-apps/shop/widgets/stats/. Paths to other files will shown relative to this widget root path for the sake of simplicity.

In this example, we describe manual creation of the widget file structure. For real development, we recommend using console command php wa.php createWidget APP_ID WIDGET_NAME.

1. Create main widget configuration file lib/config/widget.php:

<?php

return array(
    'name' => 'Shop statistics',
    'size' => array('2x2', '2x1'),
    'img'  => 'img/stats.png'
);

2. Upload widget icon file stats.png (we specified this file name in configuration file widget.php) to directory img/.

3. Create main PHP class file lib/shopStats.widget.php with class shopStatsWidget extending system class waWidget:

<?php

class shopStatsWidget extends waWidget
{
    public function defaultAction()
    {
        //
    }
}

4. Complete the file structure creation by adding HTML template file templates/Default.html, which will display data prepared by the main PHP class.

3. Main widget class & method defaultAction()

The main method of the widget's PHP class is defaultAction(). Ini this method we will implement all the necessary logic and will pass values to the HTML template using method display(). Because we are developing an app widget (as opposed to system widgets), all its app's classes and functions are automatically available in the widget's PHP code.

This sample widget displays data intended for a limited number of users with administrative access rights; therefore, we add access rights verification:

<?php

class shopStatsWidget extends waWidget
{
    public function defaultAction()
    {
        //verifying whether current user has administrative rights to the Shop-Script app
        $is_admin = wa()->getUser()->isAdmin('shop');
        
        $result = array(
            'is_admin' => $is_admin,
        );
        
        //retrieving statistical data for administrators
        if ($is_admin) {
            $product_model = new shopProductModel();
            $category_model = new shopCategoryModel();
            $product_images_model = new shopProductImagesModel();
            $customer_model = new shopCustomerModel();
            $order_model = new shopOrderModel();
            $result += array(
                'products'   => $product_model->countAll(),
                'images'     => $product_images_model->countAll(),
                'categories' => $customer_model->countAll(),
                'customers'  => $category_model->countAll(),
                'orders'     => $order_model->countAll(),
            );
        }
        
        //passing data to HTML template
        $this->display($result);
    }
}

4. HTML template Default.html

Now add the HTML template to display the data prepared in the main PHP class:

<div class="block">
    {if $is_admin}{* displaying statistical data only to administrators *}
        <ul class="zebra">
            <li>[`Products`]: <b>{$products}</b></li>
            <li>[`Images`]: <b>{$images}</b></li>
            <li>[`Categories`]: <b>{$categories}</b></li>
            <li>[`Customers`]: <b>{$customers}</b></li>
            <li>[`Orders`]: <b>{$orders}</b></li>
        </ul>
    {else}{* to other users, access rights error message is displayed *}
        <p class="gray align-center">[`You are not authorized to view store statistics. Please ask your Webasyst admin for access.`]</p>
    {/if}
</div>

5. Done!

Your first widget is ready, and you can already add it to your dashboard to test the result.

* * *

Widgets may offer users arbitrary settings options, may use several HTML templates depending on the current settings or other conditions, and also support the built-in localization mechanism of the Webasyst framework. Read more about these options in the article "Widget development basics".