Edit the web files for a custom widget

Edit the web files for a custom widget in order to develop the content of the widget and link the widget's properties and events.

Before you begin this task, you should be familiar with how to develop webpages using HTML5, CSS, and JavaScript. Also, you must have already created the custom widget and added it to your project's library; the associated web files are automatically created in your project folder only after the widget is added to the library.

The files should be located at:

<project name>\Web\Widgets\<widget name>\

The source library of widgets is located at:

Redist\CustomWidgetsLibrary

Each custom widget actually comprises three web files, but only two of the files are user-editable:

• index.html is the webpage itself. It is what is displayed within the widget's frame in the project screen. You may edit the entire body of the webpage (that is, everything between <body> and </body>).

• custom_widget.js is the library of JavaScript functions that are associated with the webpage. You need to develop functions that link the widget's properties and events with the actual content and behavior of the webpage.

Do not edit the third file, <widget name>.wjson. It contains important settings for the custom widget.

Now, given the almost limitless ways in which you can develop an HTML5-compliant webpage, it is beyond the scope of this documentation to cover every possible step and option in editing these web files. Instead, the rest of this topic will feature a simple example of a custom widget that can load another webpage and then notify your project that the webpage was loaded. The widget — which you created earlier; see Create a new custom widget — should have at least one property named URL and one event named PageLoaded.

How a custom widget loads its files

A custom widget does not load its files with file://. The Viewer maps the project Web folder to a virtual host name and loads the widget page from it.

Virtual host name: https://EdgeCustomWidget.<widget instance name>/

Example URL for the main page of a widget:

https://EdgeCustomWidget.MyWidget/Widgets/MyWidgetType/index.html

The Viewer assigns the host name. You cannot change it.

• Put every file that the widget uses (HTML, CSS, JavaScript and images) inside the project Web folder.

• Reference resources with relative paths, as the default widget files do (for example ../Resources/Apis/Proxy.js). Absolute disk paths do not work.

• Pages that the widget loads, for example in an iframe, must use http:// or https://. Pages that use file:// are not supported.

When the Viewer runs as a Thin Client, the widget files come from the project web address instead. If the address starts with http:// or https://, the Viewer does not use a virtual host name.

Compatibility with earlier versions

Custom widgets that use the standard proxy.js and cwidget calls described in this topic continue to work. Update widgets that load resources with absolute file:// paths, because the Viewer does not support them. Use relative paths inside the project Web folder (see "How a custom widget loads its files," above).

To edit the web files for a custom widget:

Web folder boundary: All widget files must be inside the Web folder of the project, or one of its sub-folders. Files outside this folder are not available to the widget, whatever the path in the HTML. The files of a widget are in:

<project name>\Web\Widgets\<widget name>\

1. Locate the widget's web files in your project folder.

   The files should be located at:

   <project name>\Web\Widgets\<widget name>\custom_widget.js

   <project name>\Web\Widgets\<widget name>\index.html

2. Use a text editor to open index.html.

   The default contents of <body> are a simple badge and label.

   <!DOCTYPE html>

   <html style="overflow: hidden;">

   <head>

   <script src="../Resources/Apis/Proxy.js" cwidget="MyWidget"></script>

   <script src="./custom_widget.js"></script>

   <title>MyWidget</title>

   </head>

   <body>

   <div style="width:96vw;height:95vh;background-color:white;text-align:center;vertical-align:middle;line-height:98vh;border:solid;border-width:thin;border-color:#e6e9eb">

   <div>

   <img src="../Resources/Images/HTML5.png" style="width:32px;height:32px"/>

   <p></p>

   <div style="height: 64px; top: 28px; width: 100%; position: absolute;">MyWidget</div>

   </div>

   </div>

   </body>

   </html>

3. Delete the default contents of <body>.

   <!DOCTYPE html>

   <html style="overflow: hidden;">

   <head>

   <script src="../Resources/Apis/Proxy.js" cwidget="MyWidget"></script>

   <script src="./custom_widget.js"></script>

   <title>MyWidget</title>

   </head>

   <body>

   </body>

   </html>

4. Insert your own HTML code into the body of the webpage.

   The entire body is displayed within the widget's frame in your project screen.

   In this example, you are inserting an iframe element that can be used to load other webpages. The iframe element is a sort of browser window within the browser window, or in this case, a browser window within the custom widget.

   <!DOCTYPE html>

   <html style="overflow: hidden;">

   <head>

   <script src="../Resources/Apis/Proxy.js" cwidget="MyWidget"></script>

   <script src="./custom_widget.js"></script>

   <title>MyWidget</title>

   </head>

   <body>

   <iframe id="myFrame" style="width: 100vw; height: 100vh;"></iframe>

   </body>

   </html>

   Please note that an iframe element cannot be used as a general purpose web browser because many public websites are designed — for security and copyright reasons — not to allow themselves to be displayed like this. You will need to test the custom widget to make sure it can load each of the webpages that you want it to load during project run time.

5. Save and close index.html.

6. Use the text editor to open custom_widget.js.

   // Subscribes to receive property changes

   cwidget.on("PropertyName", function() {

   // Gets property value

   console.log(cwidget.PropertyName);

   // Sets property value

   cwidget.PropertyName = "value"

   // Triggers an event

   cwidget.dispatchEvent("EventName");

   });

   This is an example of a JavaScript function that can be executed during project run time. cwidget is a JavaScript object that represents your custom widget, and it has various properties and methods associated with it. For example, cwidget.on is executed when the value of a property changes, cwidget.PropertyName (for example, cwidget.URL) accesses the value of the property itself, cwidget.dispatchEvent notifies your project when an event has occurred, and so on.

   You can copy this example as many times as you want, for however many properties and events you have added to your custom widget, and then develop each function to do something different. You can also develop entirely new functions and sub-routines, using your knowledge of JavaScript.

7. Delete the body of the function, so that you can insert your own commands.

   cwidget.on("PropertyName", function() { });

8. Replace PropertyName with the name of the property you added to your custom widget.

   In this example, you are using the URL property.

   cwidget.on("URL", function() {

   });

   Now this function will be executed whenever there is a change in the value of your widget's URL property (or more specifically, whenever there is a change in the value of the project tag associated with the URL property).

9. Develop your function.

   In this example, your function will load a webpage and then notify your project that the webpage was loaded.

   cwidget.on("URL", function() {

   var myFrame = document.getElementById("myFrame");

   myFrame.onload = cwidget.dispatchEvent("PageLoaded");

   myFrame.src = cwidget.URL;

   });

   The first line declares a new JavaScript object named myFrame and then links it to the iframe element that you inserted into your HTML file. The second line causes the PageLoaded event to be dispatched when a webpage is loaded. (In other words, the widget in your project is notified that the PageLoaded event occurred.) And the third line sets the source of myFrame to be equal to the widget's URL property, which causes the iframe element to load the specified URL.

   Remember, the entire function depends on the cwidget.on method, so whenever there is a change in the value of your widget's URL property, this function will be executed and a new webpage will be loaded.

10. Save and close custom_widget.js.

Of course there are many other things you can do with these web files, but that is beyond the scope of this documentation. More thorough descriptions and examples will be provided in future releases of this software. In the meantime, if you need help with developing your custom widgets, please contact your software distributor.