Mobile widget development is designed to be familiar to those with experience developing Studio Widgets against the platform APIs within Widget Studio. Both the language and structure of widgets as well as most of the APIs remain supported on mobile. Mobile does supplement the platform APIs with mobile-specific functionality.
Table of Contents
These mobile-specific APIs are primarily targeted at interacting with the mobile shell. The mobile shell is the framework supporting mobile's implementation as a single page application. While widgets are rendered on the server side within host "pages", all navigation is implemented on the client side.
The three regions of the mobile shell include:
Header and Content
The contents of the
navigation regions are defined by mobile widget instances in mobile pages. The contents of the center and right of the header are defined by APIs available to widgets, including setHeaderContent() and setHeaderButton(). The contents of the left side of the header are defined by the navigational placement and device being used to access. For example, if a user is at the root (site home), then the left-most button is a menu icon opening navigation. If navigated in elsewhere, the left-most button is transitioned to a "back" button instead, except on environments like Android or the Mobile Safari on iOS that already support a hardware or software back button.
Navigation is performed asynchronously, loading new pages and replacing the old within the shell.
When a URL is loaded (either as the result of tapping an
anchor, tapping a list item with a data-targeturl, refreshing the current content, or explicitly calling load, if it references a mobile-defined page, that page's content is loaded directly into the shell.
If the URL is a remote-proxied URL (for example, a URL contained within an entity returned from an API call), then data about the URL is first requested to deteremine whether there is an applicable mobile-specific page. If so, then that page is loaded. Otherwise, the non-proxied page is loaded in a manner relevant to the device (within the web brwoser, in an iframe on homescreened web apps, or a child browser in native). These URLs are then client-cached to prevent subsequent lookups for the same proxied URLs.
URLs and their content are also cached locally in the navigation stack. The stack enables the back button to function immediately, enables storing current scroll position of previously viewed pages, and enables detecting which direction to effectively navigate.
When a URL is requested, the stack is inspected to see if the URL has been previously visited. If so, it reloads the contents of that URL, animates the page in with a backward motion, and removes all cached URLs and content that occurred after the current position.
For example, consider a user is on the site root (seeing a menu icon in the top left), opens the menu, and navigates to a bookmarked gorup from the navigation menu.
The group's page slides in from the right and the stack then contains two items, site root and the group, and the menu button turns into a back button (in environments without a device back button). Navigating back immediately slides the site's cached home page back in from the left and returns the stack to one item.
If instead, the user navigates to the group homepage, then to a forum, forum thread, each of these transitions would be in a forward direction, and the stack would contain
Then if the user taps the name of the forum's group within the forum thread page, the entire stack would navigate back to the group home page with a backward direction, moving back up the stack since the URL being loaded was detected as already existing in the stack.
It is in this manner that the illusion of hierarchy is maintained even within otherwise-cyclical navigation paths and deeply nested group and application structures.
While it is useful to understand the process of redirection and navigation in the mobile API, they should typically be invisible both to the user as well as to the developer except when using explicit mobile APIs such as:
- home: Defines the default widgets on the mobile root page
- navigation: Defines the widgets rendered in the navigation region
- login: Defines the widgets rendered in the login experience
Zimbra Community's Widget Studio can be used to create widgets in a format exportable to the mobile components. Additionally, mobile widgets can be edited on the file system. More information is available in Managing Widget Files.