Page Comparison

This chapter will guide you through the process of implementing basic functionality using the Genie JavaScript SDK.  You will implement a login page, show an application menu driven by the process map in the server application, and hook up a data entry form to an activity and its associated fields and methods.

Creating the Client Configuration JavaScript File

To configure some of the functionality of the SDK, you're target project will need to define a config object in JavaScript, which we’ll detail here:

1. Add a new JavaScript file to the project under the Scripts folder, named config.js.
2. Add the following code to the file, which includes the various options you can configure (and some example values):

window.genie = window.genie || {};

...

genie.config =

...

                appendColonToLabels: false,

                appSite: 'MySite',

                authenticationMode: 'Alternate',

                backButton: false,

                formmappingFormat: '[p]',

                homePage: 'Home',

                implementationId: '',

                keepActivitiesOpenForSession: true,

                loginPage: 'Login',

                maintenancePage: 'Maintenance',

                messageBundlePath: 'assets/',

                onMaintenance: false,

                showAllMessages: false,

                timeFormat: 12,

...

 {
                appendColonToLabels: false,
                appSite: 'MySite',
                authenticationMode: 'Alternate',
                backButton: false,
                formmappingFormat: '[p]',
                homePage: 'Home',
                implementationId: '',
                keepActivitiesOpenForSession: true,
                loginPage: 'Login',
                maintenancePage: 'Maintenance',
                messageBundlePath: 'assets/',
                onMaintenance: false,
                showAllMessages: false,
                timeFormat: 12,
                urlBlobs: 'http://xxx.com/downloads/blobs/',

...

                urlPrefix: 'https://localhost/GenieService/GenieService.svc/restishssl/',

...

                urlProxy: '/ESAProxy.ashx',

...

                useBundle: true,

...

                useBundle: true,
                xmlNamespace: 'http://www.saasplications.com/GenieService'

...

};

1. Replace the values of the options marked in bold with the correct values for the server application that you are connecting to. Be sure to point the urlPrefix to the restishssl binding on the ESA web service.
2. Add a script reference pointing to this new config.js file, along with the other references that you added to the _Layout.cshtml file (it should be before all the Genie JavaScript SDK references):

<script type="text/javascript" src="~/Scripts/config.js"></script>

Creating the Form Mapping File

Form mapping files are used to map activities on the server to pages on the client. Therefore, if the server issues an activity request, the Genie JavaScript SDK will know which page to navigate to in response. Let’s create a form mapping file now:

1. Add a new XML file to your project, named FormMapping.xml.
2. Add the following XML to the file. Note that you will need to replace the attribute values in square brackets with an activity name and style that will map to an existing activity/style combination in your server application.

<activities>

...

  <activity form="Home" default="true"/>

...

  <activity form="DataEntry" name="[activityname]" style="[activitystyle]" />

...

  <activity form="SummaryList" name="[activityname]" style="[activitystyle]" />

...

</activities>

As you add new pages to your application, you will need to ensure that you add a corresponding activity element for it in this file.

Note: Adding a default="true" attribute to an activity element will result in that activity automatically being navigated to after a successful login.

Creating a Login Page

Now we can finally start building out application. Let’s implement a simple login page, which will contain User Name and Password fields (with corresponding labels obtained from the server), a Log In button, and a message control.

1. Open the Login.cshtml view that you created earlier under the Views folder.
2. Add the following HTML to the bottom of the existing HTML in the view:

<div bind="login"

...

    <div id="username">

        <label>User Name:</label>

        <input />

    </div>

    <div id="password">                                                        

        <label>Password:</label>

        <input type="password" />

    </div>

    <div>

...

>                                                               
    <div id="username">
        <label>User Name:</label>
        <input />
    </div>
    <div id="password">                                                        
        <label>Password:</label>
        <input type="password" />
    </div>
                               
    <div>
        <button type='submit'>Log In</button>

...

    </div>

...

...

   
    <div bind="messages"></div>

...

</div>

1. Now run your project. Enter a random user name and password into the fields, and click the Log In button. A message should appear below the login form, indicating that access was denied.
2. Now try entering a valid user name and password combination to access your server application, and click the Log In button. The server should validate the credentials, and the browser will navigate to the Home page (because it has the default="true" attribute assigned to its corresponding activity element in the form mapping file).

...

Note: After the user has logged in and is using the application, if the user’s session is lost (cleaned up, etc), then a pop up window will appear (invoked by the SDK) asking them to log in again.

Displaying the Process Map as a Menu Bar

Let’s display a menu at the top of the page, based upon the contents of the process map sent by the server, and the form mapping file.

1. Open the _Layout.cshtml view, and add the following HTML directly after the opening body tag:

<div id='menuMainContainer'>

...

    <ul id='menuContainer' bind='menu'></ul>

...

</div>

1. Now run your project. After you log in, you should see a set of bullet point hyperlinks at the top of the page. The menu is rendered as an unordered list, which you can style to suit your needs. Note how the hyperlinks point to the pages we defined earlier, allowing you to navigate through the application.

Note: You’ll find that the process map now renders on the login screen.  To prevent this behaviour, usually your login page will use a different master layout to that of all other pages, which doesn’t include this control.

Creating a Summary List

Let’s implement a view that displays a list of items. Once we have that, we’ll customise it to allow you to drill down upon an item in the list.

Displaying Tabular Data

1. Open the SummaryList.cshtml view that we previously created.
2. The first thing we need to do is to define an activity container. This will be a div that has attributes that the SDK will look for.  Add the following HTML to the end of the view:

<div bind="activity" activityname="[activityname]" activitystyle=" [activitystyle] ">

...

</div>

1. Replace the attribute values in square brackets with the values corresponding to an activity in your server application.
2. Now that we have an activity container, you can add a “data control” to it. This is a table which has the bind="data" attribute on it, like so:

...

1. Run the project, log in, and navigate to this view using the menu on the Home page. Data from the server should appear in a tabular form.

Customising the List Using Templates

You can customise the rendering of the list using underscore templates. Detailing the use of underscore templates is beyond the scope of this document, but some good sources of information include:

...

1. Run your project and navigate to the view. It should now be using the templates you created to render the list.

Enabling Drilling Down on an Item

You can turn on the ability to drill down on an item in a data control by setting the candrilldown attribute to true on the data control element.  The first cell of each row will be turned into a hyperlink, which the user can click on to drill down on that row.

...

<table id="mySummaryList" populatemethod="listMyCookingClasses" bind="data" candrilldown="true" drilldownpage="details.html"></table>

Adding Support for Row Actions

A row action typically appears as a button or a hyperlink on each row of the data publication, which performs an action on that row.  For example row actions may be things such as Edit, Delete, Add to Cart, and so on.  These actions will map to methods on the server.

...

Note: If you want to pass the value of an input element to the method as a parameter, you can use the @userInput special replacement variable as the value of a parameter.  When the action is invoked, the SDK will look for an input in the item/row whose name is of the format <rowid>_userinput_<paramname>.

Adding Support for Context Menus

Rather than invoking a method on the server when a button is clicked (as per actions), you may wish to get and display a context menu instead.  To do so, follow the same method outlined in the section titled Adding Support for Row Actions, but instead of specifying a methodName attribute, specify a contextMenu attribute instead.  For example:

...

    </gridview>

</activity>

Enabling Editable Data Grids

Nothing needs to be done to enable editable data grids.  When a data publication is received from the server that is marked as being editable, the default template will automatically insert input boxes in editable cells. 

Note: If you are templating the data publication control, it’s essential that your input elements have a data-columnid attribute with the column ID that the input element corresponds to as its value in order for any value changes to be sent back to the server. <- Does not work properly currently. Should be by column name.

Creating a Data Entry Form

Let’s create a data entry form that displays data from the server, allows you to edit it, and saves those changes back to the server.

Configuring the Activity Container

You learnt how to configure an activity container in the previous section. Do the same again here for the data entry form, mapping it to an activity/style combination in the server application:

<div bind="activity" activityname="[activityname]" activitystyle="[activitystyle]">

</div>

Implementing a Message Control

You learnt how to configure message control back when implementing the login view. Do the same again here for the data entry form.

...

You’ll note that the message control renders as an unordered list. You can use CSS styles to render it according to your needs.

Binding a Data Entry Field to a Field on the Server

There are a number of ways of binding an input field to a field on the server. One way is as follows:

...

    <select></select>

</div>

Binding a Button to a Method on the Server

To finish this data entry form we need a Save button. Add the following HTML to your view:

...