Widget (add-on)

From JRapid

Jump to: navigation, search

Contents

Introduction

Widgets are user input controls, both user-defined and standard that allow JRapid application forms to accept values from the user. A number of different built-in form widgets are available: input boxes, date pickers, checkbox, radiobutton, textarea, etc. Widgets are mainly used on forms, but can also be used for filters on listings. When a JRapid form is created, default widgets for each defined visible property are used. Together, these controls will provide the user interface to enter, update and edit the values of the particular entity.

JRapid has a wide variety of built-in widgets for the different property data types. In addition, there are importable Widgets in the JRapid Community and developers can create their own. The existing jQuery widgets are very easy to use.


jdatepicker widget colorpicker widget youtube widget

Usage

<property
   name = NAME
   type = TYPE
   widget = WIDGET
   ...
/>

How to import a Widget

It is a straightforward process to import an existing widget into your project.

1. Go to Add-ons menu and select the Import Widget option.

Import widget


2. A new window displaying the available widgets will be opened. Scroll to the desired widget. When you drag your mouse over each item, the Learn More and Import options are shown. Make sure you read the Learn More info before importing a widget as the widget may have specific requirement like that the property be of a specific type. Click Import when you are ready to add the widget to your project.

Import

How to use a Widget

In order for a Widget to be used by a property on a form, it must be specified as a value in the widget attribute of the property element.

        <property name="loadDate" type="date" widget="jdatepicker"  ... />

Always check the Widget's documentation using the Learn More link before importing.

You can also specify Widgets using the edit property dialog. The Widgets shown as options in this window will vary depending on what you have already imported or created for your project.

Editing property window

Creating Widgets

When creating a Widget you must define what the code generator should produce in the place where the original property widget would have been. There are two possible approaches:

  • Write an XSL transformation to produce the necessary HTML code
  • Execute JavaScript code to modify the DOM and modify, replace or add functionality to the original widget

You can also add your own JavaScript code to work combined with the HTML output of an XSL transformation.

The first step is to produce the boilerplate code for your Widget by using the Add-ons -> Create Add-on menu option.


Create Add-on


When Widget is selected as the type, the dialog will show the following fields.


Create Widget


Name must be unique for the widget.

Use XSL code indicates whether the widget will use an XSL transformation or not. When selected, the process will create the necessary folders and include a template XSL file where you can define the transformation. This file will be named widget-<WIDGET_NAME>.xsl and will be placed inside the /Extras folder.

JQuery allows the specification of a function name used to initialize a jQuery widget or plugin. Generally, jQuery widgets and plugins are invoked by executing a function by the name of the plugin over a DOM element to which they will be tied. The name you provide here should be that of the initializing function for the chosen plugin and it will be executed on the DOM element with the <ENTITY_NAME>_<PROPERTY_NAME> id. This could be a form text input if, for example, the property is of type string and no XSL transformation has been defined. It could also be any other HTML element created as output of a custom XSL transformation.

JQuery Options is the place where you should include all the initialization options required by the JQuery plugin, if one was used. These options are generally provided as arguments to the initializing function and are written in the form of a JSON object.

Once the form is submitted, the process creates the necessary files according to your input. The corresponding <usewidget> element will be created in the <config> section of your app definition.

<app basepackage="com.t20110406" engine="forms-0.9" name="Main">
    <config>
        ...
        <usewidget jquery="datepicker" 
                   jqueryoptions="{changeMonth: true, changeYear: true, dateFormat: 'dd/mm/yy'}" name="jdatepicker">
            <usescript location="../jrapid-runtime/extras/widget-jdatepicker/js/jquery.ui.datepicker.min.js"/>
        </usewidget>
        ...
        <usewidget name="<WIDGET_NAME>"/>
    </config>
...


Note de jdatepicker <usewidget> element, that is always included in every JRapid project. It is implemented using the JQuery UI Date Picker widget, so it uses the jquery and jqueryoptions attributes to specify name of the function an initialization options. It also defines a child <usescript> element to include the required JavaScript library file in every HTML that makes use of the widget.

Going back to the XSL file, it includes the following template that will match for any property that specifies the use of the widget. Note that, because the mode is "widget_single", it will only use this template if the property is not defined as a collection.

    <xsl:template match="property[not(@entity) and @widget='<WIDGET_NAME>']" mode="widget_single" priority="100">
        <xsl:param name="selectexpr" />
        <xsl:param name="value" />
        <xsl:param name="fpath" />
        <xsl:param name="class" />
        <xsl:param name="filter" />
        <xsl:param name="widget" />
        <xsl:param name="isnew" />

        <xsl:variable name="finalselectexpr">evaluated('<xsl:value-of select="$selectexpr" /><xsl:if test="not(@collection)">/<xsl:value-of select="@name" /></xsl:if>', me)</xsl:variable>
	<xsl:variable name="finalvalue"><xsl:if test="not($filter) and not($isnew)">{<xsl:if test="@collection and not($isnew)">.</xsl:if><xsl:if test="not(@collection)"><xsl:value-of select="$value" />/<xsl:value-of select="@name" /></xsl:if>}</xsl:if></xsl:variable>
	<xsl:variable name="finalvalueclear"><xsl:if test="@collection and $isnew">foo</xsl:if><xsl:if test="@collection and not($isnew)">.</xsl:if><xsl:if test="not(@collection)"><xsl:value-of select="$value" />/<xsl:value-of select="@name" /></xsl:if></xsl:variable>
			
	<xsl:variable name="propertyId" select="java:Util.id($fpath, @name)" />


        <!-- INSERT YOUR CODE HERE -->
        
    </xsl:template>


To produce a simple text input, just as it would be generated by default for a string property, the code would look like the following.

    <input title="{java:Util.escapeLabel( @label )}. {@description}" 
        src="xml" selectexpr="{$finalselectexpr}" 
        id="{$propertyId}" value="{$finalvalue}"
	class="{$class} text jrapid_input {@class}" 
	type="text">	
    </input>

It's important to note:

  • The id attribute takes its value from the $propertyId variable
  • the selectexpr attribute is responsible for the posting of the value entered to the input into the XML that gets submitted to the server when the OK button is clicked.


When working with the XSL transformations, it is very useful to keep an eye out for changes to the jrapid.log file present in the root of your JRapid project as errors caused by this process will be logged there. When trying out changes to the transformation and the process fails, the JRapid Console of the Designer will print a fail message, so it may also help to watch this output.

Example

JQuery Example

Combining JRapid applications and jQuery plugins is a fast and effective way to add custom functionality to your project. In this example I will take an existing jQuery script that limits input to numbers and periods, and add it to my project linking it to a product price property in my entity that should always be a double value.

First, here is the link to the jQuery code. This code is written and maintained outside of JRapid by the maintainers of the code webmonkey site.

Go to and select Create add-ons (Beta) under the Add-ons menu. Select widget as the type and fill in as follows:


File:numericonly_add_widget.png

The widget add-on is a special case that along with Views uses XSL to generate output XML. In this example we are just using the widget to execute some JavaScript, and do not need the XSL. Since the Use XSL box is left unchecked, no XSL file is created in the extras folder.

Next go to your files view (or open in Eclipse) and add a file to the folder widget-numericonly/js created under WebContent/jrapid-runtime/extras, and fill that file with the jQuery code you downloaded above. The structure should look as follows:


File:numericonly_file_view.png


Finally, you need to add a usewidget section to your config linking to the jQuery code, and add a widget tag to the property you wish the code to run for:

    <config>
        ...
        <usewidget jquery="numericonly" name="numericonly">
            <usescript location="../jrapid-runtime/extras/widget-numericonly/js/jquery.numericonly.js"/>
        </usewidget>
    </config>


    <entity label="Product" menu="menu" name="Product">
       ...
       <property label="Price" name="price" type="double" widget="numericonly"/>
    </entity>

The form entry for products should now only accept numeric values and not even allow the user to type a value that is not a double.

Google Maps Point Widget

Another very useful widget available through the JRapid community is a Google Maps Point widget which allows a user to pick a location, and have it saved as coordinates on the back-end. The following example is for a restaurant entity containing coordinates while using the Google Maps Point widget so that the user does not have to type them in and can simply select from a map. First I imported the Google Maps Point widget via Add-ons -> Import Widget, which creates the appropriate files in my project and includes the widget in the project's config section. Next I added widget="googlemapspoint" to the particular property (defined as a string).

    <config>
        ...
        <usewidget name="googlemapspoint">
            <usescript location="../jrapid-runtime/extras/widget-googlemapspoint/js/googlemapspoint.js"/>
        </usewidget>
    </config>

    <entity label="Restaurant" name="Restaurant">
        ...
        <property display="primary" label="Location" name="location" type="string" widget="googlemapspoint"/>
        ...
    </entity>


This will add a link to a pop-up to the restaurant interface as below.


File:restaurant.png


Once the user selects a value, the coordinates are stored as a string and if the user clicks on the link it will be pre-populated to show the previously selected coordinates with the normal Google marker.


File:selected_map.png

See Also

Personal tools