This guide explores Telligent Community Mobile's support around working with forms, including standardized UI and navigational patterns.
[toc]
Markup Formats
Styling is available for all standard form input types.
Example:
The following
<fieldset>
<!-- Text Area -->
<div class="form-field textarea">
<textarea placeholder="Text area with no label"></textarea>
</div>
<!-- Text Input -->
<div class="form-field text ">
<input id="input4" type="text" placeholder="Text input with no label" />
</div>
<!-- Text Input with a Label -->
<div class="form-field text">
<label for="input2">Label</label>
<input id="input2" type="text" placeholder="Text input with a label" />
</div>
<!-- Text Input with an Inline Label -->
<div class="form-field text inline-label">
<label for="input3">Inline Label</label>
<input id="input3" type="text" placeholder="Text input with an inline label" />
</div>
<!-- Checkboxes -->
<div class="form-field checkbox inline-label">
<label for="input5">Unchecked Checkbox</label>
<input id="input5" type="checkbox" />
</div>
<div class="form-field checkbox inline-label">
<label for="input6">Checked Checkbox</label>
<input id="input6" type="checkbox" checked/>
</div>
<!-- Select -->
<div class="form-field select">
<select>
<option value="a">Select Value A</option>
<option value="b">Select Value B</option>
<option value="c">Select Value C</option>
<option value="d">Select Value D</option>
</select>
</div>
<!-- Invalid Field State -->
<div class="form-field text invalid">
<label for="input7">Label</label>
<input id="input7" type="text" placeholder="Invalid text input" />
<span class="validation-message">Validation Message</span>
</div>
</fieldset>
Produces
Navigation
By default, mobile content pages are both refreshable (including pull-to-reresh on some platforms) and stored in the local navigation history. A common pattern with forms is to prevent both of these.
$.telligent.evolution.mobile.refreshable(false); $.telligent.evolution.mobile.excludeFromHistory();
This prevents accidental refreshing and clearing of a form, as well as maintaining the hierarchical sense of position when navigating "back" in the stack. For example, the Create Status widget includes the following in its content script:
<script> jQuery(function(){ jQuery.telligent.evolution.messaging.subscribe('mobile.content.rendered', function(){ // ... excerpt ... jQuery.telligent.evolution.mobile.refreshable(false); jQuery.telligent.evolution.mobile.excludeFromHistory(); }); }); </script>
Header Actions
Presenting form buttons
The app header region supports adding elements via setHeaderButton(). setHeaderButton() sets an element to render in the top right of the header area. The element can have its own event handlers bound to it, and is safely removed on the next content load or refresh. A common pattern is to setHeaderButton() to present both links to forms as well as form submission buttons.
For example, the Activity Stream widget displays +
via setHeaderButton() to link to the Create Status page:
// given createStatusLabel and createStatusUrl, var postLink = $('<a href="#" class="add">' + createStatusLabel + '</a>').on('tap', function(e) { $.telligent.evolution.mobile.clearContent(); $.telligent.evolution.mobile.load(createStatusUrl); }); $.telligent.evolution.mobile.setHeaderButton(postLink);
Note the use of clearContent() to force a refresh of the current activity stream page on the next viewing of it.
Handling form input
In the Create Status widget, the same setHeaderButton() method is used to present a "Post" button.
var postLink = $('<a href="#" class="submit">' + postLabel + '</a>'); $.telligent.evolution.mobile.setHeaderButton(postLink);
The form submission can then be handled:
postLink.on('tap', function(){ createStatus(messageBody); return false; });
createStatus
can then use the REST endpoint for creating status messages:
function createStatus(messageBody) { // display a loading indicator while processing $.telligent.evolution.mobile.showLoading(); $.telligent.evolution.post({ url: jQuery.telligent.evolution.site.getBaseUrl() + 'api.ashx/v2/users/{UserId}/statuses.json', data: { UserId: $.telligent.evolution.user.accessing.id, MessageBody: 'messagebody' } }).done(function(){ // on success, navigate back to the previous page $.telligent.evolution.mobile.back(true); }).fail(function(){ // on error, hide the loading indicator $.telligent.evolution.mobile.hideLoading(); }); }
Note the use of showLoading() during processing. On failure, it is explicitly hidden. On success, the navigation using back() automatically hides the loading indicator and removes the added Post button.
Specialized Input Types
File Uploading
File uploading can be achieved using the standard glowUpload
jQuery plugin from the core platform. The typical use pattern is:
/* Given the following variables in scope: * * fileUpload: an `a` link to begin uploading a file * uploadFileUrl: an upload URL created with * #set($contextId = $core_v2_uploadedFile.CreateContextId()) * $core_v2_uploadedFile.GetUploadUrl($contextId) * progressMessage: "Uploading ({0}%)..." * changeFileMessage: "Change file" */ $(fileUpload).glowUpload({ fileFilter: null, uploadUrl: uploadFileUrl, renderMode: 'link' }).on({ glowUploadBegun: function(e) { fileUpload.html(progressMessage.replace('{0}', 0)); }, glowUploadFileProgress: function(e, details) { fileUpload.html(progressMessage.replace('{0}', details.percent)); }, glowUploadComplete: function(e, file) { loadPreview(context, file.name); fileUpload.html(changeFileMessage).removeClass('upload').addClass('change'); fileRemove.show(); } });
This will present an upload button which, when tapped, presents a device-specific upload UI. (For example, an iOS user will have the option of selecting a photo or taking a new one from the camera.) Once selected, the upload button is replaced with an upload progress message, finally showing a preview of the uploaded file with a remove buton.
As the other details do not differ from the core platform, please refer to the full implementation of the Create Status form widget.
Mentions and hashtags
Mentions and hashtags are presented using the same evolutionComposer jQuery plugin with the 'mentions' and 'hashtags' composer plugins from the core platform.
Rich text considerations
Rich text is not editable on mobile. Whereas a widget call to $core_v2_editor.Render would result in a rich text editor on desktop scale browsers, it instead renders a plain text editor on mobile. If the editor is instantiated with existing rich text, the content is uneditable.