Understanding Mobile Pages and Classes

This chapter discusses:

• Mobile component transaction model.

• Mobile device events.

See Also

Enterprise PeopleTools 8.49 PeopleBook: PeopleSoft Mobile Agent

Mobile Classes

Mobile Component Transaction Model

Mobile pages process transactions similarly to PeopleSoft Pure Internet Architecture.

Unit of Work

A unit of work for a mobile application is an instance of a data in a component interface.

Suppose your component interface had the following structure:

CUSTOMER
...CUST_ID
   CUST_STATUS
   . . .
   SITE
      SITE_ID
      ADDRESS
      . . .

CUSTOMER is the top level of information, the top of the component interface. Your data may include more than one customer, and each customer may have one or more sites.

In a mobile application, you would have two list views based on the example structure, as well as two detail views.

Suppose you have two instances of data, Customer1 and Customer2. A user can change detail about Customer1 and details about Customer1's sites. When the user tries to navigate to Customer2, he or she is prompted to save changes, because navigating to another customer involves leaving one unit of work to begin another unit of work.

The unit of work is finished when the user leaves an instance of the component interface, by either going to another component interface (maybe a peer reference), by going to another instance of data (level zero) of the component interface, or by using the menu navigation to go to another mobile application.

When the user clicks the Save button, the current unit of work is finished and a new unit of work begins.

If an application transfers a user to another object in the same component using TransferMobilePage, the same unit of work is still in existence. If the user is transferred to a different component, a new unit of work is started.

Working Set

A working set refers to the objects and data in memory that are available you. It's similar to the component buffer.

When a user selects a mobile application, a list view is opened, containing all the instances of that component interface (all the rows of level zero data). When a user selects one of those instances, that object and all its data becomes part of the working set. The other instances of the component interface are not part of the working set.

In the initial object, only the equivalent of the level zero and level one data is in the working set. However, all the data for the component interface is available to you using PeopleCode. When data is accessed, either through PeopleCode or by the user drilling down to it, it is brought into the working set. For example, if a developer accesses data at level two before a user drills down using a detail view, that data is brought into the working set.

When a user leaves an instance of a component interface, the working set is flushed of all data. A new working set is generated when a user selects a different instance of the component interface.

For example, suppose the top level in the component interface is CUSTOMER, and there are two instances, Customer1 and Customer2. When a user navigates from Customer1 to Customer2, the current working set data is flushed.

Data for a collection is automatically pulled into the working set. When this happens, the OnInit mobile PeopleCode event runs for the data that is brought in. However, data for top-level (level zero) and prompt list views does not initiate the OnInit event. In addition, default values are not set for data displayed for top-level and prompt list views.

Data Saves

Data entered into a mobile application can only be saved either when a user clicks the Save button, or when theDoSave function is used.

You can instantiate, and make changes to, a new component interface using PeopleCode. However, when a user clicks the Save button, those changes are not automatically saved, because a developer-instantiated component interface is not part of the current component.

To save changes made to a component interface instantiated solely through PeopleCode, both of the following must happen:

• You explicitly save the component interface using the Save method or the DoSave function.

• The user must not cancel out of the current component, but must save changes by clicking the Save button.

If the user cancels out of the component, even if you have issued a Save, the data is not saved.

The user is not prompted to save data when leaving the current unit of work if:

• You changed a developer-instantiated component interface and saved those changes with the Save method.

• The user did not make any changes to data in the current component interface.

To ensure that the data actually gets committed to the database, you can force a prompt to occur. This can be done using the following code:

%ThisMobileObject.SetModified(True);

If a mobile property is based upon a derived field, changing the value of the property does not change the state of the working set. If a user changes a property based upon a derived field, he or she is not prompted to save the mobile page.

Note. If you edit the properties of a component interface reference or data collection, you can mark it as derived. However, the derived flag is ignored for all references (reference properties and collections).

Peer References

A peer reference is a related component interface defined on the underlying synchronizable component interface. Peer references can be used in mobile applications as a kind of prompt table for filtering and bringing in additional information into the originating component interface.

Any peer references are automatically brought in as part of the working set. However, only the single instance of the data that relates to the originating component interface is brought in. If you need to work with additional instances of a peer reference, they must be brought into the working set using PeopleCode.

To save data in a peer reference, use the mobile Save method. However, the data for the peer reference is not saved until a user clicks the Save button.

If a change is made to a peer reference by PeopleCode, and no data in the originating component interface has been changed, the user is not prompted to save data.

Field Processing

Mobile pages run in interactive mode. There is no deferred mode processing.

In general, when a user clicks the Save button, fields are verified and processed in the order they appear on the mobile page (tabbing order). However, if a field has PeopleCode associated with it, that field is processed last.

If more than one field has PeopleCode associated with it, and more than one of those fields has been changed by a user, when the user clicks the Save button, these fields are processed after all the fields that do not have PeopleCode associated with them, in the order the user accessed them.

For example, suppose a detail view has an edit box and a button. The user makes a change in the edit box and then clicks the button. When the user clicks the Save button, the edit box and the button are processed after all the other fields on the detail view. The edit box is processed before the button.

Only the following standard system edits are performed by mobile pages:

• Data type checking.

• Formatting.

• Required field.

• Prompt table.

Note. When doing formatting and checking data types, the Custom and Raw Binary field formats are not checked.

Translate values are displayed in a drop-down box for a field, so it is not possible for a user to enter a bad value.

Fields with required yes/no values are displayed as a check box, so it is not possible for a user to enter a bad value.

The only standard system edit that is performed when a user clicks the Save button for a page is the required field edit.

The other system edits are performed in these situations:

• PeopleCode is associated with a property (field) and the user has changed that field, and then leaves it.

• A graphical user interface (GUI) event is processed, such as when a user selects a tab or clicks the Go Back link.

Note. Fraction parts of fields of type Decimal that are too long for the target property declaration are rounded.

See PeopleSoft Pure Internet Architecture Processing Considerations.

Field Formats

The Custom and Raw Binary field format types are not supported for mobile pages. The supported field format type edits are:

• Uppercase

• Name

• Phone Number North American

• Zip/Postal Code North American

• SSN

• Mixedcase

• Numbers Only

• SIN

• Phone Number International

• Zip/Postal Code International

Cancel Button

When a user clicks the Cancel button, only the changes for that page are canceled. Changes made to other pages in that instance of the component interface are not rolled back. The parent level of the displaying page is displayed. For example, if a user clicks the Cancel button on a level two detail page, the level one detail view is displayed, with the tab that contains the level two collection active. The user is still in the same unit of work.

A user can edit values displayed in a list view generated by a collection. If a user cancels after changing this type of data, only those changes from that page are rolled back.

Mobile Device Events

This section discusses:

• Event sets.

• OnChange event.

• OnChangeEdit event.

• OnInit event.

• OnObjectChange event.

• OnObjectChangeEdit event.

• OnSaveEdit event.

• OnSavePreChange event.

• OnSavePostChange event.

Event Sets

To open these events from a synchronizable component interface in PeopleSoft Application Designer, select the component interface, then right-click and select View PeopleCode from the pop-up menu.

The mobile device events occur on the mobile device, as the device works with the data from the working set.

Note. Other events are listed on the synchronized component interface, such as OnValidate and OnGetProperty. These events occur on the synchronization server (which is a part of the application server). They do not run on the mobile device.

See Also

SyncServer Class

OnChange Event

The OnChange event is similar to the FieldChange event.

You use OnChange PeopleCode to recalculate mobile page field values, change the appearance of page controls, run upon a button being clicked, or perform other processing that results from a field change other than data validation.

To validate the contents of the field, use the OnChangeEdit event. The OnChange event occurs on the specific mobile page field and row that just changed.

Do not use error or warning statements in OnChange PeopleCode: these statements cause a runtime error that forces the user to cancel the page without saving changes.

OnChange PeopleCode is often paired with OnInit PeopleCode. In these OnInit and OnChange pairs, the OnInit PeopleCode checks values in the working set and initializes the state or value of properties (fields) accordingly. OnChange PeopleCode then rechecks the values in the working set during page execution and resets the state or value of properties (fields).

If a user has changed a property and presses Tab to leave the row (or page), the OnObjectChange event initiates after OnChange.

The OnObjectChange event does not run if the user clicks either the Cancel button or the browser's Back button.

OnChangeEdit Event

The OnChangeEdit event is similar to the FieldEdit event.

You use OnChangeEdit PeopleCode to validate the contents of a mobile page field, supplementing the standard system edits. If the data that the user entered for that field does not pass the validation, the PeopleCode program should display a message using the Error statement, which redisplays the page, displays an error message, and turns the mobile page field red.

To permit the edit, but alert the user to a possible problem, use a Warning statement instead of an Error statement. A Warning statement displays a warning dialog box with OK and Explain buttons. It permits mobile page field contents to be changed and continues processing as usual after the user clicks OK.

If the validation is checking for consistency across multiple page fields, use OnSaveEdit PeopleCode instead of OnChangeEdit.

OnInit Event

The OnInit event is similar to the RowInit event.

The OnInit event occurs as each mobile object is loaded into the working set. This also applies when a newly created object is loaded into the working set.

Note. The mobile object represents the PeopleSoft Pure Internet Architecture equivalent of a row of data, and can be used at any level in the data hierarchy: level zero, level one, level two, and so on. The mobile object is displayed in the detail view of a mobile page.

See Understanding the Mobile Device and the Component Interface.

Since the working set contains only objects that are actually accessed, the OnInit events occur over time. In PeopleSoft Pure Internet Architecture, the RowInit events are called all together, when the component buffers are built.

OnChange PeopleCode is often paired with OnInit PeopleCode.

Note. Do not use Error or Warning statements in OnInit PeopleCode: these cause a runtime error and force the user to cancel the component without saving.

OnObjectChange Event

The OnObjectChange event occurs when a user navigates away from a mobile object. This includes such actions as moving from one tab to another on a mobile page, pressing Tab to leave a row on a detail view, or clicking the Save button. OnObjectChange is only triggered by changes to the GUI.

OnObjectChange only runs for rows that have actually changed. For example, if the user selects a check box on a row in a collection, and the OnChange PeopleCode associated with the check box changes every other row in the collection, OnObjectChange only runs for the row that was changed by the GUI.

If a user changes the main object as well as a row in a collection list view that both have OnObjectChange PeopleCode, and then the user leaves the main object, the OnObjectChange event runs for the row before it runs for the main object.

The OnObjectChange event also runs for the main object if a change has been made, and the user does not leave the main object but clicks the Save button. If the user has made a change to a row in a collection list view, and then clicks the Save button, OnObjectChange also runs, because the user left the row.

If a user changes a property on a collection list view row that has the OnChange event, and then the user leaves the row, OnChange runs before the OnObjectChange event for the row (if there is OnChange PeopleCode associated with the property). If a user changes a property on a collection list view row that has the OnChange event, and then leaves the row by selecting a check box on a second row that has OnChange PeopleCode, OnChange runs for the property on the first row, then the OnObjectChange event runs for the first row, and then OnChange runs on the check box.

If a user changes a property on a collection list view row that has the OnChange event, and then leaves the row, OnChange runs before the OnObjectChange event for the row, if OnObjectChange is present. If a user changes a property on a collection list view row that has the OnChange event, and then leaves the row by selecting a check box on a second row that has OnChange, OnChange runs for the property on the first row, then the OnObjectChange event runs for the first row, and finally OnChange runs on the check box.

The OnObjectChange event does not run if a user clicks either the Cancel button or the browser's Back button.

OnObjectChangeEdit Event

The OnObjectChangeEdit event occurs when a user navigates away from a mobile object. This includes such actions as moving from one tab to another on a mobile page,pressing Tab to leave a row on a detail view, or clicking the Save button. OnObjectChangeEdit is only triggered by changes to the GUI.

The OnObjectChangeEdit event runs before the OnObjectChange event.

The OnObjectChangeEdit event only runs for rows that have actually changed. For example, if a user selects a check box on a row in a collection, and the OnChange PeopleCode associated with the check box changes every other row in the collection, OnObjectChangeEdit only runs for the row that was changed by the GUI.

If a user changes the main object as well as a row in a collection list view that both have OnObjectChangeEdit PeopleCode, and then the user leaves the main object, the OnObjectChangeEdit event runs for the row before it runs for the main object.

The OnObjectChangeEdit event also runs for the main object if a change has been made, and the user does not leave the main object but clicks the Save button. If the user has made a change to a row in a collection list view, and then clicks the Save button, the OnObjectChangeEdit event also runs, because the user left the row.

If a user changes a property on a collection list view row that has the OnChange event, and then the user leaves the row, OnChange runs before the OnObjectChangeEdit event for the row (if there is OnChange PeopleCode associated with the property). If a user changes a property on a collection list view row that has the OnChange event, then leaves the row by selecting a check box on a second row that has OnChange PeopleCode, OnChange runs for the property on the first row, then the OnObjectChangeEdit event runs for the first row, and then OnChange runs on the check box.

If a user changes a property on a collection list view row that has the OnChange event, and then leaves the row, OnChange runs before the OnObjectChangeEdit event for the row, if OnObjectChangeEdit is present. If a user changes a property on a collection list view row that has the OnChange event, and then leaves the row by selecting a check box on a second row that has OnChange, OnChange runs for the property on the first row, then the OnObjectChangeEdit event runs for the first row, and finally OnChange runs on the check box.

The OnObjectChangeEdit event does not run if the user clicks either the Cancel button or the browser's Back button.

OnSaveEdit Event

The OnSaveEdit event is similar to the SaveEdit event. The OnSaveEdit event runs for every modified object in the working set.

The OnSaveEdit event occurs whenever the user tries to save the component (clicks the Save button). Use OnSaveEdit PeopleCode to validate the consistency of data in the mobile object user-defined properties. Whenever a validation involves more than one property, use OnSaveEdit PeopleCode. If a validation involves only one property, use OnChangeEdit PeopleCode.

An Error statement in OnSaveEdit PeopleCode displays a message and redisplays the mobile page without saving data. A warning enables the user to click OK and save the data, or click Cancel and return to the mobile page without saving.

OnSavePostChange Event

The OnSavePostChange event is similar to the SavePostChange event.

The OnSavePostChange event occurs after the object is saved. Use OnSavePostChange PeopleCode to update peer references.

Note. An error or warning in OnSavePostChange PeopleCode causes a runtime error, forcing the user to cancel the mobile page without saving changes. Avoid errors and warnings in this event.

The system issues a Structured Query Language (SQL) Commit statement after OnSavePostChange PeopleCode completes successfully.

OnSavePreChange Event

The OnSavePreChange event is similar to the SavePreChange event.

The OnSavePreChange event runs after tje OnSaveEdit event completes without errors. OnSavePreChange PeopleCode provides one final opportunity to manipulate data before the system updates the database on the mobile device.

Note. An error or warning in OnSavePostChange PeopleCode causes a runtime error, forcing the user to cancel the mobile page without saving changes. Avoid errors and warnings in this event.

Mobile Event Flow

This section discusses:

• General event order.

• Event order when a page is saved.

General Event Order

Mobile events run only if there is a PeopleCode program associated with the event. The following is the general running order of the mobile events.

1. Initialize the mobile object data with the OnInit event.

   This event occurs when a mobile object is first entered into the working set, either from the database or when it is created.

2. Change property values with the OnChangeEdit or OnChange events.

   These events run only in response to a change in the GUI.

3. Navigate off a mobile object that has had its values changed with the OnObjectChangeEdit or OnObjectChange events.

   These events run only in response to a change in the GUI.

4. Save the page with the OnSaveEdit, OnSavePreChange, and OnSavePostChange events.

The following diagram shows how data is initialized and brought into the working set:

Reading a mobile object into the working set

The following diagram shows the event flow for when a property changes:

Changing a mobile page field (component interface property)

Event Order When a Page Is Saved

When a user clicks the Save button, the mobile save events operate as follows:

1. The OnChangeEdit, OnChange, OnObjectChangeEdit and OnObjectChange events run on the current mobile objects as applicable.

2. The system obtains the top parent on the current mobile object that is displayed in the mobile page detail view.

3. Working from the top parent down, a depth-first, top-to-bottom traversal of the working set hierarchy occurs, and for every modified mobile object found, the system checks the required fields.

   If a required field is not filled in correctly, the save is stopped and the field is highlighted in red.

4. Working from the top parent down, a depth-first, top-to-bottom traversal of the working set hierarchy occurs.

   For every modified mobile object found, the OnSaveEdit PeopleCode runs.

5. Working from the top parent down, a depth-first, top-to-bottom traversal of the working set hierarchy occurs.

   For every modified mobile object found, the OnSavePreChange PeopleCode runs.

6. Working from the top parent down, a depth-first, top-to-bottom traversal of the working set hierarchy occurs.

   For every modified mobile object found, the OnSavePostChange event PeopleCode runs.

The depth-first, top-to-bottom traversal of the working set hierarchy works by processing each child mobile object in the working set. For each child, processing is recursively invoked, causing that child to be processed. Then, for each of the child's children, processing is also recursively invoked.

The following is a diagram of the save process:

Saving a mobile object