Creating a Widget

Mon, 26 Mar 2018 (Last Update: Tue, 27 Mar 2018)

Developers Guide to Creating a Widget

A widget for Pubvana is small, intelligent snippets of code that helps display some aspect of the website or external resource on public pages of the website. Widgets can not accept information back to do further processing.

We would love to see what Developers come up with for Pubvana. Please consider uploading widgets you create to our Addons Store, you can sell them or offer them for free.

To begin building a widget create the following directory structure and files. We'll use the Hello World Widget [Download] as the minimal required example. Widgets go in pubvana/widgets/.

hello_world 
          |
          |---- Hello_world.php
          |---- widget_details.php
          |---- readme.txt
          |---- views/
                  |----- display.php

The widget directory and class file must match with the exception the class file must ucfirst. Direcotry: hello_world, class file: Hello_world.php.

readme.txt

This file is optional and allows you to give developers and others more information about your widget.

widget_details.php

Allows you to define the name of the widget, the description of the widget, the author, author_email, and author_website, the version ,the options, and finally any predetermined content of the widget.

$name: Can be anything you like. It is displayed in the Admin Dashboard.

$description: A short description of what your widget does. There is a 200 character limit.

$author: The author of the widget

$author_email: The email address where users can contact your for support.

$author_website: Any link to the author. Author's website, Gihub, etc.

$version: Use Semantic Version-ing. IE: 1.0.0, 1.0.3, etc

$options: Options are a multi-dimensional array that lists the options that allows users to change the default behavior of the widget.

public $options = [
        'option1'   =>  // named anything you like
                    [
                        'field_type'    => 'text',   // text or dropdown only
                        'default'       => 'default text',   // the default text or setting
                        'label'         => 'Label Text',   // The "title" or lable for the Admin form
                        'help_text'     => 'Help text for the user',   // the help text under the input in Admin form
                        'options'       => ''  // empty for field_type = text, pipe seperated options for dropdown
                    ],
        'option2'   =>// named anything you like
                    [
                        'field_type'    => 'dropdown',// text or dropdown only
                        'default'       => '5', // the default text or setting
                        'label'         => 'Label Text',   // The "title" or lable for the Admin form
                        'help_text'     => 'Help text for the user', // the help text under the input in Admin form
                        'options'       => '1|5|10'  // empty for field_type = text, pipe seperated options for dropdown
                    ]
                ];

$content: Potential content to be displayed on the public pages. This can be left as an empty String or some type of example text can be placed here. HTML or plain text is ok, but don't mix them. Pubvana looks for HTML, if found, it renders the text in HTML, otherwise it renders with PHP's nl2br().

Hello_world.php

The class loaded to run and show your widget code. This class must be the same as the file name and extend Widgets. IE:

class Hello_world extends Widgets{}

Make sure to construct the parent along with any other pre-processing you need.

public function __construct()
  {
      parent::__construct();
  }

Only one function is required for the widget to operate properly. public function run($data) {}. The Widgets Class calls this at run time, however you can have any number of other methods to support and keep code easier to manage. $data is a class, not array. Options from widget_details.php are passed to run() in $data. Values will likely changes as these are available to the user to modify as they need. For the example above:

$data->option1 = default text
    $data->option2 = 5

The Codeigniter global $this-> is available for core functions. IE: $this->db, etc. Libraries must instantiate a new class with it. IE: $Ion_auth = new Ion_auth; then called thusly: if ( $Ion_auth->logged_in() ) { ... do something }

Inside the run() method the only required call is to render(), which is similar to CodeIgniter's $this->load->view() in that it calls the view in the first parameter and passes the data class variable to the view file in views/. Note render uses extract to make access to the variables easier.

// $data->var1 = "Hi";
// $data->var2 = "there!";
// $this->render('display', $data);

In display.php

<?php echo $var1; ?>
<?php echo $var2; ?>

Note: You may change the view files, and can do so based on a variable.

IE: Say you want to support bootstrap 3 and bootstrap 4 out of the box, you could set a widget_details.php -> $options variable of frontend and set it's options to bootstrap3 and bootstrap4 respectively.

In views/ create bootstrap3.php and bootstrap4.php with the appropriate styling for Bootstrap 3 or 4.

in your class file,

return $this->render($data->frontend, $data);

Information for Theme Designers.

Widgets are wrapped in CSS which you can target.

The entire widget area is surrounded by a <div> with a class of: .widget-main-container {}

Each widget is surrounded by a <div> with a class of: .widget-container {}

Each Widget Title is surrounded by a <div> with a class of: .widget-title {}

Each Widget Title is surrounded by a <h4> with a class of: widget-title h4 {}

Each Widget Content (body) is surrounded by a <div> with a class of: .widget-body {}

Finally, each widget has a content area which is displayed under the widget-body. This content is surrounded by a <div> with a class of: .widget-content{}.


Pubvana v1.0.4 Update Release
Pubvana v1.0.4 Update Release

We released a bugfix and minor update release today.

Read more…