As with widgets in the Telligent Community platform, JavaScript can be included to provide user interactivity such as performing REST requests or changing UI state. The same JavaScript (and REST) APIs are available within Telligent Community Mobile, with the addition of mobile-specific APIs for manipulating the mobile shell, handling mobile-specific events, and rendering mobile-specific UI.
[toc]
Referencing Script
To reduce HTTP requests, a recommended pattern in mobile widgets is to include JavaScript inline instead of through external references.
Whereas a standard widget may include a separate ui.js
attachment and reference it externally at the end of page,
#registerEndOfPageHtml('widgetname') <script type="text/javascript" src="$core_v2_widget.GetFileUrl("ui.js")"></script> #end
A mobile widget could still decouple the widget's script in a separate ui.js
attachment for simplified development, but instead render it inline:
<script>$core_v2_widget.RenderFile('ui.js')</script>
Initialization
Whereas standard widgets are rendered in traditional web pages that load synchronously, mobile widgets are rendered in pages hosted within the mobile shell's asynchronous single page app. This requires handling mobile-specific events when initializing widget script, insted of just jQuery's document ready.
Assuming ui.js
defines myNameSpace.myWidget
:
<script>$core_v2_widget.RenderFile('ui.js')</script> <script> jQuery(document).ready(function(){ jQuery.telligent.evolution.messaging.subscribe('mobile.content.rendered', function(){ myNameSpace.myWidget.register({ // data passed to widget script }); }); }) </script>
Note the use of both document ready as well as mobile.content.rendered, which isn't published until the widget's host page is shown within the shell.
Message Scoping
Publishing and subscribing to messages work the same as in standard widgets, with the added support for region scopes.
Scope defines message handlers' lifetime. When the scope is navigation
, a refresh of the navigation region unsubscribes any handlers subscribed with that scope. When the scope is content
, a refresh of the content or any other navigation-triggered content loading unsubscribes any handlers previously subscribed with the content
scope. When the scope is global, handlers remain subscribed persistently. The default is content
.
Gestures
The same pointer and gesture events defined by the platform API such as pointerstart, pointerend, tap, swipe, and pan are available to mobile. And similar to the platform, binding to the click
event is identical to binding to tap.
In the scenario that a widget explicitly handles panning or swiping events or contains a scrollable element, it is often useful to prevent the propagation of pan and swipe events from bubbling up to the shell where they could inadvertently open the navigation menu.
$('SCROLLABLE_ELEMENT').on('pan swipe', function(e){ e.stopPropagation(); });