Page tree
Skip to end of metadata
Go to start of metadata

The Steps to a Custom Widget from Scratch

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.

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&q=" + encodeURIComponent(address) + "&ie=UTF8&hq=&hnear=" + encodeURIComponent(address) + "&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: {
  }

});
  • No labels