The functionality of the user experience of Telligent Community Mobile is defined using widgets, specifically by placing widgets on pages within the mobile experience. The topics discussing widgets in Telligent Community apply to Telligent Community Mobile as well.
When developing widgets for Telligent Community Mobile, all of the Widget APIs and JavaScript APIs from the community associated to the mobile application are available to widgets within the mobile experience as well as the APIs specific to Telligent Community Mobile.
Mobile Concepts
Widgets
Like standard widgets, mobile widgets are written and executed on the server side in the Velocity language. Like standard widgets, they can be written within the widget editor in Telligent Community, including attachments, JavaScript, and language resources.
APIs
Nearly all of the core platform APIs available to standard wigets in the form of Widget APIs, REST APIs, and JavaScript APIs are also available to mobile widgets. These APIs are proxied via the Remote Studio Widget framework to the mobile components to provide transparent support to mobile widgets, including third party APIs installed in the host community.
In addition to the platform APIs, mobile widgets also have access to mobile-specific JavaScript APIs and Widget APIs.
The Mobile Shell
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
Navigation
The contents of the content
and 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
Navigation is performed asynchronously, loading new pages and replacing the old within the shell.
Redirection
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 determine 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 browser, 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.
The Stack
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.
Navigation and the API
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:
- $.telligent.evolution.mobile.load()
- $.telligent.evolution.mobile.back()
- $.telligent.evolution.mobile.clearContent()
- $.telligent.evolution.mobile.setExpiration()
- $.telligent.evolution.mobile.excludeFromHistory()
Pages
Mobile pages host mobile widgets. While most pages are arbitrary, some are specially meant for specific purposes.
- 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
Development Process
Telligent Community's widget editor 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 Mobile Widget Files.