HelloWorld - part 7 applets

From EPESI framework documentation
Jump to: navigation, search

Applets are displayed on the dashboard and are used to show a simplified view of important information from a module or app. An applet can be very sophisticated application in itself but here we will focus on the most common functionality - showing filtered and simplified view of data stored in module's recordset.

You can specify which fields from the module's recordset to display. You decide what you want the applet to present. The files we will be working on are the main file and common file.

HelloWorld_0.php

The main file needs to have a method: applet (public function applet) with certain parameters. Here you configure what the applet's body will display on the dashboard:

  public function applet($conf, & $opts) {
       $opts['go'] = true; //Fullscreen - set true to enable, false to disable
       $opts['actions'][] = Utils_RecordBrowserCommon::applet_new_record_button('HelloWorld',array()); // add new record


        $rs = new Custom_HelloWorld_Recordset();
        $this->rb = $rs->create_rb_module($this);

        $crits = array(); 
        //Setting the width of particular columns

        $columns = array(
            array('field'=>'text', 'width'=>6),
            array('field'=>'calc', 'width'=>15));


        $conds = array();
        // fields selection
        $conds[] = $columns;
        // Filters = $crits
        $conds[] = $crits;
        // Sorting order
        $conds[] = array();
        // Applet info callback
        $conds[] = array('Custom_HelloWorldCommon', 'applet_info_format');
        // Display limit = number of records
        $conds[] = 15;
        // User applet config settings
        $conds[] = $conf;
        // Applet options
        $conds[] = & $opts;

        $this->display_module($this->rb, $conds, 'mini_view');
    }

The $opts['go'] variable is a boolean , if set to true a fullscreen icon is displayed in the title bar of the applet. Clicking on this icon takes you to a module or an app. By default it is set to false.

Fullscreen.png

opts['actions'][] is a button that is displayed on the applet if set that allows you to quickly create a new record in a recordset used by the module or app. In the code above we set it to add a new 'HelloWorld record.

Add record.png

HelloWorldCommon_0.php

After you have your applets body set it's time to add some info and settings to the applet. This is done in a few steps.

public static function applet_info() {
        return __('Display HelloWorld Records');
}

public static function applet_caption() {
        return __('HelloWorld');
}

public static function applet_settings() {
        return array_merge(Utils_RecordBrowserCommon::applet_settings(),array());

}
public static function applet_info_format($r) {
        static $rs;
        $rs || $rs = new Custom_HelloWorld_Recordset();

        $fields = array('Text', 'Calc');
        $args = array();
        foreach ($fields as $f) {
            $args[_V($f)] = $rs->get_val($f, $r, true);
        }


        $ret = array('notes' => Utils_TooltipCommon::format_info_tooltip($args));
        return $ret;
}

info

The applet_info function displays info about the applet in the Config screen. Write a short description about the applet.

Description.png

caption

The applet_caption function sets the caption of the applet displayed on the dashboard.

Caption.png

settings

The applet_setting is a function that displays configurations for your applet. Let's say you want to be able to change the title of the applet. Add this code into the function like so.

public static function applet_settings() {

        $options = array();
        $options[] = array('name'=>'title','label'=>__('Title'),'type'=>'text','default'=>__('HelloWorld'),'rule'=>array(array('message'=>__('Field required'),  
       'type'=>'required')));

        return Utils_RecordBrowserCommon::applet_settings($options);

 }

Now to be able to save the title of the applet you must add it to the conditions in your main file in the applet function.

  public function applet($conf, & $opts) {

        $title = $conf['title'];

        $rs = new Custom_HelloWorld_Recordset();
        $this->rb = $rs->create_rb_module($this);

        $crits = array();
        $columns = array(
            array('field'=>'text', 'width'=>20),
            array('field'=>'calc', 'width'=>15));

        $opts['title'] = $title;
        
        $conds = array();
        // fields selection
        $conds[] = $columns;
        // Filters = $crits
        $conds[] = $crits;
        // Sorting order
        $conds[] = array();
        // Applet info callback
        $conds[] = array('Custom_HelloWorldCommon', 'applet_info_format');
        // Display limit = number of records
        $conds[] = 15;
        // User applet config settings
        $conds[] = $conf;
        // Applet options
        $conds[] = & $opts;

        $this->display_module($this->rb, $conds, 'mini_view');
    }

As you can see we have added a new varaible $title. It holds the value of the title field from the common file. Then set $opt['title'] which is the applets title to the new title. Now go to the dashboard and click the Configure button on your applets tool bar at the top left. You should see the configuration screen.

Config.png

After you have updated the title click save and you should see your applet with a new title in the dashboard. There are many other things you can set in this function, be creative.

info format

Here you can set which field values to display in the pop-up when hovered over the info icon. Add a field by simply inserting it into the $fields array. Remember that the the column names are case sensitive, write them the way they are defined in Recordset.php. The default values displayed n the pop-up are the records id, created by, created on and if edited - edited by, edited on.

Applets info.png

Overview

After you have added the code above go to home and click Config. You should see your HelloWorld Applet listed drag it onto the dashboard. The result should look something like this.

Applet.png


Download: Get full tutorial here


NEXT >