Install the App?
ZnetDK JS API
Client-side Mobile Application JavaScript Methods
SUMMARY
The ZnetDK for Mobile framework is invoked through the JavaScript znetdkMobile object.
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.
Data list
HTML Attributes | JS Properties | JS Methods.
The basics
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.
EXAMPLE: minimal code for displaying a data list in a view
<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.
EXAMPLE: PHP controller action that returns a page of items
<?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).
The HTML attributes
Attribute data-zdk-load
EXAMPLE
<ul id="contactlist" data-zdk-load="myctrl:all"></ul>
Attribute data-zdk-autocomplete
EXAMPLE
<ul id="contactlist" data-zdk-load="myctrl:all" data-zdk-autocomplete="myctrl:suggestions"></ul>
Attribute data-id
EXAMPLE
<ul id="contactlist" data-zdk-load="myctrl:all">
<li data-id="{{id}}">
<a class="edit">{{name}}</a>
</li>
</ul>
The znetdkMobile.list properties
rowsPerPage,
heightDiffForNewPage,
uniqueSearchedKeyword,
beforeInsertRowCallback,
afterInsertRowCallback,
loadedCallback
beforeSearchRequestCallback
Property rowsPerPage
EXAMPLE: property rowsPerPage
<script>
znetdkMobile.list.rowsPerPage = 40;
</script>
Property heightDiffForNewPage
EXAMPLE: property heightDiffForNewPage
<script>
znetdkMobile.list.heightDiffForNewPage = 300;
</script>
Property uniqueSearchedKeyword
EXAMPLE: property uniqueSearchedKeyword
<script>
znetdkMobile.list.uniqueSearchedKeyword = true;
</script>
Property beforeInsertRowCallback
EXAMPLE: property 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>
Property afterInsertRowCallback
EXAMPLE: property afterInsertRowCallback
<script>
var list = znetdkMobile.list.make('#my-list');
list.afterInsertRowCallback = function(newRowEl) {
// Do something, the newRowEl variable contains <li> element in jQuery.
};
</script>
Property loadedCallback
EXAMPLE: property loadedCallback
<script>
var list = znetdkMobile.list.make('#my-list');
list.loadedCallback = function(rowCount, pageNumber) {
console.log('List is loaded', rowCount, pageNumber, this.rowsPerPage);
};
</script>
Property beforeSearchRequestCallback
EXAMPLE: property 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>
The znetdkMobile.list methods
make(), setCustomSortCriteria(), setModal(), refresh()
Method make()
EXAMPLE: method znetdkMobile.list.make()
<script>
var list = znetdkMobile.list.make('#my-list', true, false);
</script>
Method setCustomSortCriteria()
EXAMPLE: method znetdkMobile.list.setCustomSortCriteria()
<script>
var list = znetdkMobile.list.make('#my-list');
list.setCustomSortCriteria({
id: 'Person # (default)',
name: 'Name',
city: 'City',
country: 'Country'
}, 'id');
</script>
Method setModal()
EXAMPLE: method 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>
Method refresh()
EXAMPLE: method znetdkMobile.list.refresh()
<script>
var list = znetdkMobile.list.make('#my-list');
$('#my-button').on('click', function() {
list.refresh();
});
</script>
Modal dialog
The basics
Displays a modal dialog box suitable for mobile devices with only a few lines of code.
EXAMPLE: view that displays a modal dialog box
<!-- 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>
The znetdkMobile.modal methods
make(),
getInnerForm(),
open(),
close(),
setTitle()
Method make()
EXAMPLE: method znetdkMobile.modal.make()
<script>
var modal = znetdkMobile.modal.make('#my-modal', 'myview', function(){
console.log('View loaded.', this);
});
</script>
Method getInnerForm()
EXAMPLE: method znetdkMobile.modal.getInnerForm()
<script>
var modal = znetdkMobile.modal.make('#my-modal');
var form = modal.getInnerForm();
</script>
Method open()
EXAMPLE: method znetdkMobile.modal.open()
<script>
var modal = znetdkMobile.modal.make('#my-modal');
modal.open(submitCallbak, closeCallback, 'my-input');
function submitCallback(response) {
console.log('Submit success!');
}
function closeCallback() {
console.log('Modal closed!');
}
</script>
Method close()
EXAMPLE: method znetdkMobile.modal.close()
<script>
var modal = znetdkMobile.modal.make('#my-modal');
modal.open();
setTimeout(function() { modal.close(); }, 5000);
</script>
Method setTitle()
EXAMPLE: method znetdkMobile.modal.setTitle()
<script>
var modal = znetdkMobile.modal.make('#my-modal');
modal.setTitle('My title');
</script>
The znetdkMobile.modal events
Event beforeshow
EXAMPLE: beforeshow event
<script>
$('my-modal').on('beforeshow', function (event, modalObj) {
console.log(modalObj);
});
</script>
Event aftershow
EXAMPLE: aftershow event
<script>
$('my-modal').on('aftershow', function (event, modalObj) {
console.log(modalObj);
});
</script>
Input form
The basics
Connect an HTML input form to the actions of the remote PHP controller to load and submit its data.
EXAMPLE: Connecting an input form to controller actions
<!-- 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>
EXAMPLE: Input form PHP controller actions
<?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;
}
}
?>
The HTML attributes
Attribute data-zdk-load
EXAMPLE
<form id="myform" data-zdk-load="myctrl:detail"></form>
Attribute data-zdk-submit
EXAMPLE
<form id="myform" data-zdk-submit="myctrl:store"></form>
The znetdkMobile.form methods
make(),
load(),
init(),
reset(),
getInputValue(),
setInputValue(),
setDataModifiedState(),
isModified(),
showError(),
hideError(),
setFocus(),
setReadOnly()
Method make()
EXAMPLE: method znetdkMobile.form.make()
<script>
var myForm = znetdkMobile.form.make('#my-form', onSubmit);
function onSubmit(response) {
console.log('Submit succeeded!', response);
}
</script>
Method load()
EXAMPLE: method znetdkMobile.form.load()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.load(57, onLoadingSuccess);
function onLoadingSuccess(response) {
console.log('Loading succeeded!', response);
}
</script>
Method init()
EXAMPLE: method znetdkMobile.form.init()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.init({
firstname: 'John',
lastname: 'Doe',
age: 34
});
</script>
Method reset()
EXAMPLE: method znetdkMobile.form.reset()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.reset();
</script>
Method getInputValue()
EXAMPLE: method 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>
Method setInputValue()
EXAMPLE: method 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>
Method setDataModifiedState()
EXAMPLE: method znetdkMobile.form.setDataModifiedState()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.setDataModifiedState(false);
</script>
Method isModified()
EXAMPLE: method znetdkMobile.form.isModified()
<script>
var myForm = znetdkMobile.form.make('#my-form');
console.log(myForm.isModified());
</script>
Method showError()
EXAMPLE: method znetdkMobile.form.showError()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.showError('Value is invalid!', 'my_input');
</script>
Method hideError()
EXAMPLE: method znetdkMobile.form.hideError()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.hideError();
</script>
Method setFocus()
EXAMPLE: method znetdkMobile.form.setFocus()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.setFocus('firstname');
</script>
Method setReadOnly()
EXAMPLE: method znetdkMobile.form.setReadOnly()
<script>
var myForm = znetdkMobile.form.make('#my-form');
myForm.setReadOnly();
</script>
Action buttons
The basics
Standard action buttons can be displayed at fixed position on a view. These are Refresh, Add, Search and Back to top buttons.
- Refresh button, when calling the
znetdkMobile.list.make()method withrefreshparameter set totrue. - Search button, when calling the
znetdkMobile.list.make()method withsearchparameter set totrue. - Add button, when calling the
znetdkMobile.list.setModal()method withonAddparameter set to a valid function.
Additional custom action buttons can also be declared and displayed if required.
The znetdkMobile.action methods
Method registerView()
EXAMPLE: Display of "Back to top" button
<script>
// "Back to top" button displayed for the 'myviewid' view.
znetdkMobile.action.registerView('myviewid', {
scrollup: {
isVisible: true,
callback: function () {
alert('Button clicked!');
}
}
});
</script>
Method addCustomButton()
EXAMPLE: Definition of a custom action button
<script>
znetdkMobile.action.addCustomButton('mybutton', 'fa-print', 'w3-yellow');
</script>
Method toggle()
EXAMPLE: Display of the action buttons
<script>
znetdkMobile.action.toggle();
</script>
Autocomplete
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.
EXAMPLE: 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.
EXAMPLE: PHP controller action that provides suggestions
<?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 ($query === 'abc') {
$suggestions[] = array('label' => 'abc');
$suggestions[] = array('label' => 'abcd');
$suggestions[] = array('label' => 'abcde');
}
$response->setResponse($suggestions); // Suggestions matching the entered text
return $response;
}
}
?>
The znetdkMobile.autocomplete properties
minStringLength,
delay,
maxNumberOfCachedItems,
cacheLifetime
Property minStringLength
EXAMPLE: property minStringLength
<script>
znetdkMobile.autocomplete.minStringLength = 3;
</script>
Property delay
EXAMPLE: property delay
<script>
znetdkMobile.autocomplete.delay = 1000;
</script>
Property maxNumberOfCachedItems
EXAMPLE: property maxNumberOfCachedItems
<script>
const myList = znetdkMobile.autocomplete.make('#my-autocomplete', {
controller: 'myctrl',
action: 'suggestions'
});
myList.maxNumberOfCachedItems = 20;
</script>
Property cacheLifetime
EXAMPLE: property cacheLifetime
<script>
const myList = znetdkMobile.autocomplete.make('#my-autocomplete', {
controller: 'myctrl',
action: 'suggestions'
});
myList.maxNumberOfCachedItems = 20;
myList.cacheLifetime = 'selection';
</script>
The znetdkMobile.autocomplete methods
Method make()
EXAMPLE: method 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>
Messages
Displays a message to the user by calling a simple method in JavaScript.
EXAMPLE: information, warning, error messages
<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>
EXAMPLE: transient snackbar message
<script>
znetdkMobile.messages.showSnackbar('Message when success...');
</script>
EXAMPLE: notification message
<script>
znetdkMobile.messages.notify('Notification to the user', 'Notification message...', null, function() {
alert('Click on OK button');
});
</script>
EXAMPLE: confirmation message
<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>
AJAX requests
The basics
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.
EXAMPLE: AJAX request sent to get the sum of two values
<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.
EXAMPLE: PHP controller action that calculates the sum of two values
<?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;
}
}
?>
The znetdkMobile.ajax methods
Method request()
EXAMPLE: method znetdkMobile.ajax.request()
<script>
znetdkMobile.ajax.request({
controller: 'mycontroller',
action: 'myaction',
data: {id: 58},
callback: onSuccess
});
function onSuccess(response) {
console.log(response);
);
</script>
Method loadView()
EXAMPLE: method znetdkMobile.ajax.loadView()
<script>
znetdkMobile.ajax.loadView('myview', $('#my-container'), onSuccess);
function onSuccess() {
console.log('View loaded.');
);
</script>
Method getParamsFromAjaxURL()
EXAMPLE: method znetdkMobile.ajax.getParamsFromAjaxURL()
<script>
console.log(znetdkMobile.ajax.getParamsFromAjaxURL());
</script>
App Views
The basics
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.
The znetdkMobile.content methods
displayView(),
reloadView(),
getDisplayedViewId(),
goToAnchor(),
Method displayView()
EXAMPLE: Method displayView()
<script>
znetdkMobile.content.displayView('myview', 'my-anchor');
</script>
Method reloadView()
EXAMPLE: Method reloadView()
<script>
znetdkMobile.content.reloadView('myview');
</script>
Method getDisplayedViewId()
EXAMPLE: Method getDisplayedViewId()
<script>
var displayedView = znetdkMobile.content.getDisplayedViewId();
</script>
Method goToAnchor()
EXAMPLE: Method goToAnchor()
<script>
znetdkMobile.content.goToAnchor('my-anchor');
</script>
The znetdkMobile.content events
Event beforeviewdisplay
EXAMPLE: beforeviewdisplay event
<script>
$('body').on('beforeviewdisplay', function (event, viewName) {
console.log(viewName);
});
</script>
Event afterviewdisplay
EXAMPLE: afterviewdisplay event
<script>
$('body').on('afterviewdisplay', function (event, viewName) {
console.log(viewName);
});
</script>
App Header
The znetdkMobile.header JS API allows you to customize the App Header display and retrieve information about the logged-in user.
The znetdkMobile.header methods
Method autoHideOnScroll()
EXAMPLE: Hiding header
<script>
znetdkMobile.header.autoHideOnScroll(true);
</script>
Method getConnectedUserLogin()
EXAMPLE: Getting login name
<script>
const login = znetdkMobile.header.getConnectedUserLogin();
</script>
Method getConnectedUserName()
EXAMPLE: Getting user name
<script>
const username = znetdkMobile.header.getConnectedUserName();
</script>
Method getConnectedUserMail()
EXAMPLE: Getting user email
<script>
const userEmail = znetdkMobile.header.getConnectedUserMail();
</script>
The znetdkMobile.header events
Event topspacechange
EXAMPLE: topspacechange event
<script>
$('body').on('topspacechange', function () {
console.log('Top space has changed.');
});
</script>
App Footer
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.
EXAMPLE: adjusting the position of the App footer
<script>
znetdkMobile.footer.adjustPosition();
</script>
EXAMPLE: Hiding the App footer
<script>
znetdkMobile.footer.hide();
</script>
EXAMPLE: Showing the App footer
<script>
znetdkMobile.footer.show();
</script>
Local Storage
The basics
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.
The znetdkMobile.browser methods
Method storeLocalData()
EXAMPLE: Storing data
<script>
znetdkMobile.browser.storeLocalData('customColor', 'blue');
</script>
Method readLocalData()
EXAMPLE: Reading data
<script>
var customColor = znetdkMobile.browser.readLocalData('customColor');
console.log(customColor);
</script>
Method removeLocalData()
EXAMPLE: Clearing data
<script>
znetdkMobile.browser.removeLocalData('customColor');
</script>
PWA - Progressive Web App
ZnetDK 4 Mobile JS API includes useful properties and methods to get the service worker registration status and to know if the App can be installed through the used web browser and finally to know if App is installed or not.The znetdkMobile.serviceWorker properties
Property isRegistered
EXAMPLE: property isRegistered
<script>
console.log(znetdkMobile.serviceWorker.isRegistered);
</script>
The znetdkMobile.install methods
Method isAppInstallable()
EXAMPLE: Checking if App is installable
<script>
console.log(znetdkMobile.install.isAppInstallable());
</script>
Method isAppInstalled()
EXAMPLE: Checking if App is installed
<script>
console.log(znetdkMobile.install.isAppInstalled());
</script>
Method showInstallView()
EXAMPLE: Displaying installation view
<script>
znetdkMobile.install.showInstallView();
</script>
Method showUninstallView()
EXAMPLE: Displaying uninstallation view
<script>
znetdkMobile.install.showUninstallView();
</script>
Method showInstallableMessage()
EXAMPLE: Displaying prompt for installing App
<script>
znetdkMobile.install.showInstallableMessage();
</script>
Miscellaneous Tools
The znetdkMobile.browser methods
Method doPhoneCall()
EXAMPLE: Doing a phone call
<script>
znetdkMobile.browser.doPhoneCall('+33701234567');
</script>
Method sendSMS()
EXAMPLE: Sending a SMS
<script>
znetdkMobile.browser.sendSMS('+33701234567', 'Hello John Doe');
</script>
The znetdkMobile.file methods
Method display()
EXAMPLE: Downloading a PDF document
<script>
const docUrl = '<?php echo General::getURIforDownload('featurectrl', 'filename=document.pdf'); ?>';
znetdkMobile.file.display(docUrl);
</script>