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 on the device and communicates via REST services with a NET Generator web server, which persists data on an MSSQLServer database, to perform synchronization processes. If you are using another web generator, like Java Generator, or another DBMS, the steps are the same but the prerequisites may change.
Open GeneXus and create a New - Knowledge Base. Select your preferred Prototyping Environment.
Create the Customer and Company transactions with the following structure:
Please note that predefined domains were used for certain attributes and, in both transactions, note that each identifier attribute is based on the GUID data type with the Autogenerate Guid property set to True.
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:
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":
Create a Menu for Smart Devices 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 Menu. 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:
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.
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 installed 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.
If your computer and the Device are not on 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:
Press F8 to call the "build all" command and build the entire application. This step is necessary, 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 Analysis report, indicating which tables must be created on database. Click on "Create" button in order to create them.
Once the Menu for Smart Devices called "Menu" is built, a new object appears right below the Menu: 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.
Once the "build all" process finishes, in order to run your application in your Android Device or Android Emulator, first right-click the "Menu" Menu for Smart Devices 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.
As mentioned in the beginning of this document, this application uses a local database in order to work. This means that all data the application uses is from the local database. In addition, all insertions, deletions, and updates are made in the local database.
The first time the application 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.
The device always applies changes in the local database, but at the same time, it inserts events which represent 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.
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 these events are sent to the server once the device is again connected, and another modification is made, or next time the application starts again.
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.
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 exception 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
My First Offline Model