Chapter 1—Tutorial

The first section of this tutorial shows you how to create the data classes for an Omnis application to browse a picture database. The database contains sample client designs for a fictional design company including TV program identities, music album covers, and book jackets. You could, however, use the application to store any type of picture data, such as a library of your own favorite books or photos. To use the application for your own data, you need to work through the tutorial to create the application (library file) and then create your own database file.

Further sections of the tutorial show you how to create a JavaScript Remote Form so you can view the picture database in a web browser on your desktop, or on a mobile device, such as a phone or tablet.

What will you learn?

The tutorial shows you how to create the Omnis class structure required to match the data structure in an existing database (a SQLite database file available in the zip download), and how to create a JavaScript Remote Form to browse the data in a web browser, either on a desktop computer or a mobile device. The first part of the tutorial will take about an hour to complete, but you can pause at any stage and return to it at a later time, as long as you remember to open the database session using the SQL Browser each time you start Omnis Studio if you wish to browse through the data.

Download & install the Files

If you haven’t already done so, you need to download the development version of Omnis Studio. For this tutorial, you can use the free 90-day trial version of the Professional edition, or the Community edition, which you can also download for free; both editions require registration.

Professional edition: www.omnis.net/developers/free-trial

Community edition: www.omnis.net/community-edition

Note that some sections of the tutorial cannot be completed using the Community Edition, since they relate to desktop classes only, but these can be skipped easily and you can create the web-based features without restriction.

To work through the tutorial, you will need to download and extract the project files from this ZIP archive: tutorial.zip. The archive contains a SQLite database file called Pics.db (the Pics.db-journal file is also required), and a PNG image file. Place the files from the zip in the \welcome\tutorial folder in the writable part of the Omnis tree you installed. Alternatively, you can place the tutorial files on your Desktop.

On Windows, you will find the ‘tutorial’ folder in the writable part of your Omnis installation, found in the ‘AppData\Local’ folder, for example:

C:\Users\<username>\AppData\Local\Omnis Software\ Omnis Studio <version>\welcome\tutorial

To find the ‘AppData\Local’ folder, you may need to enable hidden folders in the Windows File Manager and then navigate to the Omnis folder via Users\<username>\AppData\Local.

On macOS, you will find the Omnis files, including the ‘tutorial’ folder, in the Application Support folder, for example:

/Users/<username>/Library/Application Support/Omnis/Omnis Studio <version>/welcome/tutorial

To find the Application Support folder, click on the 'Go' menu in the macOS Finder, then hold down the 'Option' key and select the 'Library' option. There you will find the 'Application Support' folder and within that the 'Omnis' folder.

Tutorial Libraries

If you are using the Professional Edition (or the free trial), you can open and examine the libraries in the final folder in the ‘\welcome\tutorial\’ folder in the Omnis folder; note you cannot open these libraries in the Community Edition.

The PICS.LBS library in the final folder contains the same classes as covered in this tutorial. The PICS2.LBS library has the same classes with some extra classes, including a Query class, a Report class, and a Menu class that enhance the Desktop aspects of the application. You can open these libraries and examine the code in both, or you can copy code from these into your tutorial library to save time when completing the different exercises.

Mouse and Keyboard Usage

In this tutorial, all mouse and key combinations are given in shorthand for all supported platforms, with the Windows shortcut first. So "Press Ctrl/Cmnd-T" means you press Ctrl-T under Windows, or press Cmnd-T on macOS. Similarly, "Press F2/Cmnd-2" means you press the F2 key under Windows, or press Cmnd-2 on macOS, or if your keyboard has function keys you can use Fn+F2 on macOS.

Context Menus

Many of the design tools and class editors in Omnis have Context Menus that provide useful options that speed up development and navigation. To show a context menu, when using a two-button mouse or trackpad, click the Right button on the window or editor and select an option, or when using a single button pointer, hold down the Ctrl button and click the pointer; both these methods will be described in the tutorial as a “Right-click”.

Starting Omnis

To create an Omnis Studio application, you need to use the Development version. Once you have created your web or mobile app, you would run it in conjunction with the App Server version of Omnis Studio for which you need separate end-user client licenses (a free Web license is provided with the Community Edition). The Development version has all the design editors and debugging facilities that you need to help you build an application, but also allows you to test your application in a browser in “runtime mode” as you build it, without having to compile your app. During this tutorial, you will be using the Development version.

Studio Browser

When you start Omnis Studio you will see the Studio Browser, which is the main window from which you can access all the other tools and class editors in Omnis Studio. Initially you will see the Project Libraries option (highlighted below), where you will create a new Omnis library file. If you are new to Omnis or you are evaluating it, you may like to look in the Hub which contains many example libraries and sample code which you may find useful.

image1

The above screen is the Studio Browser on macOS, but it will look identical on Windows, except for obvious differences in border or window style: since Omnis Studio is cross-platform, you should note that every part of the IDE performs in exactly the same way, with only minor differences in key strokes or menu/toolbar options.

If you cannot see the Studio Browser press the F2 key on Windows, or Cmnd-2 on macOS. Under Windows, you can click on the Browser button (compass icon) on the main Omnis Studio toolbar, or you can select the Browser option from the View menu on the Omnis menubar. To show the main Omnis menubar on Windows you need to press the Alt key. On macOS, you can select the Browser option from the View menu on the Omnis menubar, or to show the Omnis toolbar, select the Toolbars option from View menu, show the View toolbar, click OK, and then you can click on the Browser button.

Creating a New Library

The starting point for your Omnis application or project is an Omnis library. A library stores all the classes in your application, including the web forms, data classes, and so on. If you want to edit an existing library, you can open it using the Open existing project library option in the Studio Browser.

You can import an Omnis library from a set of JSON files using the Create project library from JSON option, e.g. you can get sample Omnis libraries in JSON format from our GitHub repository at: https://github.com/OmnisStudio. However, for this tutorial, you will create a new blank library using the Create New Project Library section in the Studio Browser.

To create a new library: 

image2

The Web and Mobile option creates a new library containing a new Remote form and a Remote task, but in this tutorial we are going to build a library and Remote form from scratch or use the Class wizards to automate some parts of the process. If you are evaluating Omnis Studio, and haven’t got time to work through the tutorial, you may like to try the Web and Mobile option and examine the Remote form and other classes it creates for you automatically.

On Windows, you may want to place the tutorial files in your ‘AppData\Local’ folder to allow read/write access to them (note that you may need to enable hidden folders in the Windows File Manager to access the AppData folder). On macOS you can save your library in the Documents folder or on the Desktop.

When you create or open a library it appears in the Studio Browser. To view the contents of a library you expand the ‘Project Libraries’ branch of the Folders tree list (on the left) and click on the library name, in this case the pics library; an alternative way to expand (or contract) a branch in the Folders tree list is to double-click on the name.

image3

The classes that belong to the selected library are listed to the right of the Folders tree list in the Browser list. Using the View menu on the Browser window toolbar, you can change the display to Large Icons, Small Icons or Details (the default view). The following screenshot shows the Studio Browser in Large Icons view, which might be easier while you work through the Tutorial.

image4

Note that your library initially contains a Startup_Task which is used to initialize the library when it starts up (i.e. when it is opened), as well as a folder containing some System Classes that are required to setup or configure a library. If you are using the Community Edition, your library will also include a Remote_Task class which will be listed in the Studio Browser.

Creating a Database Session

Before you start to build your application (project library), you need to open a session to the SQL database, to access the data you are going to use. In this case, you are going to connect your session to an existing SQLite database, provided in the download, that is already populated with data. However, you could use a database from another vendor, such as Oracle, Sybase, DB2, or MySQL, or some other data source connected via ODBC (your edition may restrict which database/s you can use). You can use the SQL Browser during development to set up, modify and examine your database, or multiple databases on different servers, and you can use the SQL Browser to move database tables from one server or data source to another.

image5

Note that some of the session templates may not appear if your edition of Omnis Studio does not support a particular database, or you do not have the necessary clientware installed, but you should see templates for PostgreSQL and SQLite in all editions of Omnis Studio.

The Modify Session window will open which contains all the information needed to connect to your database. (Not all the fields on the session template are needed for all databases.)

image6

Now you need to connect this session template to the SQLite database available in the zip download. On the Modify Session window, the Host Name box needs to contain the path to the SQLite database file that you wish to use, in this case the Pics.db file you downloaded. 

Under Windows, it will be located in AppData\Local such as:
C:\Users\<username>\AppData\Local\Omnis Software\Omnis Studio <version>\welcome\tutorial
On macOS, look for the ‘tutorial’ folder in the Application Support folder, such as:
/Users/<username>/Library/Application Support/Omnis/Omnis Studio <version>/welcome/tutorial

image7

Note that there is also a New Data File button on the Modify Session window that you can use to create a new empty SQLite database, but for this tutorial you will use the existing database file, as above.

The new PICSESS session template will appear in the list of available session templates.

image8
  1. Click on the Back option to exit the Session Manager

Opening a Database Session

To open the database session:

You should see your PICSESS session template displayed in the list of sessions. 

image9

The PICSESS session appears under the SQL Browser branch of the Folders tree list and the Tables and Views icons are displayed on the right. (Different databases may contain different database objects.)

Viewing your Tables

Note that if you have quit and restarted Omnis Studio, then you will need to reopen your database connection/session, as above, to continue this tutorial.

To view the tables contained in the PICS database: 

image10
image11
  1. Close the Alter Table window by clicking on Finished or the close box. 

Viewing your Data

To view the contents of the MyPictures table: 

image12

Note the Interactive SQL tool has entered the SQL needed to view the whole of the MyPictures table (SELECT * FROM MyPictures), but you can use this tool to return whatever data you like by entering your own SQL statements and clicking on the Run button. For example, you could add an 'Order By Pic_Category' clause, then click Run to sort the data on Pic_Category; in this case the Books would appear at the top.

Now you have used the SQL Browser in the Development version of Omnis Studio to create the PicSess session, and to explore the tables and data in the database, you need to provide a way for your library to access the data in the database, using that session information.

Making a Schema

Note that if you have quit and restarted Omnis Studio, then you will need to reopen your database connection/session, as described in the ‘Opening a Database Session’ section, to continue this tutorial.

To allow your library to access the data in the MyPictures table you must first create a Schema class in your library that defines the column structure of the table.

Make sure that the Libraries branch of the Folders tree list is expanded so that you can see the PICS library in the tree list (see below).

Then make sure that the SQL Browser branch of the Folders tree list is expanded so that you can see Tables under the PicSess session in the tree list.

image13

You should see a new schema class called MyPictures appear in the Browser list.

image14

This schema class was created by Omnis automatically to match the definition of the database table when you dropped the MyPictures table onto the PICS library. (If you create your own app using your own database, you could do the same using the tables in your database, that is, drag a table onto your library to create a schema class.)

Editing a Schema

To edit the schema class: 

The 'Server table or view' box at the top of the schema editor contains the name of the database table MyPictures that is related to this Omnis schema class. Each of the entries in the schema contains the name and Omnis data type of one of the columns in the table. Note the data type is the equivalent Omnis data type to that of the column defined in the SQLite database table.

image15

To ensure that certain kinds of queries execute in the most efficient manner it is recommended that one column in each table should be designated as the Primary Key. It is important that the value of the primary key column in each row is unique because it is used to identify a particular row of data when it is to be updated or deleted. In other words, only one row in each table should contain a specific value in the primary key column.

In addition, Omnis sets the No nulls column to kTrue, so the value is incremented automatically every time a new record is entered.

image16

When you have finished modifying a class in Omnis you can simply close the editor window to save it, or you can use the Save option from the File menu, or press Ctrl/Cmnd‑S. You can also select the Auto Save option from the File menu to force Omnis to save any updates automatically.

  1. Close the MyPictures schema class to save it. 

Creating a Desktop Form using a wizard

IMPORTANT: the following section shows how you can create a desktop form, so if you are only interested in creating a web or mobile app (or you are using the Community Edition), you can skip this section and jump to the section ‘Creating a Web Form from scratch’, or the ‘Creating a Web Form using a wizard’ section.

Having created the data structure for your database (the MyPictures schema), you can create a window or form to browse and insert data locally using a window class.

Remember, if you have quit and restarted Omnis Studio, then you will need to reopen your database session, as described in the ‘Opening a Database Session’ section.

image17
image18
image19

The radio buttons on the Omnis Class Wizard allow you to select the style of form to create. Select the first radio button that reads "One field per column based on schema or query class".

image20

Note that if different text is displayed next to the first radio button, you have selected the wrong type of wizard so you should press the Cancel button on the wizard window and choose the SQL Form Wizard.

Note that if at this point you get the message "There are no file classes available for selection. Please create a file class in your library and try again", you have selected the wrong type of wizard so you should press the OK button and choose the SQL Form Wizard. 

image21

Note that if at this point you get the message "There are no SQL sessions available for selection. Please use the SQL Object Browser to open a session and try again", you need to cancel the wizard and open a database connection, as described earlier.

image22

Note that at any time prior to pressing the Finish button you can press the Previous button to go back and review or change a selection.

Editing a Desktop Form

After the wizard has finished creating the form, the Window Class Editor will open with the new PicsWindow window class in design mode, ready for you to modify as you wish. The Component Store (on the left-hand side) and Property Manager (on the right) are opened automatically.

image23

The Component Store (left) is a palette containing the objects and fields that you can add to the forms and windows in your library, while the Property Manager (right) lets you view and modify the values of properties of the currently selected object, e.g. in this case, the window class. At this stage, you do not need to use these tools. 

Adding some code

Before you can open the window and use it to insert data, you must make a small change to the Insert button. Doing this will introduce you to the Omnis Method Editor which is an all-purpose tool with built-in debugger for adding Omnis code to the objects and classes in your library.

The Pic_ID column in the SQLite database we are using is an INTEGER data type with a Primary Key, known as an INTEGER PRIMARY KEY, which will store a unique integer value automatically. The “trick” is to insert the value of Pic_ID as NULL and SQLite will insert the next available numeric value; in effect the value of Pic_ID is incremented by 1 automatically and the new value is inserted. If you delete a data record the value of Pic_ID in that record is never reused; SQLite will always use a new unique value when inserting a new row.

image24

The Omnis Method Editor and Code Editor will open and the $event method behind the Insert button will be highlighted. This method will be executed when you click on the button; in this case the method inserts the current values in the iSqlRow variable into the database, and it's before this line you need to make a small addition.

image25

Note you can press Ctrl/Cmnd-+ to increase the font size in the Code Editor.

image26

You can select the variable name with the pointer, or to keep your hands on the keyboard, use the Up or Down Arrow keys to move up and down in the list and press the Return key to confirm your choice, in this case select iSqlRow. This variable is contained in the form and was added automatically by the SQL form wizard – when the form is opened the variable will contain the current row of data.

image27

To enter #NULL you can type “#” (Shift+3 or Option/Alt+3 or Fn+Option+3 on a Mac keyboard) and the Code Assistant will display all the “hash variables”, or in this case, type “#N” and use the Down Arrow and Return keys to select “#NULL” from the Code Assistant.

image28

#NULL is a so-called "hash variable", a built-in Omnis variable (constant), that represents a NULL value. The line of code you added to the Insert button ensures that whatever value is entered into the field in the open window, just before the row of data is inserted, the value of Pic_ID in the window is set to NULL and SQLite will insert a new value automatically. The complete code line is:

Calculate iSqlRow.Pic_ID as  #NULL

Your method should now look like the following:

image29

Testing a Desktop Form

Now you can test the form you have created to ensure that in runtime mode it performs as expected. To do this:

This will create a window instance on the screen. The window is opened on top of the design window. Note that when you press Ctrl/Cmnd-T to test your form you must first make sure that the design window for PicsWindow is the top window and not some other Omnis window such as the Component Store or Property Manager.

image30

If you don't see any data in your form, check that the database session is open (for example, if you have closed and reopened Omnis, then resumed the tutorial, you will need to open the database session again via the SQL Browser, as described in an earlier section in this tutorial).

When you are developing a form, you can press Ctrl/Cmnd-T at any time to switch between the design mode and runtime (open mode), and back to design mode again.

Inserting some data

Next you can insert a new record in the database. To insert data (a record), first enter some data into the fields as follows (the precise details are not important for this test, but do insert the PNG image into Pic_Image and insert the correct text in Pic_URL):

Field Data to enter…
Pic_Category Book
Pic_Name Science in Chaos
Pic_Image Insert '11bookchaos.png' from the tutorial folder you downloaded: to do this, use the Paste from File option, available from the Edit menu (you might need to press Alt or Option under Windows to show the menu bar including the Edit menu): you may need to select the PNG image type to see the file.
Pic_Desc Cover art for Bob Zurich’s latest science book
Pic_ID leave this field blank; a new unique value of Pic_ID will be inserted for you automatically
Pic_URL images\tutorial\11bookchaos.png (this is not required for the desktop window, but this information is required when viewing the data in a web browser created in the next part of the tutorial)
image31

Important note: Your form must be in open/runtime mode to test it and edit/enter data.

Creating a Web Form from scratch

In this section, you will build a remote form “from scratch” starting with a blank form and adding controls one by one. Alternatively, you could use the SQL JavaScript Form Wizard which automates the whole process and is much quicker. So, to save yourself time, you may like to go straight to the ‘Creating a Web Form using a wizard’ section, ignoring the following section.

In this section of the Tutorial, you are going to create a JavaScript-based web form (called a “Remote form class” in Omnis) to browse your database in a desktop web browser. You can deploy the remote form on the Omnis App Server* & Web Server to allow anyone to look at your picture database in a browser on a desktop computer or mobile device (*this would require a Web license to run your app, which is available for free with the Community Edition, or for a license fee with other editions).

Remember, if you have quit and restarted Omnis Studio, then you will need to reopen your database session, described in the ‘Opening a Database Session’ section, to complete this section.

To create a remote form from scratch (i.e. not using a wizard): 

image32

The new Remote Form will appear in the Studio Browser (note that if you are using the Community Edition there will also be a Remote_Task class).

  1. Double-click on PicsWebform to open it in design mode.

When you design a remote form the Component Store will open automatically docked to the left side of the Remote form editor. It contains 40 or so ready-made JavaScript components, arranged in functional groups, which you can drag and drop onto your remote form.

image33

The remote form has two layout breakpoints, set to 320 and 768, which are shown in the Design bar of the Remote form editor; there are also options to show the Methods for the form and to Test the form in a web browser (you can use these later). The layout breakpoints allow the layout of the form to change at runtime as the size of the client browser changes (mobile or desktop). If necessary, enlarge the form design window and click on 768 to select it.

You will add some fields and other controls to the design layout for the 768 layout breakpoint, and later in this section you can adjust the layout for the 320 breakpoint, so your form can be displayed on phones as well.

Adding Fields to a Web Form

You can add fields to your form by dragging icons from the Component Store and dropping them onto the form.

image34
image35

An Entry Field control is placed on your form and assigned a default name, but you can change it using the Property Manager.

Hiding and Showing Properties

The Advanced option in the Property Manager will be disabled (off) when you first launch Omnis, so the Property Manager will display a simpler subset of properties: for the purposes of the tutorial, all the properties you need should be visible with Advanced disabled.

image36

Once you are familiar with Omnis, as well as the components and their properties, you might like to enable the Advanced option to show all properties whenever the Property Manager is opened.

Changing a Property

image37

Your form should look something like the following.

image38

The minimum height of the current layout is set to 2 pixels below the bottom of the lowest control on the form and this is adjusted automatically as you add or move components. The minimum height is stored in the $layoutminheight remote form property for each layout breakpoint, while the padding is stored in $layoutpadding (default is 2). The minimum height of the remote form is shown as the white area enclosing all the controls on the form.

Adding Code and Further Fields to a Form

Next you need to add a dataname or variable name to the edit field you have created to associate the entry field with a column in your database.

Before you can add a dataname to the edit control, you need to add a Row variable to the form that will link your form to the MyPictures table in your database. You can add just the variable alone, or you can add or copy the code needed in the form, which contains the required variables, and then add the variable(s) directly in the code.

If you are using the Community Edition of Omnis Studio, you can jump to the ‘Pasting in the code...’ section below and enter the code and variables manually.

Otherwise, if you are using the Professional Edition of Omnis Studio, or the free trial, you can copy the code from the PicsWindow (window class) you created in the previous section of this tutorial, or if you did not complete that section you can grab the code from one of the pics.lbs or pics2.bs library in the ‘final’ folder.

To copy code from a window class: (not for Community edition users)

image39
image40

When you paste a method or some code containing any variables from one class to another in Omnis, the variables and their definitions are also copied across. Therefore, you will notice that in the Variable pane, Omnis has created the iSqlRow instance variable (under the Instance tab) and the lSessionName local variable (under the Local tab).

Pasting in the code

If you did not create the PicsWindow window class (or are using the Community edition), you can copy the code text from this page (using the Copy icon, top right of the code box), and create the variables yourself.

Calculate lSessionName as  'PICSESS'
If $root.$sessions.[lSessionName]
  Do iSqlRow.$definefromsqlclass('MyPictures')
  Do iSqlRow.$sessionobject.$assign($root.$sessions.[lSessionName].$sessionobjectReturns #F
  Do iSqlRow.$select() Returns #F
  If flag false
    Do $cinst.$showmessage(con(iSqlRow.$statementobject.$nativeerrorcode,' - ',iSqlRow.$statementobject.$nativeerrortext),'SQL Error')
  End If
Else
  Do $cinst.$showmessage(con('Session ',chr(39),lSessionName,chr(39),' does not exist.'),'SQL Error')
End If

Next you need to paste the code in the correct place in the PicsWebform.

image41

At this stage the code text contains the variable names (for lSessionName and iSqlRow) but they need to be defined. You will notice that since the code contains undefined variables it is not color coded, but you can fix this next. To do this:

image42

In the Create Variable dialog for lSessionName, ensure that Local is selected for Scope, Character for Type, and click on Create Variable to create the lSessionName local variable. Omnis chooses the scope and type automatically based on the name and context of the code.

image43

The lSessionName is now defined and should have its correct syntax color coding in the Code Editor.

image44

Now that you have defined the variables, the iSqlRow and lSessionName variables should appear under their respective tabs (Instance and Local) in the Variables pane, and your code should look like the following, including the syntax color coding:

image45

So what does this code do? The $construct method will be executed when the remote form is opened (in the client web browser), so you can use this method to initialize the form and perform any other functions. The three lines of code starting ‘Do iSqlRow…’ inside the first If statement in the $construct method do the following:

The other code in the $construct method is for handling errors.

You can type the variable name and column name in full, or to use the Code Assistant, type the first letter of the variable name, in this case “i”, and select the variable name from the popup, then add a “dot” (full stop/period) and type the column name Pic_Name.

image46

Pic_Name is a column in the iSqlRow variable that is linked to the Pic_Name column in the MyPictures table in the database.

You need to create some other fields in the form, but rather than creating them from scratch you can copy the Pic_Name field and change the properties of each field.

image47
image48

The Position Assistance (shown as dotted lines, as above) will help you line up the controls by their top edges; when the dotted line appears you can release the control and it will snap into position.

image49
image50

Now you need to create a further field.

You can use the Position Assistance to line up the left edges of the fields and to distribute them equally in a vertical direction.

image51

Your form should look something like the following:

image52

Adding a Picture and a Button to a Form

Next you need to add a Picture control to your form. You can find the Picture control in the Media group in the Component Store, which should be docked to the left of the Remote form editor.

image53
image54
image55

The Pic_URL column contains the location (relative path) of each picture referenced in the SQLite database.

Next you need to create a Button in your form to allow the end user to load each data record, that is, each row in the database.

image56
image57

You need to add some code to the Next button; you can copy the code text from here:

On  evClick
Do iSqlRow.$fetch() Returns lStatus
If lStatus=kFetchFinished=kFetchError
  Do iSqlRow.$select()
  Do iSqlRow.$fetch() Returns lStatus
End If
Calculate iOldRow as iSqlRow

(Alternatively, if you are using the Professional Edition or free trial, you can copy the code from the Next button on the PicsWindow window class you created previously in this tutorial, or from one of the pics libraries in the ‘final’ folder; you’ll need to copy the code from the $event method for the Next button.)

Note when you double-click on an object, Omnis will open the Method Editor and select the object’s $event method, in this case, $event for the Next button on your form. This method will contain the code that will be executed when the end user clicks on the button, i.e. it is the event method for the button.

image58

Note that if you copied the code from this page you will need to create the local variable lStatus type = Character, and the instance variable iOldRow type = Row. (If you copied the code from the Next button in the PicsWindow class, the variables will also have been copied automatically, so you can skip the next part about creating the variables.)

To create the variables, click in the variable name in the Code Editor, click on the Fix button (at the bottom of the Code editor window), and create the variable in the Create Variable dialog, remembering to select the correct Scope and Type for each (although Omnis will try to select these for you automatically).

This is the definition for lStatus:

image59

This is the definition for iOldRow:

image60

The iOldRow and iSqlRow variables are needed to load or "fetch" each successive row of data from the database (in the result set from the database SELECT).

Your Method Editor should look the same as the following, including the syntax color coding for the variables you defined:

image61

(If you copied the code from the PicsWindow window class you can delete the last line of code ‘Do $cwind.$redraw’ since it will have no effect in a web form, or you can comment it out by clicking anywhere in the line (or selecting the whole) and pressing Ctrl/Cmnd-/. A # symbol is added to the line and it becomes inactive code.)

Adjusting the form for a Mobile Device

At present the fields on your PicsWebform are positioned to be displayed in a browser on a desktop computer or tablet (on the 768 layout breakpoint), but you can reposition the fields on the 320 breakpoint so the same remote form can be displayed on different devices, including mobile phones.

To tidy up the fields on the 320 breakpoint layout you can start with the layout from the 768 breakpoint you already designed (at this stage the fields are randomly placed).

image62

Your remote form should look something like the following:

image63

To test your remote form in a web browser, the library needs a Remote Task, which handles the client connections at runtime when you test or deploy your application. However, when you test a remote form, and if your library does not contain a Remote task, one will be created for you automatically and assigned to your Remote form.

So you can skip to the Testing your Web Form section.

Creating a Web Form using a wizard

If you have created a web form from scratch, described in the previous section, you can skip this section; go to the Testing your Web Form section.

Having created the database session and data structure (the MyPictures schema), you can create a Remote Form to browse the data in a web browser on your desktop computer or on a mobile device. The previous section described how to create a Remote form from scratch (and adding fields manually), but this section describes how you can create a Remote form using a Remote Form Wizard; if you are evaluating Omnis Studio then using a wizard will speed up the development process allowing you to assess Omnis in a shorter time.

Remember, if you have quit and restarted Omnis Studio, then you will need to reopen your database session, described in the ‘Opening a Database Session’ section, to complete this section (if the PicSess session is open it will be listed in the SQL Browser as highlighted below).

image64
image65
image66

Next you need to select a Remote task, and since you are creating a Remote form and your library does not contain a Remote task, Omnis will create one for you automatically.

image67

Next in the Class wizard screen, you need to choose the style or layout of the remote form; the radio buttons allow you to select the style of remote form to create.

image68

The "One field per column based on schema or query class" option should be selected by default, which creates a simple form to allow you to browse the data in a single database table, like the one used in this tutorial.

If you have more time, and want to explore Omnis Studio a little more, you can come back to this stage of the tutorial and try the other form layouts, such as the Display or Enterable grid-based form; note the Parent / Child option requires two schema classes linked in a parent/child relationship.

Note that at any time in the wizard process you can press the Previous button to go back and review or change a selection. Next you need to select the SQL class and fields you want to include in your remote form.

image69

Note that if at this point you get the message "There are no SQL sessions available for selection. Please use the SQL Object Browser to open a session and try again", you need to cancel the wizard and open the PicSess database connection, as described earlier in the ‘Opening a Database Session’ section, and then restart this section.

image70

The new JavaScript Remote form is created for you and opened in design mode; the 768 layout breakpoint is selected and the Component Store is docked to the left side of the Remote form editor. A Remote_Task has also been created.

image71

Omnis has added all the required fields and buttons, and created 2 form layouts (shown in the Design bar at the top) to cater to desktop browsers (768 breakpoint) and mobile devices (320 breakpoint); click on each layout to see how the controls have been arranged.

You can click on the Methods button in the Design bar to examine the code Omnis has added automatically during the wizard process; close the Method Editor window(s) when you’ve finished. Omnis has added an Upload button (shown with ellipsis, to the right of the Pic_Image control) and code to allow you to upload an image; when you test the form you can enter a new record including the PNG image provided in the zip (this is described later).

Adding some code

Before you can open the remote form and use it to insert data, you must make a small change to the Insert button. The Pic_ID column in the SQLite database you are using is an INTEGER data type with a Primary Key, known as an INTEGER PRIMARY KEY, which will store a unique integer value automatically. The “trick” is to insert the value of Pic_ID as NULL and SQLite will insert the next available numeric value; in effect the value of Pic_ID is incremented by 1 automatically and the new value is inserted. If you delete a data record, the value of Pic_ID in that record is never reused; SQLite will always use a new unique value when inserting a new row.

image72

The Omnis Method Editor will open and the $event method behind the Insert button will be highlighted. This method will be executed when the end user clicks on the button; in this case the method inserts the current values in the iSqlRow variable into the database, and it's before this line you need to make a small addition.

image73
image74

You can select the variable name with the pointer, or to keep your hands on the keyboard, use the Up or Down Arrow keys to move up and down in the list and press the Return key to confirm your choice, in this case select iSqlRow. This variable is contained in the remote form and was added automatically by the Remote Form Wizard – when the form is opened the variable will contain the current row of data.

image75
image76

#NULL is a so-called "hash variable", a built-in Omnis variable (constant), and represents a NULL value. The line of code you added to the Insert button ensures that whatever value is entered by the end user into the field in the remote form, just before the row of data is inserted, the value of Pic_ID in the remote form is set to NULL and SQLite will insert a new value automatically (you may not have included the Pic_ID field on the form, in which case, this line of code is still needed to ensure a correct value for Pic_ID is entered into the database automatically). The complete code line is:

Calculate iSqlRow.Pic_ID as  #NULL

Your method should now look like the following.

image77

Testing your Web Form

If you created your remote form from scratch it may look different from the JavaScript remote form created using the wizard (i.e. it only has a Next button), but testing a remote form is the same. Remember, if you have quit and restarted Omnis Studio, then you will need to reopen the PicSess database session, as described earlier in the ‘Opening a Database Session’ section.

Your remote form should open in your default web browser, such as Chrome, Safari, Firefox, or Edge. However, you can test a Remote form in a different browser (other than your default web browser), by Right-clicking on the background of a Remote form and selecting the Select Browser and Test Form option, then choosing the browser.

image78

If the data is not displayed this may be because the Pics database session is not open (maybe you closed Omnis Studio and returned to the tutorial later). If you need to open the database session, close the browser tab, return to Omnis Studio, click on SQL Browser in the Studio Browser, click on the Open Session option, then click on PicSess to open the database session, as described in the ‘Opening a Database Session’ section.

image79

Having re-opened the PicSess session, return to your PicsWebform in design mode, click on the Test button (or press Ctrl-T) to open it in your web browser and try clicking the Next button again, or if the PicsWebform form is still open in your web browser you can return to the browser and Refresh/Reload the web page.

Inserting some data

Assuming your PicsWebForm is open in your web browser (and that you have added the code to the Insert button, described in the previous section), then you can insert a new record into the database. To insert data you must first enter some data into the fields as follows:

Field Data to add
Pic_Category Book
Pic_Name Science in Chaos
Pic_Image Use the Upload button to insert the '11bookchaos.png' from the tutorial folder you downloaded in the zip file
Pic_Desc Cover art for Bob Zurich’s latest science book

Note that you did not include the Pic_ID and Pic_URL columns on the form; Pic_ID will be inserted automatically using the code you added to the Insert button.

Click on the Next button to cycle through the data and you should see the record you just inserted.

image80

Test HTML page

When you test a remote form, using the Test button (or Test Form option or Ctrl/Cmnd-T), Omnis creates an HTML page for you automatically, containing the JavaScript client; in this case the page is called 'PicsWebform.htm' and is placed in the html folder inside the Omnis Studio tree (the browser connects to the page using your ‘Localhost’ and a random test port setting). The test HTML page displays your remote form by connecting to your development version of Omnis Studio and the Pics library you have created.

You can view the source for the test HTML page in your browser to see the embedded JavaScript client object – look for the <div> with id=omnisobject1, and some of the other parameters that relate to the name of the library (data-omnislibrary="pics") and the remote form you created (data-omnisclass="PicsWebForm").

<div id="omnisobject1" style="position:absolute; top:0; left:0; 
width:100%; height:100%;" data-webserverurl="_PS_" 
data-omnisserverandport="" data-omnislibrary="pics" 
data-omnisclass="PicsWebForm" data-themename="default" 
data-appid="pics.PicsWebForm" data-dss="'js320x480Portrait',
'js768x1024Portrait'" data-param1="" data-param2="" 
data-commstimeout="0"></div>

Viewing a different layout

Next you can resize your desktop web browser, that is, make it narrower, and the form will switch to display the layout for the 320 breakpoint. It will look something like this (if you used the Remote form wizard):

image81

You can animate the transition between the two layouts, by setting the animatelayouttransitions property.

The animatelayouttransitions property is not shown under the basic view mode (when Advanced is disabled); when you switch to Advanced mode, all the properties and group tabs will appear in the Property Manager to categorize different types of properties. For a Remote form, you will see General, Appearance, Methods, and Action tabs.

image82

If you want to locate other properties in the Property Manager, you need to clear the search by clicking the X icon next to the search, or deleting the search string.

Viewing your form on a mobile device

Resizing your desktop web browser is a quick way to test the different layouts in a remote form, but you can test the form on a mobile device, or any other computer or tablet.

During development and testing you can load the form on any device that is within the same local network WLAN. To do this, you can enter a test URL into the web browser on your mobile or tablet, but replace the Localhost IP address (127.0.0.1) with the IP address of your development computer itself, that is, the computer that is running Omnis Studio and the Pics library.

First, you'll need to open the form in the desktop browser on your development computer to find out the test URL.

Make a note of the URL in the web browser of your development computer, or just leave open the browser, and have ready your mobile phone or tablet, or any other computer within the current WLAN.

image83

Next you need to find out the IP address of your development computer.

The URL will be something like the following (the port number and IP address will be different, otherwise the URL should have the same format):

http://192.168.1.130:49984/jschtml/PicsWebform.htm

When you submit the test URL on your mobile device the PicsWebform remote form will open, but this time Omnis detects that the form is on a mobile device and displays the correct layout.

Changing the form theme

When you create a remote form a ‘default’ color theme is selected and applied to the controls and form background automatically, but you can change the theme in the remote quite easily. You need to return to your remote form in design.

image84

Note that the JS Theme is a global setting so the selected theme will be applied to all the remote forms in your library (or any other open libraries); you can write code in your remote form to set the JS Theme to be used on the client.

image85

Summary

This tutorial does not cover the process of deploying your application to the web, but hopefully it has given you an insight into how quick and easy it is to create and test remote forms in a web or mobile app using Omnis Studio.

For more information about deploying your web application, refer to the Deployment chapter.