^
Navigate CMS v2.9.5 r1611 (2022/03) Sign up Sign in Your account Sign out

Website widget

A website widget extension extends Navigate CMS nv tags adding more functionality. The theme creators can write requests to that kind of widgets to generate HTML code or execute certain actions.

We will explain two examples taking real widgets simplified.


Random content

Let's take a look to the extension definition (random_content.plugin):

{
    "title": "Random content",
    "version": "1.0",
    "author": "Naviwebs",
    "website": "http://www.naviwebs.com",
    "description": "Choose a random item associated to a category and redirect the browser",
    "type": "website"
}

No configuration options, binds or permissions. It is a very simple extension definition. What this extension do is search for all items in a category and return the path of one selected by a random algorithm.

The extension adds a new nv tag callable like this:

 <a href="{{nv object="nvweb" 
               name="random_content_plugin" 
               categories="7,45"}}">Random</a>

The extension call only assigns one attribute: categories, which is a comma separated list of real category IDs that will be used to pick an element.

We have simplified the extension, as the real "random content" extension has another attribute named "mode". In this example we'll assume mode="href".

Let's analyze the simplified extension PHP file (random_content.php). The structure is:

<?php
function nvweb_random_content_plugin($vars=array())
{
    [search for a random element assigned to one of the categories]
    [retrieve the link for that element]
    [return the link]
}
?>

Pretty simple, isn't it? So all calls to <nv object="web" name="random_content_plugin" /> ends up executing this function and returning some HTML code.

Notice that the webget function will receive only one parameter: an associative array. In our example that parameter is named $vars and has the additional attributes given in the HTML template.

Every widget call always includes one special element in the array: "nvweb_html", which is the page template parsed and processed just to the point before calling the widget. In this case, $vars array contains:

$vars = array(
    "categories" => "7,45",
    "nvweb_html" => "<!DOCTYPE html><html><head>[...]</body></html>"
);

Now, the complete PHP code with comments:

<?php
function nvweb_random_content_plugin($vars=array())
{
    // $vars contains all nv tag attributes used in this call

    // retrieve the global variables $website and $current
    global $website; // properties of the active website
    global $current; // properties of the active session

    // $out will contain the HTML code we'll return
    $out = '';
	
    // parse the comma separated list of categories 
    $categories = explode(',', $vars['categories']);
    
    // create an item instance
    $item = new item();

    // ask the empty item to load itself from a list of categories
    $item->load_random($categories);

    // retrieve the path for the chosen item 
    // in the language used in this session
    $item_path = $item->paths[$current['lang']];
			
    // create an absolute URL taking the root website path and
    // adding the item relative path
    $out = $website->absolute_path() . $item_path;
	
    // return the HTTP link to replace the nv tag call
    return $out;
}
?>

The real "random content" extension has extra functionality, like adding all children categories to the possibilities and prevent errors by checking the $categories content. You are free to download the extension and analyze the code.

That's all. To publish the extension we'll need to include a simple documentation file (random_content.info.html) and a 160x100 identity image (thumbnail.png).


Raty (voting plugin)

For the second example we have chosen the Naviwebs wrapper for the jQuery Raty Plugin, a library that allows website visitors to give a score to a content. To keep this simple we will put here a lite version of the plugin.

To display the widget in a template we simply need to write their nv tag call:

<nv object="nvweb"
    name="raty_plugin"
    mode="stars"
    number="5"
    callback="voting_result"
/>

The mode="stars" attribute tells the plugin to show icons of stars. number states how many stars have to be shown. callback is the name of the javascript function of our website that will be executed after the vote has been submitted; this callback is used to report the success or failure of the vote submission to the user.

You may think that the template should load the jQuery Raty library by placing the appropiate code in the <head> section, but this is unnecessary with Navigate CMS. The extension itself will add all code needed. Let's see how this is achieved.

Navigate CMS tells every website extension that a template parsing will start. This event can be catched by any extension just by writing a function called "nvweb_extension_name_event":

function nvweb_raty_event($event, $html)
{
    if($event == 'before_parse')
    {			
        $code = '';
		
        if(strpos($html, 'jquery')===false)	
            $code.= '<script language="javascript" type="text/javascript" 
                        src="https://ajax.[...]/jquery.min.js"></script>';
		
        if(strpos($html, 'jquery.raty.')===false)
            $code.= '
                <script language="javascript" type="text/javascript" 
                    src="'.NAVIGATE_URL.'/plugins/raty/jquery-raty/js/jquery.raty.min.js">
                </script>
            ';

        nvweb_after_body("html", $code);
    }
	
    return $html;
}

So, when Navigate CMS sends the event "before_parse", the extension will check if the template already uses the jQuery library and the jQuery.raty library. If one or both are not found, the extension asks Navigate CMS to add some HTML code at the end of the template code, just after <body> tag is closed.

As a side note, the nvweb_extension_event function is also called for the event "after_parse".

We are now sure to have the javascript libraries loaded. Next step is write the main function of the extension. We have included comments to better understand the code.

function nvweb_raty_plugin($vars=array())
{
    global $website;
    global $current;

    // $out is the HTML code that will replace the whole nv tag call
    $out = '';

    // if the nv tag does not assign a number of stars, set it to five
    if(empty($vars['number']))    $vars['number'] = 5;

    // if no callback given, set it to false
    if(empty($vars['callback']))    $vars['callback'] = 'false';
		
    // calculate the average score given to this content by all users
    $score = 0;
    if($current['object']->votes > 0)
        $score = $current['object']->score / $current['object']->votes;
		
    // generate a unique id to avoid class collissions
    $uid = uniqid();

    // generate the HTML output replacement
    // jQuery Raty just needs a placeholder
    $out = '<div class="raty-plugin-'.$uid.'"></div>';
			
    // we will separate the javascript code 
    // to include it at the end of the template
    // in brief, it executes the raty jquery plugin once the document has loaded
    $js = ' $(document).ready(function()
            {
                $(".raty-plugin-'.$uid.'").raty(
                {
                    path: "'.NAVIGATE_URL.'/plugins/raty/jquery-raty/img",
                    number: '.$vars['number'].',
                    start: '.number_format($score, 2, '.', '').',
                    targetKeep: true,
                    hintList: [],
                    click: function(score, evt)
                    {
                        nvweb_votes_plugin_vote(score, '.$vars['callback'].');
                    }
                });
             });
            ';

    // tell Navigate CMS to include a javascript code at the end of the template
    nvweb_after_body("js", $js);		

    // return the HTML code to replace the nv tag call
    return $out;
}

Both functions must be written in the main extension PHP file: raty.php

That completes the website widget extension examples.

DocumentationExtensionsWebsite widget