TD MOBILE NoSQL Data Operations Product Version 2.0
TD Mobile : NoSQL Data Operations, Product Version 2.0 The software described in this book is furnished under a license agreement and may be used only in accordance with the terms of the agreement. Last updated: September 10, 2015. Legal Notice Copyright 2014-2015 Gupta Technologies, Inc. All rights reserved. Gupta, Gupta Technologies, the Gupta logo, Gupta Powered, the Gupta Powered logo, ACCELL, Centura, Centura Ranger, the Centura logo, Centura Web Developer, Component Development Kit, Connectivity Administrator, DataServer, Development Kit, ewave, Fast Facts, NXJ, Object Nationalizer, Quest, Quest/Web, QuickObjects, RDM, Report Builder, RPT Report Writer, RPT/Web, SQL/API, SQLBase, SQLBase Exchange, SQLBase Resource Manager, SQLConsole, SQLGateway, SQLHost, SQLNetwork, SQLRouter, SQLTalk, Team Developer, Team Object Manager, TD Mobile, Velocis, VISION, Web Developer and WebNow! are trademarks of Gupta Technologies and may be registered in the United States of America and/or other countries. SQLWindows is a registered trademark and TeamWindows, ReportWindows and EditWindows are trademarks exclusively used and licensed by Gupta Technologies. The product described in this document is distributed under licenses restricting its use, copying, distribution, and decompilation/reverse engineering. No part of this document may be reproduced in any form by any means without prior written authorization of Gupta Technologies Corporation and its licensors, if any. THE DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. GUPTA TECHNOLOGIES, INC. SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE. This document may describe features and/or functionality not present in your software or your service agreement. Contact your account representative to learn more about what is available with this Gupta Technologies product. Gupta Technologies, Inc. 1420 Rocky Ridge Drive, Suite 380 Roseville, CA 95661 Gupta Technologies.com 1
Table of Contents INTRODUCTION... 3 SQL CONNECTIONS... 3 XML CONNECTIONS... 5 CUSTOM CONNECTIONS... 5 MONGO CONNECTIONS... 6 SETTING UP OUR MONGO DATA CONNECTION... 7 SETTING UP OUR DATA CLASS... 8 USING THE ADD DATA PAGE WIZARD... 13 HOW DATA OPERATIONS WORK WITH BINDINGS... 19 LIST PAGE... 19 DETAIL PAGE... 23 EDIT PAGE... 24 CUSTOMIZING THE WIZARD-GENERATED PAGES... 25 2
Introduction TD Mobile 1.2 allows to build data driven mobile enterprise apps without any coding involved at all. TD Mobile will access your data and create CRUD (Create, Read, Update, Delete) operations without the developer needing to code anything. The developer just needs to tell TD Mobile what data source and tables to use. TD Mobile is taking simplicity of app creation to the next level with both the new data operations and the existing code-free data binding features. Beginning with TD Mobile 1.1, we have the following new features: Data Connections Data Classes Data Operations Data Pages First we ll take a look at the different types of Data Connections that you can use, and then we ll take a trial run of all these features using the popular new NoSQL database Mongo, which now comes packaged with TD Mobile. SQL Connections If you are connecting to a relational database like SqlServer, Oracle or GuptaTechnologies own SqlBase, choose SQL for your Connection Type and then choose your database from the Provider Type dropdown. For those three databases, all you ll need to add is a Connection String to com- plete your Data Connection. If you need help with the connection string, in TD Mobile SAL Help (on the Ribbon Bar of TD Mobile, select the Help tab and then press the SAL button, second from the left), there is a lot of great ad- vice on how to build that: search for the function documentation for SqlConnectDotNet. The con- nection string is a series of key=value pairs, where the keys are keywords dictated by your data provider and the values are largely private to your company: server name, database name, user and password, etc. So 3
you could seek help with the former from your data provider and with the latter from your network admin or other colleagues. There s also some great resources online, like: www.connectionstrings.com 4
XML Connections An XML Connection allows you to store and retrieve records from an XML file based database. The File Path should be the path and name of the XML file to store your data in. If you select Auto Cre- ate File the file will be created if it doesn t already exist. Custom Connections A Custom Connection allows you to create your own data connection implementation. You would have to write a.net class that implements the IDataConnection interface. Specify the fully quali- fied name of that class in Implementation Class, and the fully qualified name of the assembly con- taining the class in Assembly Name. In the Configuration table, you can specify a list of name/value pairs that will be passed to the class when connecting. 5
Mongo Connections Let s go step by step with a Mongo Connection and build a small sample of how to hook up all these new features. If you want to get some hands-on experience and follow along, start TD Mobile and 6
save your new app as MongoContacts.apx in its own folder. If you re the lazy sort, you can find a finished version of MongoContacts.apx in the Samples folder you installed with TD Mobile. Setting up our Mongo Data Connection To add a Connection, select the Connections node within the Server Resources section of the Application window and click the Add button in the Connections window: A Connection named conn1 is created. Select the name and change it to connmongo: Double-click it to get into its Definition window: --> 7
Mongo is the Connection Type we want. The Database Name, by default, is the name of the application; typically you d want to change that but it will work for our sample (if you happen to already have a Mongo database with that name, make up your own new name). Mongo is very flexible and will open an existing database or, if the one you specify doesn t exist, will create it. For our sample, we want to create a new database. If you are using the version of Mongo that comes with TD Mobile, the default Host and Port set- tings seen above will work fine; TD Mobile will start Mongo automatically. If you have your own version, provide the appropriate information; also make sure your Mongo database is running be- fore you run your TD Mobile app. Setting Up our Data Class Adding a new Data Class is a little different, because the default type of Class is Functional. You want to click the down arrow on the right side of the Add button and select Data Class: 8
That will create a new Data Class with the default name cls1. Double-click it to get into the tree view mode: 9
Change the name of the Data Class from cls1 to dccontact. The Data Class will represent a data- base table (called a collection in Mongo) and here, in the Instance Variables section, we will spec- ify the fields we are going to be using from that collection within our app. If the class name is not exactly the same as the collection or table name, whether pre-existing or how we want to define it, we can map it appropriately. Let s insert a Name Map with the Coding Assistant. (If the Coding Assistant is not showing on your screen, look at Outline tab of the Ribbon Bar, and in the Tools section click the Coding Assistant button.) With the Data Class selected in the Outline window, double-click the Name Map option in the Coding Assistant: Once that Name Map is inserted, let s change the collection name from dccontact to Contact : Note: Mongo and many data sources are case-sensitive, be careful when naming collec- tions/tables and fields/columns. Now we will add our fields. With the Instance Variables node selected, choose Number from the available data types listed by the Coding Assistant: 10
Now name that Number ID : Notice that when you select a Data Class variable, you have three options for what you can Add Next Level (or insert under): Name Map, Identity Field and Auto Increment: Name Map we ve seen. Just like the Data Class name can be mapped, if different, to the table/collection name, the Variable name can be mapped to a different column/field name. We ll use the same names for both, so we won t need to map any of our variables. 11
Identity Field must be specified for one field in your Data Class; it identifies a field as the primary key or the unique identifier by which we can select or change data. The compiler will let you know if you forget to specify one, or if you try to specify more than one. 12
Auto Increment is an optional feature; if specified, TD Mobile will automatically increment an Iden- tity Field when inserting new data. Let s specify our ID field as the Identity Field and also ask TD Mobile to automatically increment it on our inserts: As we added the first variable, likewise add the following Strings: Name, Company, Phone, Email ; and a Date/Time named StartDate. These will not be mapped, meaning they will have the same name in the database. Here s our complete Data Class: Using the Add Data Page Wizard First let s get rid of the default page page1. In the Pages collection, select page1 and click the Remove button: 13
Then click the down arrow on the right side of the Add button and select Data Page. This will start the wizard and bring up the Add Data Page window (which expands as you fill in data): 14
In Select Class, choose our Data Class dccontact from the dropdown. For Page Type, we want the works: List Page + Detail Page + Edit Page For Data Connection, choose our Data Connection connmongo. 15
In the Data Page Fields (which will apply to both our Detail Page and our Edit Page), let s de-select the ID field because it s our Identity Field which we won t ever want to change and it s Auto Incre- ment so we don t even need to specify it on inserts. For the ListView Fields, let s de-select all the fields except Name and Company; those two will suf- fice for identifying our contacts from a list. Also change the ListView Rows from 2 to 1, as one row will be plenty for our two fields. Click the Go button. Magically, the wizard builds us three fully functioning, data-enabled web pag- es. There s only one thing you need to do before we can try them out: on the Ribbon Bar, select the Project tab, and in the Pages section, specify the Default Page as DccontactList : Go ahead and run the app. In the Project tab of the Ribbon Bar, in the Application section, click the Go button. If all goes well, you should see, somewhat anticlimactically, a blank web page: 16
But that is as expected because we have no data yet. We can make that better and will a little later on. But let s add some data first so we can see the interaction between our app and the mongo da- tabase. Click the Add button to open the Edit page, and make up some data, for example: And Save. Then we are navigated back to our List page and presto we have a list of one: 17
You can click on that list to go to the Detail page, and from the Detail page you can go to the Edit page and make and save changes, and then navigate back to the list. Play with it if you want. Add another contact. Then let s look at how the wizard wired it all up: 18
How Data Operations Work with Bindings List Page Let s take an in-depth look at our List page, named by the wizard DccontactList. First the wizard declared a pair of Bindings which you can see in the Client section of the web page outline: Defined as type dccontact (our Data Class), we have an array Binding which will populate our list, and a single-instance Binding which will represent the item that the user selects from the list. Then the wizard added a ListView control, named listviewmain to the Phone Layout and specified its List Source Bind and its Value Bind using those two Bindings: Within the ListView is a Layout Grid with two text fields; the wizard set their Value Binds to the appropriate field from the dccontact Data Class; for example, the Name field: 19
On the server side, there is only this Data Operation: 20
You could guess what this Data Operation is going to do by its name, BrowsedcContact, which is a concatenation of Browse (that is, select some number of records/documents) and dccontact (our Data Class). It will return an array of dccontact items. When you look at the entire Data Operation, fully expanded, the thing that jumps out at you is: there s no code: The wizard merely needed to specify the Connection, the Data Action of Browse, and the Data Class Binding we just saw as the List Source Bind for our ListView control. The optional Filters field is like a Where clause in traditional SQL. Say you modified the page and added a data field and hooked it to a Binding named COMPANY; you could then let the user type in a company and then only return contacts from that company with this filter: And the Sort Options works as you would expect. This example would sort your list by Company name and then by Contact name: 21
22
The last step for the wizard was to specify an On Create event for the web page that will invoke this data operation when the user navigates to this page: The wizard also added an On Click event to the ListView, so that when the user selects a contact from the list, it will navigate to the detail page, sending the ID of the selected contact: Detail Page The Detail page has a Parameter named ID set up to receive that data: It then uses that Parameter as the Identity Binding in its one Data Operation: 23
Notice the Data Action of Read that differs from Browse by selecting only one record/document. The Data Class Binding, DCCONTACT will be populated by the operation and will provide the Value Binds for all the text fields on the page. We also see here that a Page Parameter is a type of Binding and ID is used to look up the contact selected back on the List page. Edit Page The Edit Page has two purposes. If it is passed an ID into its Page Parameter, it presumes an edit of an existing contact; if not it presumes we want to insert a new contact. It has three Data Opera- 24
tions, with three different Data Actions : GetdcContact does a Read that selects a contact if there is a passed ID; EditdcContact does an Edit if that contact info is changed and the Save button is clicked; AdddcContact does an Add that inserts a new contact. Again I have to note that there is not a line of code in these Data Operations: Customizing the Wizard-generated Pages You can modify the pages however you like. Let s add some niceties, and add one new Data Opera- tion to delete a contact. First let s handle the case where there are no contacts to list and a blank page is presented to the user. Drag-and-drop a Text field from the Controls section of the Ribbon Bar in Layout view, and set its Caption, in the Properties window to: Click the Add button to insert a contact. Then set its Visibility Bind to the array Binding that populates the ListView, and check the Inverse property; that way, if the array is empty (its Boolean State is False) the text will be visible; if the array has items (its Boolean State is then True) the text will not be visible. 25
In the Detail and the Edit pages, the columns could be sized better. Select the Layout Grid on both of those pages and set the Column Widths property by specifying a percentage of the total width for each column: On the Detail page, let s swap in some Link controls for the Phone number and the Email address so the user will be able to call or email the contact by clicking them. The Link control is the chain-link icon on the Layout tab of the Ribbon Bar in the Control section: After swapping the Text field for a Link, set the Link Type to Phone (or Email) and make sure to set the Value Bind appropriately: 26
On the Edit page, let s add a Delete button and a Cancel button, and let s put all three buttons in a Navigation Bar in the page footer. First, with the page selected in Phone Layout, check the Footer Visible setting in the Page section of the Properties window. Then drag-and-drop a Navigation Bar into the footer. The Navigation Bar is in the Container section next to the Controls section: Then drop the Save button already on the page into the Nav bar. Then drag-and-drop two new buttons from the Ribbon bar: 27
You have to drop them in the right-most edge of the Nav bar. Your Nav bar should now look like this: 28
Select the middle button and, in the Properties window, change its caption to Delete and its name to pbdelete. Now we need to add a Data Operation that will Delete a contact. Switch to the Outline view for the Edit page and, in the Server section, select the Operations node and, in the Coding Assistant, select Data Operation : Give our new Data Operation a name; select our Connection connmongo ; change the Data Action to Delete ; set the Data Class Binding to DCCONTACT ; and the Identity Binding to DCCONTACT.ID, like so: That completes the Data Operation. Now switch back to Phone Layout, and double-click the Delete button. TD Mobile inserts an On Click event for you and brings you to it. Add a Confirm command with a question that will be pre- sented to the user; if he or she answers Yes then the indented lines beneath it will execute, and we will invoke our new Data Operation, and then navigate back to the List page: 29
30
Back in the Phone Layout, select the other new button in the Nav bar. Change its Caption to Can- cel and its Name to pbcancel. Double-click on the button to insert an On Click event. Add a Navigate command that will simply go to the previous page: In the version of MongoContacts.apx in the Samples folder you installed with TD Mobile, if you re curious, you can see some other changes to the app: such as defaulting the StartDate to today for inserts, formatting the dates, and making the Name field on the Edit page required, - but I think you get the point. With the new Data Connections, Data Classes and Data Operations, and the amazing Data Page Wizard, you can have a fully functional data-enabled app up and running in no time. And with just a little tweaking you can fine-tune the design just the way you like it. 31
Gupta Technologies 1420 Rocky Ridge Drive, Suite 380 Roseville, CA 95661 USA Phone: 1.916.928.6400 Toll Free: 1.800.468.6439 Fax: 1.916.928.6404 Germany: +49-(0)89-208039 158 United Kingdom: +44 (0)1753 245 510 France: +33 (0)1 72 86 60 77 COPYRIGHT 2014. Gupta Technologies. All rights reserved. Gupta Technologies, the Gupta Technologies logo and Gupta Technologies NXJ are registered trademarks of Gupta Technologies. Gupta Technologies Composer is a trademark of Gupta Technologies. Java and J2EE are the trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All other company or product names are trademarks of their respective owners. 32