Creating a Custom Widget from Scratch
- Alex Roytman
- Emily Seage
- Megan Bond
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&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: {
}
});