Creating a Custom Widget from Scratch



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&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: { } });