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:

        2024-05-09_08-28-33.png
        2024-05-09_08-33-46.png
      • 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:

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

Â