Developers

Omnis Technical Note TNJC0006Dec 2013

JavaScript Components: Subform sets

for Omnis Studio 6.x or above

With the introduction of Omnis Studio 6.x you can now open a special kind of subform or group of subforms that behave rather like separate windows in the JavaScript Client. The new subforms are different to standard subforms in that they have a title bar and resizable borders, so the end user can move or resize them dynamically within the “main” JavaScript remote form running in the browser on the client device.

The new subforms or group of subforms are opened as part of a new client object called a Subform Set (SFS), which is created at runtime in the JavaScript Client and allows you to manage the group of subforms. The new subforms are opened in the client at runtime within the main JavaScript remote form, or they can be opened within the context of a single page in a paged pane. Each separate subform in the Subform Set is an instance of a standard Remote form class that you have previously created in your library, which is referenced and added to the Subform Set dynamically.

Creating Dynamic Subforms

There is a set of new client commands to open and manage the subforms in a Subform Set which you can execute using the $clientcommand() method. These client commands must be executed on the Omnis App Server in the context of the current remote form instance ($cinst); the $clientcommand() method will not work in a client-side method. The $clientcommand() method requires two parameters: the Command to be executed and a Row variable containing the parameters for the command, with the general syntax:

Do $cinst.$clientcommand(cCommand,wRow)

where $cinst is the current remote form instance. The following client commands are available for creating and managing Subform Sets.

• subformset_add
  creates a Subform Set within the current remote form instance based on a list of remote form classes specified in the formlist parameter (see below).
  Do $cinst.$clientcommand("subformset_add",row-variable)
  # where row-variable is row(setname, parent, flags, ordervar, formlist)
• subformset_remove
  removes a set of subforms. All subforms in the set will be destructed and removed from their parent.
  Do $cinst.$clientcommand("subformset_remove",row-variable)
  # where row-variable is row(setname) where setname is set to be removed.
• subformset_formadd
  adds a form to an existing subform set.
  Do $cinst.$clientcommand("subformset_formadd",row-variable)
  # where row-variable is row(setname, uniqueID, classname, params, title, left, top, width, height, modal)
• subformset_formremove
  removes a subform from an existing set and destructs it (removing it from its parent).
  Do $cinst.$clientcommand("subformset_formremove",row-variable)
  # where row-variable is row(setname, uniqueID, focus)
• subformset_formtofront
  brings a subform in a set to the top of the stacking order, and gives it the focus. You must use this command to display a subform that has previously been minimized.
  Do $cinst.$clientcommand("subformset_formtofront",row-variable)
  # where row-variable is row(setname, uniqueID)

The subform list

The formlist parameter required for the subformset_add command defines the subforms to be added initially to the subform set (this list can be empty), i.e. a list of remote form classes that you have previously created in your library. The order of the forms in this list represents the stacking order from top to bottom, so that once the set has been added, the top-most subform will be for line 1, and the bottom-most subform will be for the last line.

Using the Stacking Order Variable (ordervar)

When you use the subformset_add client command a list called ordervar is created containing a list of the subforms in the subform set. The ordervar variable allows you to manage the subforms in the set. It has the same definition as the formlist, and like the formlist it contains the subforms in the order of the top to the bottom of the stacking order. Note that if coordinates have been centered using kSFScenter, the ordervar contains their actual values rather than the value kSFScenter.

Subform Set Examples

There is a sample application called ‘Memo’ that uses Subform sets which is available in the Hub in the Studio Browser under the Applets option (or in the Welcome window in older versions), or in the JavaScript Apps Gallery. You can download the Memo app from Github: https://github.com/OmnisStudio/Omnis-JSMemoApplet (requires Studio 8.1.2 or above)

In the latter example, the list of remote forms to be used in the subform set is created in the $construct method of the remote form and the subform set itself is created using the subformset_add command. First the ‘formlist’ or list of forms for the subform set is defined and populated. Note that 'jsSubformSetForm' is a remote form contained in the library and the initial content for subforms can be sent in the Form parameters.

Do lFormList.$define(      lFormID,lClassName,lFormParams,lFormTitle,lFormLeft,lFormTop,lFormWidth,lFormHeight) Do lFormList.$add(1,'jsSubformSetForm',con(1,",",chr(34),      "Forms within a subform set can be draggable and resizable.",chr(34)),'Sub Form 1',25,170,160,160) Do lFormList.$add(2,'jsSubformSetForm',con(2,",",chr(34),      "Forms within a Subform set can be minimized and maximized.",chr(34)),'Sub Form 2',225,170,160,160) Do lFormList.$add(3,'jsSubformSetForm',con(3,",",chr(34),      "Forms within a Subform can include a close box.",chr(34)),'Sub Form 3',425,170,160,160)   # then you setup the row variable containing the parameters for the subformset_add client command   Do lSetRow.$define(lSetName,lParent,lFlags,lOrderVar,lFormList) Do lSetRow.$assigncols("SubformSet",,      kSFSflagMaxButton+kSFSflagMinButton+kSFSflagResize+kSFSflagCloseButton,      'iOpenForms',lFormList) Do $cinst.$clientcommand("subformset_add",lSetRow)

To find out more about Subform sets and in particular the parameters needed for the client commands used for creating and managing subform sets, refer to the 'JavaScript Remote Forms' chapter in the ‘Creating Web & mobile Apps’ manual which you can view here. Click here to register and download a trial copy of Omnis Studio and try out the Memo app that uses subform sets.