This document is a step by step explanation of how to create a simple native offline application with GeneXus 15.
Before starting with the tutorial, please check that the prerequisites are correctly installed, as also we recommend you to briefly look at the Offline Applications overview and the Smart Devices Offline Applications architecture documents for better understanding of how do the Offline applications works.
In this sample, the application uses a local SQLite database in order to work, as also it communicates via REST services with a Ruby web server , which persists data on a MySQL database, to perform synchronization processes. If you are using another web generator, like .NET Generator or Java Generator, or another DBMS, the steps are the same but the prerequisites may change.
Step 1: Create a new Knowledge Base
Open GeneXus and create a New - Knowledge Base. Select your preferred Prototyping Environment.
Step 2: Model the application
Create the Customer and Company transactions with the following structure:
Please note that predefined domains were used for certain attributes and, in both transactions, be sure to set to True the Autonumber property of each identifier attribute. For instance, positioned on the CustomerId field, press F4 to see its properties, and change the value of the Autonumber property. Do the same for the CompanyId attribute. This is not mandatory, just for the aim of this example.
Step 3: Apply the Work With for Smart Devices pattern
Apply Work With for Smart Devices pattern on both transactions. To do so, on each transaction, click on the Patterns tab, then choose Work With for Smart Devices tab, and check the check box as shown below and save:
Step 4: Customize some layouts (Optional)
Once the Work With for Smart devices pattern is applied on both transactions, we are free to modify their Layouts, Events and many other components.
In this step, we are making some little changes on the List layout of the WWSD applied to Customer in order to show more information when displaying the customers.
From the Toolbox, drag & drop the control Attribute/variable in order to insert attributes you want to see on the Customer list screen. For example, CustomerEmail:
We can remove the label of the attribute by setting the Label position property value to "None":
Step 5: Create the main Menu of the application
Create a Dashboard object called Menu.
This object is like a menu; you can use it to call the Work With objects created in the previous Steps. To do this: right-click in the Items option to add actions to the Dashboard. You must select the WorkWithDevices<TransactionName> objects from the Select Object dialog:
When you select a WorkWithDevices<TransactionName> object, the associated Event to this action is generated automatically:
Step 6: Shift your application to the offline architecture
Change the Connectivity Support property of the "Menu" object into "Offline". This step is crucial, it means a huge change on the application architecture. If you want to learn more about this, please read the Smart Devices Offline Applications architecture document.
Step 7: Edit the Smart Devices Generator Preferences
Change the Smart Devices Generator preferences to choose how is your application built.
You can build and run your application in any of the platforms mentioned in the Offline Applications Requirements document.
However, in this example it is shown how to build your offline application for an Android device. In order to follow this sample, edit the Smart Devices Generator preferences like in the image below:
- Generate Android: True (default)
- Generate iOS: False
- Main Platform: Android
- Android SDK directory: Select your Android SDK directory (which is: the directory where you have instaled the program)
- JDK Directory: Select your JDK directory.
Important note: Because the Offline Smart Devices applications are fully generated in native code, the applications must be compiled and installed on Devices or Simulators of the corresponding platforms. This means that the KBN application does not work with Offline applications.
Step 8: Deploy your application to the cloud (Optional)
If your computer and the Device are not in the same network, and/or you prefer a simpler solution for wireless prototyping, you can deploy your app to the cloud (we recommend this option for your first deploy). To do this, go to the Ruby Generator properties, and set the value "Yes" to the "Deploy to cloud" property, as shown below:
Step 9: Build your application
Press F8 to call the "build all" command and build the entire application. This step is necesary, at least for the first time you build your application.
Note: If you have skipped the Step 8, as it is the first time you build the application, GeneXus needs to know the database connection information.
The following output is shown, as well as the Impact Anlaysis report, indicating which tables must be created on database. Click on "Create" button in order to create them.
Once the Dashboard called "Menu" is built, a new object appears right below the Dashboard: it is the Offline Database Object. This object is in charge of selecting which tables are being created in the local database of the device once the application is installed, as also this object properties can manage how is the Data Synchronization done, among other features.
In the build process, after the Offline Database Object appears, the Offline Database Object Navigation Report is shown, giving to you all the related information about the tables which are going to be synchronized in the device with respect to the server.
Step 10: Run your application!
Once the "build all" process finishes, in order to run your applicaiton in your Android Device or Android Emulator, first right-click the "Menu" Dashboard object and set it as the Startup Object.
Finally press F5 and the application is going to be installed in the Android Device or Android Emulator. This depends on whether the Android Device is plugged into the computer or not.
How does this application works?
As mentioned in the begining of this document, this applications uses a local database in order to work. This means that all data the application uses is from the local database. In adition, all insertions, deletions and updates are made in the local database.
The first time the applications is installed, the local database is created inside the Device. After that, a reception synchronization process is executed in order to receive all data from the server and store that data into the device. Once both, the device and the server, are synchronized, you are free to use the application either the device has connection to the internet or not.
But what happens if data is modified while the device is connected to the internet?
The device always applies changes in the local database, but at the same time, it inserts events which represents those modifications into an auxiliary table in the local database. After that, and because the Send Changes property of the Offline Database Object is set to "When connected" by default, the device sends those events to the server via REST services in order to apply the same changes in the server side.
And what happens if data is modified while the device is disconnected from the internet?
Like when the device is indeed connected, every modification is inserted as an event in the auxiliary table in the local database. But because the device has no connection to the internet, it keeps stacking all events into that auxiliary table. All this events are sent to the server once the device is again connected, and another modification is made, or next time the application starts again.
When does the device receive modifications made in the server?
By default the device receives data from the server every time it starts up. However, this behavior can be customized by changing the Data Receive Criteria property from the Offline Database Object properties.
You can learn more about how synchronization works by reading the Automatic Offline Data Synchronization document and the Data Synchronization document for more advanced concepts.
What is next
We firstly recommend to you to read the whole Table of Contents of the Smart Devices Offline Applications, paying special attention to the Smart Devices Offline Applications architecture and the Smart Devices Offline Applications Generation documents.
After that, you can try to create a new Knowledge Base from some of our Offline applications samples:
Or if you already have an online application and you want to convert it into Offline, please read the HowTo: Converting online applications into offline applications document to get started.
- The offline local database, which is inside the device or emulator, is not reorganized. Therefore, if you make any change to the data model which affects the offline application database, the application re-creates the database, loosing all stored data ( with exeption of Pending Events: see the Offline Database Object ).
- Most of times, starting by developing a simple Online application might be easier and faster to prototype, either with GeneXus X Evolution 2 or GeneXus X Evolution 3, and once it is ready, you are free to convert your application from Online to Offline.
- This sample application uses autonumeric primary keys, but not by setting its Autonumber property=Yes. On the other hand, primary keys are defined based on the GUID data type (with Autogenerate) in order to avoid possible conflicts on the server side when sending changes. To learn more about this, please read the Automatically generated identifiers synching conflicts article.
See the Offline Common Issues
Download the XPZ
My First Offline Model