Creating a Custom Widget from Scratch

This page details an advanced example of creating a custom widget from scratch. While this widget is shipped with Profound UI, the widget is not built-in to the product. If you require a Google Maps widget for your application, we recommend using a basic iFrame widget that points to the Google Maps URL instead.

The attached files show a simple example of the recommended way of adding a Google Maps ‘widget’ to your application.

DSPF:
- JSON files can be opened directly in the Visual Designer by following these steps:
  - Download the file to your PC
  - Use the Open… → Local File option:
  - Select the file from the Windows File Explorer
  - Select the Open button
RPG program:

Creating a custom widget from scratch requires you to write JavaScript code to perform the following steps:

Add a base widget using the pui.widgets.add() API
Add the necessary custom properties using the pui.addCustomProperty() API
Add an entry to the Widgets Toolbox using the pui.toolbox.add() API

For more information on these API functions, refer to the Widgets Development API section of the documentation.

All JavaScript code should be saved into an external file that is placed in the /www/profoundui/htdocs/profoundui/userdata/custom/widgets IFS directory.

The completed example widget can be found in the Profound UI Visual Designer in the Custom Widgets section:

Example: Google Maps Widget

In this example, a custom Google Maps widget is created.

// Add the base widget
pui.widgets.add({
  // widget name - this is placed into the standard "field type" property
  name: "google maps",

  // the default id prefix - used to assign id's when the element is first created
  newId: "Map",

  // pull-down menu name
  menuName: "Google Maps Widget",

  // default properties for the widget
  defaults: {
    "width": "400px",
    "height": "300px",
    "z index": "25",
    "background color": "#FFFFFF"
  },

  // property setter functions
  propertySetters: {

    // this will fire when the field type property is set to "google maps"
    // initialization code for the element should go here
    "field type": function(parms) {
      if (parms.design) {
        // design mode content creation code goes here
        // add preview image
        var img = document.createElement("img");
        img.src = "/profoundui/proddata/images/GoogleMaps.jpg";
        img.style.position = "absolute";
        img.style.left = "0px";
        img.style.top = "0px";
        img.style.width = parms.dom.style.width;
        img.style.height = parms.dom.style.height;
        parms.dom.appendChild(img);
        parms.dom.style.overflow = "hidden";
      }
      else {
        // runtime content creation code goes here
        // clear
        parms.dom.innerHTML = "";
        // get url property - evalProperty will evaluate any js expressions that may have been used to build the property
        address = parms.evalProperty("google maps address");
        // populate the widget's dom element
        if (address == null || address == "") {
          parms.dom.innerHTML = "Google Maps Address property not specified.";
        }
        else {
          // here, we build an iframe element and put it into the dom
          var widthHeight = "";
          var width = parseInt(parms.properties["width"]);
          var height = parseInt(parms.properties["height"]);
          if (width > 0) widthHeight += ' width="' + width + '"';
          if (height > 0) widthHeight += ' height="' + height + '"';
          var url = "http://maps.google.com/maps?hl=enl&amp;q=" + encodeURIComponent(address) + "&amp;ie=UTF8&amp;hq=&amp;hnear=" + encodeURIComponent(address) + "&amp;output=embed";
          var html = '<iframe src="' + url;
          html += '" frameborder="0" scrolling="no" marginheight="0" marginwidth="0"';
          html += '"' + widthHeight + '>';
          parms.dom.innerHTML = html;                                                                                                                                               
        }
      }
    },

    // this will fire when the width property of the element changes
    "width": function(parms) {
      if (parms.design) {
        // adjust preview image width
        parms.dom.firstChild.style.width = parms.value;
      }
    },

    // this will fire when the height property of the element changes
    "height": function(parms) {
      if (parms.design) {
        // adjust preview image height
        parms.dom.firstChild.style.height = parms.value;
      }
    }

  }

});

// the widget will already have prebuilt standard properties relating to css attributes, js events, etc.
// here, we can add additional custom properties
pui.addCustomProperty({
  // property name
  name: "google maps address",

  // optional type of input
  // "long" specifies that the text can be long, and an exta text area prompt box is added
  // other types include: "color", "boolean", "image", "list", "js", "file", and "field"
  type: "long",

  // help text appears at the bottom of the properties window
  help: "Specifies the full address to be mapped within Google Maps.",

  // array of widget elements that this property is applicable to
  controls: ["google maps"],

  // properties are categorized in the properties window
  // if the specified category doesn't already exist, it will be created
  category: "Field Settings"
});

// Now, we add an entry to the left-hand side Widgets Toolbox
// More than one entry can be added for the same base widget - this would makes sense if we vary default properties
pui.toolbox.add({
  // specifies category - this can be an existing category or a new one
  // if the category does not exist, it is created on the fly
  category: "Custom Widgets",

  widget: "google maps",
  text: "Google Maps Widget",
  icon: "/profoundui/proddata/images/icons/google_maps.png",

  // this determines the look of the drag/drop proxy as we drag the widget element off the toolbox
  proxyHeight: 302,
  proxyWidth: 402,
  proxyHTML: '<img src="/profoundui/proddata/images/GoogleMaps.jpg" style="width: 400px; height: 300px;">',


  // additional default property values can be specified here
  defaults: {
  }

});