Writing widgets

A homepage widget is a collection of scripts that can be placed on a homepages web page. Homepages allows users to drag and drop widgets on to a page, re-arrange them and change their design. It is also possible to apply settings to widgets to modify their behaviour. For example a widget could be used to display a user-defined image, some text or a Twitter feed.

Widgets can be coded using HTML and PHP. It is also possible to associate Javascript with a widget, to be included whenever that widget is used on the page. Widget settings are stored in the database as name value pairs.

Overview

Homepage widgets are made up of four scripts:

  • public.php: the template and PHP code to be displayed to the user
  • public.js: a Javascript file included with the public.php script
  • secure.php: the file that contains the HTML or PHP used to specify any settings when using the Homepages designer
  • secure.js: a Javascript file to be included with secure.php

The public.php template is the only file that is required for a widget to be functional. This can contain PHP, Javascript, HTML or CSS.

Any widget that you require the administrator to enter data into will require a secure.php template. Again, this can contain PHP, Javascript, HTML or CSS.

A widget can be added into the Control Center either by zipping up the files and uploading them, or pasting or writing the information into the respective text area in the Homepage Widgets utilities page.

If a zip file is created, the files themselves must be zipped, rather than placing the files in a directory and then zipping the directory.

Once uploaded, a widget record is stored in the database in the JaduHomepageWidgets table and on the file system in the var directory.

Developing Widgets using HTML

The simplest widget is just a few lines of HTML. This widget displays the message “Hello, world!”:

    <div class="helloWorldWidget">
        <h2>Hello, world!</h2>
    </div>

We can also use widgets to send values to other sites using forms. This widget lets you search for your nearest Driving test center:

    <div class="drivingTestWidget">
        <form action=http://www.dsa.gov.uk/findnearestDTC.asp name="frmPostcode" method="get">
            <label for="sPostCode">Postcode:</label>
            <input name="sPostCode" id="sPostCode" type="text" />
            <input name="Find" value="GO" type="submit" />
            <input name="sCentreType" value="car" type="hidden" />
            <input name="TypeID" value="17" type="hidden" />
            <input name="cat" value="38" type="hidden" />
        </form>
    </div>

Developing Widgets using PHP

Our Hello, world! widget in PHP would look as follows:

    <div class="helloWorldWidget">
        <?php print '<h2>Hello, world!</h2>'; ?>
    </div>

The following example would show the top-level navigation categories from your website’s taxonomy as a drop down list:

    <div class="categorySelectWidget">
        <form action="<?php print getSiteRootURL(); ?>/site/scripts/documents.php" method="get">
            <label for="categoryID">Information by category</label>
    <?php
        if (sizeof($rootCategories) > 0) {
    ?>
            <select id="categoryID" name="categoryID">
    <?php
            foreach ($rootCategories as $category) {
    ?>
                <option value="<?php print $category->id; ?>">
    <?php
                print encodeHtml($category->name);
    ?>
                </option>
    <?php
            }
    ?>
            </select>
    <?php
        }
    ?>
            <input type="submit" value="Go" />
        </form>
    </div>

If you need your widget to have settings when it’s dropped into a homepage, you will need to create a secure.php file. The following example would allow a heading to be entered into the widget. The secure.php code would look as follows:

    <table class="form_table" id="lb_widget_content">
        <tbody>
            <tr>
                <td class="label_cell">Text to show</td>
                <td class="data_cell">
                    <input id="text1" value="" size="12" type="text" class="field" />
                </td>
            </tr>
        </tbody>
    </table>

The corresponding public.php would be as follows:

    <div class="textWidget">
        <p>%TEXT1%</p>
    </div>

As you can see from the example above, any inputs that you specify in the settings code must be identified using a unique id attribute.

This id attribute is then used in the public.php code to identify where the setting should be used when viewed by a visitor.

Styling widgets

When writing stylesheet specific widget styles, the placeholder %WIDGET% is used to denote the class of the div wrapping the public.php template.

Example:

    %WIDGET% h2 { background: url(h1-event.gif) no-repeat left center; }

Images

If you would like administrators to be able to assign an image from the Jadu Image Manager, the following must be embedded in your secure.php template table:

    <tr>
        <td class="label_cell">Image</td>
        <td class="data_cell">
            <input type="hidden" id="img_src" value=""
                onchange="$('img_srci').src = 'https://' + DOMAIN + '/images/' + this.value;" />
            <img id="img_srci" class="img_preview"
                src="<?php print $SECURE_JADU_PATH; ?>/images/no_image.gif" />
            <br />
            <input type="button" class="button" value="Image Library"
                onclick="return loadLightbox('image_manager/image_manager', 'lb2',
                'mode=lb2&imagePreviewID=img_srci&imageFilenameID=img_src');" />
        </td>
    </tr>

To access this in public.php, the placeholder %IMG_SRC% is used. This will contain only the filename of the image, so the file path must be specified as follows:

    <?php print getStaticContentRootURL() . '/images/' .  encodeHtml('%IMG_SRC%'); ?>

results matching ""

    No results matching ""