Client-side Mobile Application JavaScript Methods
The ZnetDK for Mobile framework is invoked through the JavaScript znetdkMobile
object (since version 2.9, the shorten z4m
global variable can be used instead).
Its source code is defined in the mobile.js
JavaScript library located in the INSTALL_DIR/engine/public/js/
folder.
From a ZnetDK view, call inside a <script>
block, the methods you need among those described on this page.
HTML Attributes | JS Properties | JS Methods | JS Events.
The ZnetDK data list is loaded from a remote PHP controller action by page of 20 data rows according to the infinite scrolling pattern.
Here is an example of a ZnetDK view with the minimum HTML and JavaScript code required to load list items from the all
action of the MyCtrl
controller, and then display them.
The number of rows per page is changed to 40 rows (rowsPerPage
property is set to 20 by default) to take in account the reduced height of each item element.
<ul id="contactlist" class="w3-ul" data-zdk-load="myctrl:all">
<li>{{label}}</li>
</ul>
<script>
znetdkMobile.list.rowsPerPage = 40;
znetdkMobile.list.make('#contactlist');
</script>
See the Tutorial page for a complete sample code
And to be complete, you will find below the PHP source code of the MyCtrl
controller that provides on demand the item labels to display in the list.
<?php
namespace app\controller;
class MyCtrl extends \AppController {
static protected function action_all() {
$maxItems = 100; // Display of 100 items max.
$request = new \Request();
$first = $request->first; // The first item number (zero-based value)
$rowCount = $request->count; // The number of items requested (40 rows in this example)
$items = array();
for ($index = $first; $index < $first+$rowCount && $index < $maxItems; $index++) {
$items[] = array('label' => "Item $index");
}
$response = new \Response();
$response->total = $maxItems;
$response->rows = $items;
return $response; // As JSON format
}
}
?>
Each call to the myctrl:all
PHP controller action to get the items to be displayed in the list is done in AJAX according to the POST method with the paramaters first
and count
.
The first
POST property contains the first item number to display in the list (value 0 when called for the first time) while the count
POST property indicates the number of items requested (value 40 in this example).
data-zdk-load
<ul id="contactlist" data-zdk-load="myctrl:all"></ul>
data-zdk-autocomplete
<ul id="contactlist" data-zdk-load="myctrl:all" data-zdk-autocomplete="myctrl:suggestions"></ul>
data-id
<ul id="contactlist" data-zdk-load="myctrl:all">
<li data-id="{{id}}">
<a class="edit">{{name}}</a>
</li>
</ul>
znetdkMobile.list
properties
rowsPerPage
,
heightDiffForNewPage
,
uniqueSearchedKeyword
,
beforeInsertRowCallback
,
afterInsertRowCallback
,
loadedCallback
beforeSearchRequestCallback
rowsPerPage
rowsPerPage
<script>
znetdkMobile.list.rowsPerPage = 40;
</script>
heightDiffForNewPage
heightDiffForNewPage
<script>
znetdkMobile.list.heightDiffForNewPage = 300;
</script>
uniqueSearchedKeyword
uniqueSearchedKeyword
<script>
znetdkMobile.list.uniqueSearchedKeyword = true;
</script>
beforeInsertRowCallback
beforeInsertRowCallback
<script>
/* In this example, a new 'is_alert' property is added to the original row data object
from the existing 'alert' property. So the new property can be displayed in the data list. */
var list = znetdkMobile.list.make('#my-list');
list.beforeInsertRowCallback = function(rowData) {
rowData.is_alert = rowData.alert.length > 0 ? 'yes' : '';
};
</script>
afterInsertRowCallback
afterInsertRowCallback
<script>
var list = znetdkMobile.list.make('#my-list');
list.afterInsertRowCallback = function(newRowEl) {
// Do something, the newRowEl variable contains <li> element in jQuery.
};
</script>
loadedCallback
loadedCallback
<script>
var list = znetdkMobile.list.make('#my-list');
list.loadedCallback = function(rowCount, pageNumber) {
console.log('List is loaded', rowCount, pageNumber, this.rowsPerPage);
};
</script>
beforeSearchRequestCallback
beforeSearchRequestCallback
<script>
/* In this example, the 'search_criteria' POST parameter
replaces the default 'keyword' parameter. */
var list = znetdkMobile.list.make('#my-list');
list.beforeSearchRequestCallback = function(requestData) {
if (requestData.hasOwnProperty('keyword')) {
requestData.search_criteria = requestData.keyword[0];
delete requestData.keyword;
}
};
</script>
znetdkMobile.list
methodsmake()
, setCustomSortCriteria()
, setModal()
, refresh()
make()
znetdkMobile.list.make()
<script>
var list = znetdkMobile.list.make('#my-list', true, false);
</script>
setCustomSortCriteria()
znetdkMobile.list.setCustomSortCriteria()
<script>
var list = znetdkMobile.list.make('#my-list');
list.setCustomSortCriteria({
id: 'Person # (default)',
name: 'Name',
city: 'City',
country: 'Country'
}, 'id');
</script>
setModal()
znetdkMobile.list.setModal()
<script>
var list = znetdkMobile.list.make('#my-list');
list.setModal('#my-modal', true, function(innerForm){
// NEW ITEM
this.setTitle('New item');
innerForm.setInputValue('status', 'Draft');
}, function(innerForm, response) {
// EDIT ITEM
this.setTitle('Edit the item');
innerForm.setInputValue('status', response.status);
});
</script>
refresh()
znetdkMobile.list.refresh()
<script>
var list = znetdkMobile.list.make('#my-list');
$('#my-button').on('click', function() {
list.refresh();
});
</script>
znetdkMobile.list
eventsafterpageloaded
afterpageloaded
event
<script>
$('#my-list').on('afterpageloaded', function (event, listObj, rowCount, pageNumber) {
console.log(listObj, rowCount, pageNumber);
});
</script>
Displays a modal dialog box suitable for mobile devices with only a few lines of code.
<!-- Button to display the modal dialog -->
<button id="my-button" class="w3-button w3-theme-action">Show modal</button>
<!-- The modal dialog definition -->
<div id="my-modal" class="w3-modal">
<div class="w3-modal-content">
<div class="w3-container">
<h4>My modal dialog box</h4>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse aliquet ornare...</p>
<button type="button" class="cancel w3-button w3-red w3-margin-bottom">Close</button>
</div>
</div>
</div>
<!-- The modal is displayed on button click -->
<script>
$('#my-button').on('click', function(){
var modalObject = znetdkMobile.modal.make('#my-modal');
modalObject.open();
});
</script>
znetdkMobile.modal
methods
make()
,
getInnerForm()
,
open()
,
close()
,
setTitle()
make()
znetdkMobile.modal.make()
<script>
var modal = znetdkMobile.modal.make('#my-modal', 'myview', function(){
console.log('View loaded.', this);
});
</script>
getInnerForm()
znetdkMobile.modal.getInnerForm()
<script>
var modal = znetdkMobile.modal.make('#my-modal');
var form = modal.getInnerForm();
</script>
open()
znetdkMobile.modal.open()
<script>
var modal = znetdkMobile.modal.make('#my-modal');
modal.open(submitCallback, closeCallback, 'my-input');
function submitCallback(response) {
console.log('Submit success!');
}
function closeCallback() {
console.log('Modal closed!');
}
</script>
close()
znetdkMobile.modal.close()
<script>
var modal = znetdkMobile.modal.make('#my-modal');
modal.open();
setTimeout(function() { modal.close(); }, 5000);
</script>
setTitle()
znetdkMobile.modal.setTitle()
<script>
var modal = znetdkMobile.modal.make('#my-modal');
modal.setTitle('My title');
</script>
znetdkMobile.modal
events
beforeshow
,
aftershow
,
beforehide
,
afterhide
beforeshow
beforeshow
event
<script>
$('#my-modal').on('beforeshow', function (event, modalObj) {
console.log(modalObj);
});
</script>
aftershow
aftershow
event
<script>
$('#my-modal').on('aftershow', function (event, modalObj) {
console.log(modalObj);
});
</script>
beforehide
beforehide
event
<script>
$('#my-modal').on('beforehide', function (event, modalObj) {
console.log(modalObj);
});
</script>
afterhide
afterhide
event
<script>
$('#my-modal').on('afterhide', function (event, modalObj) {
console.log(modalObj);
});
</script>
Connect an HTML input form to the actions of the remote PHP controller to load and submit its data.
<!-- Input form definition -->
<form id="my-form" class="w3-container" data-zdk-load="myctrl:detail"
data-zdk-submit="myctrl:submit">
<div class="w3-section">
<label class="zdk-required"><b>Name</b></label>
<input class="w3-input w3-border w3-margin-bottom" type="text" name="name" required>
<label><b>City</b></label>
<input class="w3-input w3-border" type="text" name="city">
<button class="w3-button w3-block w3-green w3-section w3-padding" type="submit">Submit</button>
</div>
</form>
<!-- Input form initialization -->
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.load();
</script>
<?php
namespace app\controller;
class MyCtrl extends \AppController {
static protected function action_detail() {
$response = new \Response();
$response->name = 'John DOE';
$response->city = 'Tokyo';
return $response;
}
static protected function action_submit() {
$request = new \Request();
$response = new \Response();
$response->setSuccessMessage('Submit', "Name= {$request->name}, city= {$request->city}");
return $response;
}
}
?>
data-zdk-load
<form id="myform" data-zdk-load="myctrl:detail"></form>
data-zdk-submit
<form id="myform" data-zdk-submit="myctrl:store"></form>
znetdkMobile.form
methods
make()
,
load()
,
init()
,
reset()
,
getInputValue()
,
setInputValue()
,
setDataModifiedState()
,
isModified()
,
showError()
,
hideError()
,
setFocus()
,
setReadOnly()
make()
znetdkMobile.form.make()
<script>
var myForm = znetdkMobile.form.make('#my-form', onSubmit);
function onSubmit(response) {
console.log('Submit succeeded!', response);
}
</script>
load()
znetdkMobile.form.load()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.load(57, onLoadingSuccess);
function onLoadingSuccess(response) {
console.log('Loading succeeded!', response);
}
</script>
init()
znetdkMobile.form.init()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.init({
firstname: 'John',
lastname: 'Doe',
age: 34
});
</script>
reset()
znetdkMobile.form.reset()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.reset();
</script>
getInputValue()
znetdkMobile.form.getInputValue()
<!-- Exemple of view -->
<form id="my-form">
<label>Lastname</label>
<input name="lastname">
<button type="button" onclick="onClick();">Click me</button>
</form>
<script>
function onClick() {
var myForm = znetdkMobile.form.make('#my-form');
console.log(myForm.getInputValue('lastname'));
}
</script>
setInputValue()
znetdkMobile.form.setInputValue()
<!-- Exemple of view -->
<form id="my-form">
<label>Lastname</label>
<input name="lastname">
</form>
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.setInputValue('lastname', 'DOE');
</script>
setDataModifiedState()
znetdkMobile.form.setDataModifiedState()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.setDataModifiedState(false);
</script>
isModified()
znetdkMobile.form.isModified()
<script>
var myForm = znetdkMobile.form.make('#my-form');
console.log(myForm.isModified());
</script>
showError()
znetdkMobile.form.showError()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.showError('Value is invalid!', 'my_input');
</script>
hideError()
znetdkMobile.form.hideError()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.hideError();
</script>
setFocus()
znetdkMobile.form.setFocus()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.setFocus('firstname');
</script>
setReadOnly()
znetdkMobile.form.setReadOnly()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.setReadOnly();
</script>
Standard action buttons can be displayed at fixed position on a view. These are Refresh, Add, Search and Back to top buttons.
znetdkMobile.list.make()
method with refresh
parameter set to true
.znetdkMobile.list.make()
method with search
parameter set to true
.znetdkMobile.list.setModal()
method with onAdd
parameter set to a valid function.Additional custom action buttons can also be declared and displayed if required.
znetdkMobile.action
methods
registerView()
,
addCustomButton()
,
removeCustomButton()
,
toggle()
registerView()
<script>
// "Back to top" button displayed for the 'myviewid' view.
znetdkMobile.action.registerView('myviewid', {
scrollup: {
isVisible: true,
callback: function () {
alert('Button clicked!');
}
}
});
</script>
addCustomButton()
<script>
znetdkMobile.action.addCustomButton('mybutton', 'fa-print', 'w3-yellow');
</script>
removeCustomButton()
<script>
znetdkMobile.action.removeCustomButton('mybutton');
</script>
toggle()
<script>
znetdkMobile.action.toggle();
</script>
The ZnetDK autocomplete component displays suggestions provided by a remote PHP controller action while the user enters text.
Below a simple example of view with autocompletion.
<input id="my-autocomplete" class="w3-input" type="search">
<script>
znetdkMobile.autocomplete.make('#my-autocomplete', {
controller: 'myctrl',
action: 'suggestions'
});
</script>
And an example of PHP controller that returns suggestions from the text entered by the user.
The entered text in the autocomplete field is sent through the query
POST parameter.
<?php
namespace app\controller;
class MyCtrl extends \AppController {
static protected function action_suggestions() {
$request = new \Request();
$keyword = $request->query; // Text entered in the autocomplete field
$response = new \Response();
$suggestions = array();
if ($keyword === 'a' || $keyword === 'ab' || $keyword === 'abc') { {
$suggestions[] = array('label' => 'abc');
$suggestions[] = array('label' => 'abcd');
$suggestions[] = array('label' => 'abcde');
}
$response->setResponse($suggestions); // Suggestions matching the entered text
return $response;
}
}
?>
znetdkMobile.autocomplete
properties
minStringLength
,
delay
,
maxNumberOfCachedItems
,
cacheLifetime
minStringLength
minStringLength
<script>
znetdkMobile.autocomplete.minStringLength = 3;
</script>
delay
delay
<script>
znetdkMobile.autocomplete.delay = 1000;
</script>
maxNumberOfCachedItems
maxNumberOfCachedItems
<script>
const myList = znetdkMobile.autocomplete.make('#my-autocomplete', {
controller: 'myctrl',
action: 'suggestions'
});
myList.maxNumberOfCachedItems = 20;
</script>
cacheLifetime
cacheLifetime
<script>
const myList = znetdkMobile.autocomplete.make('#my-autocomplete', {
controller: 'myctrl',
action: 'suggestions'
});
myList.maxNumberOfCachedItems = 20;
myList.cacheLifetime = 'selection';
</script>
znetdkMobile.autocomplete
methodsmake()
znetdkMobile.autocomplete.make()
<input id="my-autocomplete" class="w3-input" type="search">
<script>
znetdkMobile.autocomplete.make('#my-autocomplete', {
controller: 'myctrl',
action: 'suggestions'
}, onSelection, onRendering);
/* Function called when a suggestion is selected */
function onSelection(selectedItem) {
console.log(selectedItem.label);
}
/* Function called before rendering the list of suggestions */
function onRendering(item) {
return '<b>' + item.value + '</b> - <i>' + item.label + '</i>';
}
</script>
Displays a message to the user by calling a simple method in JavaScript.
<script>
znetdkMobile.messages.add('info', 'Information', 'Message for information...');
znetdkMobile.messages.add('warn', 'Warning', 'Message for warning...');
znetdkMobile.messages.add('error', 'Error', 'Message when error occured...');
</script>
<script>
znetdkMobile.messages.showSnackbar('Message when success...');
</script>
<script>
znetdkMobile.messages.notify('Notification to the user', 'Notification message...', null, function() {
alert('Click on OK button');
});
</script>
<script>
znetdkMobile.messages.ask('Asking for the user', 'Do you really want to do it right now?', null, function(isYes) {
var buttonPressed = isYes ? 'YES' : 'NO';
alert('Click on ' + buttonPressed + ' button');
});
</script>
Performs an AJAX request to a remote PHP controller action for getting data or executing a process. This feature is based on the jQuery ajax()
method.
Here is an example of AJAX call to the myctrl
controller and its sum
action, passing the values to be summed as POST parameters and finally specifying a callback function to execute when the request is complete.
<script>
znetdkMobile.ajax.request({
controller: 'myctrl',
action: 'sum',
data: {value1: 13, value2: 22},
callback: function (response) {
znetdkMobile.messages.add('info', 'Result', response.result, false);
}
});
</script>
See below the source code of the Myctrl:action_sum()
PHP controller action executed in response to this AJAX request.
<?php
namespace app\controller;
class MyCtrl extends \AppController {
static protected function action_sum() {
$request = new \Request();
$response = new \Response();
$response->result = $request->value1 + $request->value2;
return $response;
}
}
?>
znetdkMobile.ajax
methodsrequest()
znetdkMobile.ajax.request()
<script>
znetdkMobile.ajax.request({
controller: 'mycontroller',
action: 'myaction',
data: {id: 58},
callback: onSuccess
});
function onSuccess(response) {
console.log(response);
);
</script>
loadView()
znetdkMobile.ajax.loadView()
<script>
znetdkMobile.ajax.loadView('myview', $('#my-container'), onSuccess);
function onSuccess() {
console.log('View loaded.');
);
</script>
getParamsFromAjaxURL()
znetdkMobile.ajax.getParamsFromAjaxURL()
<script>
console.log(znetdkMobile.ajax.getParamsFromAjaxURL());
</script>
The content of a ZnetDK web application is the area where the views are displayed.
The first view declared in PHP in the menu.php
script is the first one displayed once the application is loaded in the web browser.
The ZnetDK JS API provides some methods to display any view tied to the navigation menu of the application, to scroll the view to a specific anchor, to force a view to be reloaded and to get the name of the view currently displayed.
znetdkMobile.content
methods
displayView()
,
reloadView()
,
getDisplayedViewId()
,
goToAnchor()
,
displayView()
displayView()
<script>
znetdkMobile.content.displayView('myview', 'my-anchor');
</script>
reloadView()
reloadView()
<script>
znetdkMobile.content.reloadView('myview');
</script>
getDisplayedViewId()
getDisplayedViewId()
<script>
var displayedView = znetdkMobile.content.getDisplayedViewId();
</script>
goToAnchor()
goToAnchor()
<script>
znetdkMobile.content.goToAnchor('my-anchor');
</script>
znetdkMobile.content
eventsbeforeviewdisplay
beforeviewdisplay
event
<script>
$('body').on('beforeviewdisplay', function (event, viewName) {
console.log(viewName);
});
</script>
afterviewdisplay
afterviewdisplay
event
<script>
$('body').on('afterviewdisplay', function (event, viewName) {
console.log(viewName);
});
</script>
The znetdkMobile.header
JS API allows you to customize the App Header display and retrieve information about the logged-in user.
znetdkMobile.header
methodsautoHideOnScroll()
<script>
znetdkMobile.header.autoHideOnScroll(true);
</script>
getConnectedUserLogin()
<script>
const login = znetdkMobile.header.getConnectedUserLogin();
</script>
getConnectedUserName()
<script>
const username = znetdkMobile.header.getConnectedUserName();
</script>
getConnectedUserMail()
<script>
const userEmail = znetdkMobile.header.getConnectedUserMail();
</script>
znetdkMobile.header
eventstopspacechange
topspacechange
event
<script>
$('body').on('topspacechange', function () {
console.log('Top space has changed.');
});
</script>
The app footer is sticked to the bottom of the viewport when the content displayed in the application is less than the viewport height.
Otherwise, if the content is higher than the window height, the application footer displays at the very bottom of the page and the content must be fully scrolled to make the footer visible.
<script>
znetdkMobile.footer.adjustPosition();
</script>
<script>
znetdkMobile.footer.hide();
</script>
<script>
znetdkMobile.footer.show();
</script>
ZnetDK local storage API, based on HTML5 localStorage
API, preserves data stored by each application, even if the several web applications are deployed on the same domain name.
In other words, if two applications are running on the same hosting domain name, values stored by the first application are not overwritten by those stored by the second one.
znetdkMobile.browser
methodsstoreLocalData()
<script>
znetdkMobile.browser.storeLocalData('customColor', 'blue');
</script>
readLocalData()
<script>
var customColor = znetdkMobile.browser.readLocalData('customColor');
console.log(customColor);
</script>
removeLocalData()
<script>
znetdkMobile.browser.removeLocalData('customColor');
</script>
znetdkMobile.serviceWorker
propertiesisRegistered
isRegistered
<script>
console.log(znetdkMobile.serviceWorker.isRegistered);
</script>
znetdkMobile.install
methodsisAppInstallable()
<script>
console.log(znetdkMobile.install.isAppInstallable());
</script>
isAppInstalled()
<script>
console.log(znetdkMobile.install.isAppInstalled());
</script>
showInstallView()
<script>
znetdkMobile.install.showInstallView();
</script>
showUninstallView()
<script>
znetdkMobile.install.showUninstallView();
</script>
showInstallableMessage()
<script>
znetdkMobile.install.showInstallableMessage();
</script>
znetdkMobile.browser
methodsdoPhoneCall()
<script>
znetdkMobile.browser.doPhoneCall('+33701234567');
</script>
sendSMS()
<script>
znetdkMobile.browser.sendSMS('+33701234567', 'Hello John Doe');
</script>
znetdkMobile.file
methodsdisplay()
<script>
const docUrl = '<?php echo General::getURIforDownload('featurectrl', 'filename=document.pdf'); ?>';
znetdkMobile.file.display(docUrl);
</script>