View (add-on)

From JRapid

Jump to: navigation, search

Contents

Introduction

A view specifies a way of displaying records in listings for JRapid applications.

JRapid offers two built-in views:

There are endless possibilities for displaying records in a convenient format depending on what those records actually represent. An entity that represents appointments with date and time properties could show its records rendered on a calendar. Real Estate records with an address may be shown on a map. These are situations where add-on Views become powerful features. Developers can import available views or create their own. Views may be shared with other users through the JRapid Community.

Views define how a certain part of a listing's UI code is generated. Filters and the actions bar area remain unchanged, but the area where the records are listed can be rendered as needed. See the listing page for a description of listing sections or areas.

View Area View Area

Usage

<listing
    displayproperties = COMMA_SEPARATED_PROPERTIES
    name = NAME
    subset = SUBSET
    view = COMMA_SEPARATED_VIEWS
/>


  • displayproperties: the properties to be displayed in the listing. Some views require certain number of properties or even different display levels.
  • view: the views for this listing. If more than one view is specified, end-users can select from a combo the view to be displayed.

Views in relation to Services

Views are closely related to JRapid Services. Views provide the definition for how the marshalled entities accessed through services are displayed to the user. These services are exposed to the front end via controllers. The marshalled entities can be viewed by accessing the exposed HTTP methods. This is very useful in seeing exactly how the system works. By default all entities will have find methods created, so viewing a particular entity is a simple as creating a URL and viewing the resulting XML. You can find an example of constructing the URL under the example section here.

How to import a View

The process of importing a view to your project is very straightforward.

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

Import view


2. A new window displaying the available views will be opened. Scroll to the desired view. 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 view as it may describe requirements for the view to work. Click Import when you are ready to add the view to your project.

Import

How to use a view

In order for a View to be used by a listing, it must be specified as a value in the view attribute of the listing element.

        <listing name="divicons" view="divicons"  ... />

Some views require extra attributes in the listing element in order to work. Always check the View's documentation using the Learn More link before importing.

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

Editing listing window


Creating views

Creating a view can be done by defining XSL which formats the XML received from the Entity listing web service. The XML will follow this structure:

<page page="#" rows="#" total="#">
  <entityName id="#">
      <entityProperty>...</entityProperty>
  </entityName>
</page>

An Entity named Company with "name" and "address" as properties would have a service /xml/Company that would return you:

<page page="1" rows="2" total="2">
  <company id="55">
   <name>Mars</name>
   <address>6885 Elm Street</name>
  </company>
  <company id="72">
   <name>Chrysler</name>
   <address>1000 Chrysler Drive Auburn Hills</name>
  </company>
</page>

Creating a new view means defining an XSL file that takes the XML and generates the HTML content that is displayed to the user. Selecting Add-ons->Create add-on (Beta) will take you to the following screen where you can select view as the type and add a name for your new custom view:


File:custom_item.PNG


This will then create a series of files under the folder "Extras". You will need to edit the view_<ViewName>.xsl file. It is suggested you take a look at a few other views and how they work before you try your own. Two of the simpler ones are "tableicons" and "divicons", although there are many sample XSLs provided for you in the JRapid community site to take a look at.


File:extras.PNG


If your custom view requires CSS or JavaScript, you will have to create a folder, and import them. This needs to be done in /WebContent/jrapid-runtime/extras, and then you will have to add a useview section to your config.

<config>
        <useview name="tableicons">
            <usescript location="../jrapid-runtime/extras/view-tableicons/js/tableicons.js"/>
            <usestylesheet location="../jrapid-runtime/extras/view-tableicons/css/tableicons.css"/>
        </useview>
        ...
</config>
...

Finally, you will need to add a listing to your entity so that your new view can be displayed.

<listing name="customListing" view="customview" />

Your listing can be passed other parameters giving your view more information, but you will need to define these in "extras.dtd". To add a parameter such as the entity property name to the customListing above you could do it as follows:

<listing name="customListing" view="customview" extraparameter="name"/>
<!ENTITY % extraelements "">

<!ATTLIST listing extraparameter CDATA #IMPLIED>

Examples

Custom View

Creating a custom view is a powerful, customizable feature. In order to handle the formatting you should be familiar with XSL. The following example will create a listing containing a custom view that provides a mailto link for a particular employee's email address.

First, create your view.

File:custom_item.PNG

Next, open your extras folder and open your view-customview.xsl file. Look for the following for loop where you can define the approach to displaying each entity row in the listing:

        <xslt:for-each select="/*/*">
           <!-- Put your code to display each entity instance here -->
        </xslt:for-each>

The big thing to realize here is that this code will be processed twice before it is displayed. The first transform will be done to the XSL namespace tags, so if you add the following code noting the first is an XSL transform and the second XSLT they will be handled differently.

   <xslt:for-each select="/*/*">
      <p><xsl:value-of select="concat('var','1')"/></p>
      <p><xslt:value-of select="concat('var','2')"/></p>
   </xslt:for-each>

If you package the above view with a listing it will result in the following HTML. As you can see, the XSL transform was evaluated first, and that code does not appear in the source exposed to the user. If you go into the source for the generated JRapid pages you can see this code.

  <xslt:for-each select="/*/*">
     <p>var1</p>
     <p>
       <xslt:value-of select="concat('var','2')"/>
     </p>
  </xslt:for-each>

To create a special listing of the employees and their email addresses one can add the following custom view. For simplicity it is assumed that the email of each employee is their last name plus "@jrapid.com".

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xslt="http://www.htmli.com/xslt"
    xmlns:htmli="http://www.htmli.com/ns/ui" xmlns:exsl="http://exslt.org/common"
    xmlns:str="http://exslt.org/strings" xmlns:java="http://xml.apache.org/xalan/java"
    xmlns:jhtmli="http://www.htmli.com/jhtmli" xmlns:j="http://www.htmli.com/jhtmli"
    xmlns:forms="http://www.htmli.com/ns/forms" xmlns:xalan="http://xml.apache.org/xalan"
    xmlns:jrapid="http://www.jrapid.com/tld">

    <xsl:output method="xml" indent="yes" encoding="utf-8"
        xalan:indent-amount="4" cdata-section-elements=""
        doctype-public="-//W3C//DTD HTML 4.01//EN " doctype-system=" http://www.w3.org/TR/html4/strict.dtd"
        omit-xml-declaration="yes" />

    <xsl:template match="entity" mode="view_customview">
        <xsl:param name="index" />
        <xsl:param name="position" />

        <table width="90%">
          <xslt:for-each select="/*/*">
             <xslt:variable name="email">  
                <xslt:value-of select="concat('mailto:', lastName, '@jrapid.com')"/>
             </xslt:variable>
                   
              <tr>
                 <td>
                    <xslt:value-of select="lastName"/>
                 </td>
                 <td>
                    <xslt:value-of select="firstName"/>
                 </td>
                 <td>
                    <a href="{{$email}}">                 
                       <xslt:value-of select="lastName"/>@jrapid.com
                    </a>
                 </td>
              </tr>
           </xslt:for-each>
        </table>

    </xsl:template>
    
</xsl:stylesheet>

Next add the following listing to the source for your entity containing "firstName" and "lastName" as properties.

    <entity label="Employee" menu="menu" name="Employee">
        <listing name="emailListing" view="customview"/>
        <property display="primary" label="First Name" name="firstName" type="string"/>
        <property display="primary" label="Last Name" name="lastName" type="string"/>
        <property display="secondary" entity="Company" label="Company" name="company"/>
    </entity>

This will give you a listing where the email address is a clickable "mailto:" opening your designated mail handler for you particular system.

File:email_listing.png


Googlecharts view usage

  • Googlecharts view "geomap" visualization:
<entity label="Sale" name="Sale">
        <listing itemname="region" itemvalue="value" name="geomapListing" view="googlecharts" visualization="geomap"/>
        <property display="primary" label="Region" name="region" type="string"/>
        <property display="secondary" label="Value" name="value" type="integer"/>
</entity>
GeoMap view

See also

Personal tools