Objectives

Upon completion of this tutorial, a new developer will be able to:

• Create a new Client
• Place and configure widgets, either stand-alone or based on data types
• Add event-based functionality to widgets

Tutorial Overview

This tutorial creates a simple invoicing application which allows a user to enter sales information into a form. The last five transactions will dynamically appear in a table. A gauge will also keep track of the sum of the last five transactions. The basic steps to do this are:

• Create a new project
• Create data types to keep and use sales information
• Build widgets on a new Client, based on the data types already established
• Add Javascript-coded functionality to widgets within the Client

All lessons assume the developer has a working knowledge of the Vantiq IDE. It is recommended that a new developer completes the lessons in the Introductory Tutorial before starting the lessons in this tutorial.

Note: if needed, you can import a finished version of this project using the Projects -> Import menu item. Just select Tutorials for Import Type, then select Client Builder from the second drop-down, then click Import.

1: Creating a Client Builder Project

The first task is to create a project in the IDE to assemble all the Client components.

Use the Projects button, select New Project, which displays the New Project Wizard. Either create a new Namespace (recommended) or add a new project to the current Namespace, select Empty as the Project type, and title the project “Invoice”:

The rest of the lessons take place inside this Project.

2: Creating a Data Type

The invoice Client needs to store invoice data input by the user in the Vantiq system. You must create a data type to specify that data.

Use the Add button to select Type…:

Use the New Type button to create the invoice data type:

Use the resulting popup to name your type “Invoice”. The description is optional, but you must leave the role as standard.

The Invoice type contains six properties:

• amount: a required Real number which is the total amount of the invoice
• description: an (optional) String property to describe what is being purchased
• firstName: an (optional) String property which holds the first name of the purchaser
• ID: a required unique String property which is used to reference the invoice
• lastName: a required String property which holds the last name of the purchaser
• timestamp: a DateTime property which holds the date and time that the invoice is submitted

The invoice Client creates the ID and timestamp properties using Javascript. The user of the invoice Client will manually enter all other properties.

Once the six properties are defined, save the Invoice type, then save the project.

3: Creating the Invoice Client

This lesson uses the IDE’s Client Builder feature to create our invoice Client.

Use the Add button to select Client…, then use the New Client button to display the New Client dialog:

Enter “Invoice” as the Client Name and select the BrowserEmpty Client Template since we’ll be running our Client in a browser. Use the OK button to display the Client Builder:

The rest of this tutorial takes place inside this Client Builder.

4: Creating the Client Invoice Form

The next task is to create the invoice data entry form for user input. This is multi-step process and demonstrates concepts of the Client Builder common to many Clients.

First, we’ll need to create a new Data Object for the Client. Data Objects define Javascript variables that are referenced by the Client. In this Client, we need to define one Data Object which is used to hold the invoice properties (firstName, lastName, etc.) that the user enters. To create a new Data Object, click the Edit tab of the Control Dock (on the left side of the Client pane), open the Data Objects tree control, then click Page ‘Start’ Data Object (page.data.*) to open the Editing Data Object dialog:

Use the Add a ‘Typed Object’ button to add the new Invoice property to the list of Data Objects. By creating the Invoice property, any Javascript may now reference the Invoice variable using the following syntax: page.data.Invoice. (page.data is the Client’s syntax prefix to reference the data object associated with the Client.)

Second, we’ll use the Client Builder to automatically create a data entry form based on the Invoice properties. Use the Generate Widgets icon, which is an Actions choice and looks like a small lightning bolt. The Generate Widgets process creates a contained form with labeled data entry widgets.

Use the Save and Exit button to save the new Invoice Data Object.

Third, we’ll edit the data entry form to make it a little more user-friendly. Since we’ll use be using Javascript later to generate the invoice ID and timestamp properties, delete those widgets from the Client display. Select the timestamp title widget, then use the Delete button just above the palette of widgets to delete the title. In the same manner, select and delete the timestamp data entry widget, the ID title widget, and the ID data entry widget.

Next, change the titles of the remaining widgets. To change the title of the amount widget, select it, then edit the Text property in the Specific menu to “Amount”. In the same manner, change the titles of the description, firstName, and lastName title widgets to “Description”, “First Name” and “Last Name”.

Finally, drag and drop the Last Name title widget and its data entry widget so they are directly under the First Name widgets. The data entry form should now look like this:

Fourth, add a button to the form to submit the invoice data. To add the Submit button, click the Edit tab of the Control Dock then drag the Inline widget palette tile (under Buttons) and drop it just under the Last Name title in the form. By default, the button is titled ‘Click Me’. Click the ‘Click Me’ button to display its property sheet:

Change the Button Label field in Specific property category to “Submit”. Next, select the Event property category then click the <None> field titled On Click to display the ‘Edit Javascript’ dock:

This editor is where we enter Javascript that is executed whenever the user clicks the Submit button. For our invoice Client, we want to generate values for the ID and timestamp properties, validate some user-provided invoice properties, and submit the invoice data to the Vantiq system:

    // generateUUID is used to create a unique ID to use as the invoice ID
    generateUUID = function() {
        // http://www.ietf.org/rfc/rfc4122.txt
        var s = [];
        var hexDigits = "0123456789abcdef";
        for (var i = 0; i < 36; i++)
        {
            s[i] = hexDigits.substr(Math.floor(Math.random() * 0x10), 1);
        }
        s[14] = "4";  // bits 12-15 of the time_hi_and_version field to 0010
        s[19] = hexDigits.substr((s[19] & 0x3) | 0x8, 1);  // bits 6-7 of the clock_seq_hi_and_reserved to 01
        s[8] = s[13] = s[18] = s[23] = "-";

        var uuid = s.join("");
        return uuid;
    };

    if (!page.data.Invoice.lastName || (page.data.Invoice.amount === 0)) {
        client.errorDialog("Please enter Last Name and Amount values!");
    } else {
        // programatically generate a timestamp and ID for our invoice
        page.data.Invoice.timestamp = new Date().toISOString();
        page.data.Invoice.ID = generateUUID();

        // create a Vantiq database connection to insert our new invoice
        var http = new Http();
        http.setVantiqUrlForResource("Invoice");
        http.setVantiqHeaders();
        http.insert(page.data.Invoice, null, function(response) {
            client.infoDialog("Invoice " + page.data.Invoice.ID + " submitted.");            
        }, function(errors) {
            client.errorDialog("Submit fails: " + JSON.stringify(errors));
        });
    }

Copy the lines of code above and paste them between the curly braces within the …onClick function. Now, when the user clicks the Submit button after entering invoice data on our form, the program will do the following:

• First, check that the user entered at least the Last Name and Amount on the form, generating an error message and terminating further action if not
• Next, populate the timestamp property for the current Invoice by generating a timestamp and converting it to a string
• Likewise, populate the transaction ID property for the current Invoice by calling the function generateUUID (which is defined in the first part of the code) to return a large randomized number formated as a string with dashes
• Connect to the Vantiq database to insert the entire record, both from the user’s input on the form and from what the code generated
• If the insert succeeds, create an Info pop-up to confirm; in the case of failure, an Error pop-up alerts the user

Use the Save button to save the code.

Fifth, add a button to the form to reset the invoice data. To add the Reset Form button, drag the Inline widget palette tile and drop it to the right of the Submit button. Click the new ‘Click Me’ button to display its property sheet: