ZnetDK 4 Mobile

ZnetDK JS API

Client-side Mobile Application JavaScript Methods

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.

Add into a ZnetDK view a HTML <ul> element with the id attribute filled in and the data-zdk-load attribute that specifies the remote controller action called to load the data.
The first list item declared (HTML <li> element) is the row template used to display all the items of the data list. Each value to be displayed is surrounded by double braces (i.e. {{myValue}}).
Optionally, the second list item declared is the custom message displayed when no list item exists.
Finally, call the znetdkMobile.list.make() method to initialize and load the data list.

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

DESCRIPTION Remote PHP controller and action to call in AJAX to load the elements in the list.
  • This attribute applies to the HTML list element ( <ul> ),
  • The controller and action names are separated by a colon ( : ),
  • The specified controller is the PHP class name of the dedicated Application controller,
  • The specified action is the name of PHP class method without the action_ prefix (ie if the PHP method of the controller's action is named action_all(), the specified action name is only all).
See the The view - Displaying contacts from AJAX request section of the Tutorial for a complete sample code.

EXAMPLE

<ul id="contactlist" data-zdk-load="myctrl:all"></ul>

 Attribute data-zdk-autocomplete

DESCRIPTION Remote PHP controller and action to call in AJAX to get the suggestions displayed when a keyword is entered from the search dialog (see the search parameter of the znetdkMobile.list.make() JS method).
  • This attribute applies to the HTML list element ( <ul> ),
  • The controller and action names are separated by a colon ( : ),
  • The specified controller is the PHP class name of the dedicated Application controller,
  • The specified action is the name of PHP class method without the action_ prefix (ie if the PHP method of the controller's action is named action_suggestions(), the specified action name is only suggestions).
See the The view - Adding search button and keyword input section of the Tutorial for a complete sample code.

EXAMPLE

<ul id="contactlist" data-zdk-load="myctrl:all" data-zdk-autocomplete="myctrl:suggestions"></ul>

 Attribute data-id

DESCRIPTION Name of the property in the JSON data returned by the action of the remote PHP controller (see data-zdk-load attribute), which uniquely identifies each row in the list.
  • This property name is used by the ZnetDK Data List to know the identifier that matches the row's data to load and to display in the modal dialog for editing purpose (see setModal() JS method),
  • This attribute applies to the HTML list item element declared as row template ( <li> ),
  • The name of the property, generally id, must be rounded by double braces (ie {{id}}).
ZnetDK for Mobile Data List, data-id HTML attribute

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, beforeSearchRequestCallback

 Property rowsPerPage

DESCRIPTION The number of items to request in AJAX from the remote PHP controller action and add to the list when it is displayed for the first time and then when it is scrolled down.
This property can be changed in particular when the height of the first 20 items displayed in the list is lower than the viewport height.
DATATYPE Integer
DEFAULT VALUE 20

EXAMPLE: property rowsPerPage

<script>
    znetdkMobile.list.rowsPerPage = 40;
</script>

 Property heightDiffForNewPage

DESCRIPTION The list height in pixels to scroll down to trigger AJAX loading of a new elements page.
This height can be reduced or increased according to the height of each row displayed in the list.
DATATYPE Integer
DEFAULT VALUE 200

EXAMPLE: property heightDiffForNewPage

<script>
    znetdkMobile.list.heightDiffForNewPage = 300;
</script>

 Property uniqueSearchedKeyword

DESCRIPTION Limit the search in the list to only one keyword when the property is set to true.
By default, multiple keywords can be entered and cumulated to search items in the list.
DATATYPE Boolean
DEFAULT VALUE false

EXAMPLE: property uniqueSearchedKeyword

<script>
    znetdkMobile.list.uniqueSearchedKeyword = true;
</script>

 Property beforeInsertRowCallback

DESCRIPTION Custom function called each time a row is inserted in a list.
This function has one parameter which contains the data to display for the row. This data can be modified within the function before displaying the row.
This callback function can be useful to format data before row insertion.
DATATYPE function
DEFAULT VALUE null
VERSION >= 2.7

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 beforeSearchRequestCallback

DESCRIPTION Set a callback function executed just before requesting to the web server, the items to load in the list.
This callback function is particularly useful to change the POST paramaters sent in AJAX to the action of the remote PHP controller.
The requestData parameter passed to the callback function is a simple JavaScript object whose properties and values are the POST parameter names and their associated value as described below:
  • first: property containing the first item number to display in the list (value 0 when called for the first time)
  • count: property that indicates the number of items requested (by default, 20 per page).
  • keyword: property containing the keyword entered by the user in the Searched keyword field.
    This property is an array having multiple keyword values when the list uniqueSearchedKeyword property is set to true.
  • sortfield property specifying the sorting key matching the sort field selected by the user from the Sort result by dropdown.
  • sortorder property indicating the Sort order value (1 for ascending order, -1 for descending order) choosen by the user.
DATATYPE function
DEFAULT VALUE null

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()

DESCRIPTION Instantiate the list object for the specified <ul> HTML element.
PARAMETERS
listElementId String Identifier (id HTML attribute value) of the <ul> HTML element prefixed by a hash symbol (#).
refresh Boolean If set to true or undefined, the refresh action button is displayed for refreshing the list content on demand.
search Boolean If set to true or undefined, the search action button is displayed for filtering/sorting the list content.
RETURNED VALUE Object The instantiated object for the specified list element. This object can then be used to call the setCustomSortCriteria() and setModal() methods.

EXAMPLE: method znetdkMobile.list.make()

<script>
    var list = znetdkMobile.list.make('#my-list', true, false);
</script>

 Method setCustomSortCriteria()

DESCRIPTION Specify the sort criteria that the user can apply to the list when clicking on the search button.
PARAMETERS
sortCriteria Object A JavaScript object whose properties are the sorting keys and values are the sort labels.
defaultSortCriterium String The sorting key to apply by default.
RETURNED VALUE Boolean Value true when succeeded, false if the method is not called into the context of a list object or if its parameter are not properly set.

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()

DESCRIPTION
Declare the modal dialog to display for editing an existing item or for adding a new one.
The first <li> HTML list item declared as row template must be declared with the data-id attribute and must embed an anchor element with the edit class so that the edit modal dialog is automatically displayed when the list item is clicked.
For example: <a class="edit">{{customer_name}} (see detail...)</a>

See the The view - Adding an input form for creating and editing contacts section of the Tutorial for a complete sample code.
PARAMETERS
modalElementId String The identifier of the modal dialog (id HTML attribute).
isFormModifiable Boolean When set to true or undefined, the item can be modified through the modal dialog and the add action bar button is displayed.
onAdd function The function to call back for initialization purpose when adding a new row, just before the modal dialog display.
- The this value allows to access to the modal dialog object.
- The innerForm parameter passed to the callback function is the inner form object.
onEdit function The function to call back for initialization purpose when editing an existing row, just before the modal dialog display.
- The this value allows to access to the modal dialog object.
- The innerForm parameter passed to the callback function is the inner form object.
- The response parameter passed to the callback function is the response object returned by the remote PHP controller action.
RETURNED VALUE Boolean Value true when succeeded, false if the method is not called into the context of a list object.

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()

DESCRIPTION Refresh the list from the data returned by the remote controller action set for the list through the data-zdk-load HTML5 attribute.
PARAMETERS

no parameter

RETURNED VALUE Boolean Value true when succeeded, false otherwise.

EXAMPLE: method znetdkMobile.list.refresh()

<script>
    var list = znetdkMobile.list.make('#my-list');
    $('#my-button').on('click', function() {
        list.refresh();
    });
</script>

Modal dialog

JS Methods | JS Events.

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(),

 Method make()

DESCRIPTION Instantiate the modal dialog object for the specified <div> HTML element.
PARAMETERS
modalElementSelector String | jQuery The string selector of the modal (i.e #my-modal) or a jQuery element of the modal.
viewName VERSION >= 2.7 String | undefined OPTIONAL, the name of the view containing the modal dialog. If the modal dialog does not exist in the DOM, the given view name is loaded to add the modal dialog in the DOM.
onViewLoaded VERSION >= 2.7 function | undefined OPTIONAL, when the viewName parameter is specified, this function is called back once the view is loaded if the modal does not yet exist in the DOM. If the modal already exists, the function is directly called. The this object of this callback function is the modal object.
RETURNED VALUE Object The instantiated modal dialog for the specified <div> element. This object can then be used to call the open() and close() methods.

EXAMPLE: method znetdkMobile.modal.make()

<script>
    var modal = znetdkMobile.modal.make('#my-modal', 'myview', function(){
        console.log('View loaded.', this);
    });
</script>

 Method getInnerForm()

DESCRIPTION Returns the form of the modal. If more than one form exist, only the first one is returned.
PARAMETERS
asJqueryElement Boolean | undefined OPTIONAL, if true, the form is return as a jQuery element. Otherwise, the form is returned as a znetdkMobile object.
selectorClass String | undefined OPTIONAL, CSS class of the form if multiple forms exist within the modal (for example my-form).
RETURNED VALUE znetdkMobile.form | jQuery | Boolean The form of the modal by default as a znetdkMobile object or as a jQuery object.
Returns false if no form exists or if more than one form exist.

EXAMPLE: method znetdkMobile.modal.getInnerForm()

<script>
    var modal = znetdkMobile.modal.make('#my-modal');
    var form = modal.getInnerForm();
</script>

 Method open()

DESCRIPTION Display the modal dialog.
PARAMETERS
onSubmit function | undefined OPTIONAL, function to call back when clicking on the inner form submit button if exists.
The JSON response returned by the remote controller's action after submit success is passed to this callback function as parameter.
If this callback function returns false, the modal dialog is not closed once submit succeeded.
onClose function | undefined OPTIONAL, function to callback when closing the modal dialog.
If this callback function returns false, the modal dialog is not automatically closed.
focusedInputName String | undefined OPTIONAL, name of the inner form input element for which the keyboard focus is set.
RETURNED VALUE Boolean Value true when it is opened successfully, false otherwise.

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()

DESCRIPTION Close the modal dialog.
PARAMETERS
checkDataFormsModified Boolean | undefined OPTIONAL, when set to true, check if the inner input form data are modified before closing. If so, a confirmation message is displayed before.
RETURNED VALUE Boolean Value true if modal is closed, false otherwise.

EXAMPLE: method znetdkMobile.modal.close()

<script>
    var modal = znetdkMobile.modal.make('#my-modal');
    modal.open();
    setTimeout(function() { modal.close(); }, 5000);
</script>

The znetdkMobile.modal events

 Event beforeshow

DESCRIPTION Event sent before displaying a modal dialog.
If the event handler return false, the modal dialog is not displayed.
PARAMETERS
modalObject znetdkMobile.modal JS object of the modal dialog.
VERSION >= 2.7

EXAMPLE: beforeshow event

<script>
    $('my-modal').on('beforeshow', function (event, modalObj) {
        console.log(modalObj);
    });
</script>

 Event aftershow

DESCRIPTION Event sent after displaying a modal dialog.
PARAMETERS
modalObject znetdkMobile.modal JS object of the modal dialog.
VERSION >= 2.7

EXAMPLE: aftershow event

<script>
    $('my-modal').on('aftershow', function (event, modalObj) {
        console.log(modalObj);
    });
</script>

Input form

JS Methods

The basics

Connect an HTML input form to the actions of the remote PHP controller to load and submit its data.

The form element is declared with the data-zdk-load HTML5 attribute that specifies the controller action to request in AJAX (i.e. Myctrl::action_detail()) to get the data to load in the input form.
The data-zdk-submit attribute specifies the PHP controller action to execute (i.e. Myctrl::action_submit()) when the submit button is pressed.
The znetdkMobile.form.load() method executed once the view is loaded, sends the AJAX request to the Myctrl::action_detail() PHP controller action.

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>

Below the source code of the MyCtrl PHP controller.
The action_detail() method, executed by the JavaScript znetdkMobile.form.load(), returns the values to display in the input form.
The action_submit() method, triggered on form submit, reads the input form values and shows them throught the information message returned.

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 znetdkMobile.form methods

make(), load(), init(), reset(), getInputValue(), setInputValue(), setDataModifiedState(), isModified(), showError(), hideError(), setFocus(), setReadOnly()

 Method make()

DESCRIPTION Instantiate a new form object from the specified HTML form element.
PARAMETERS
formElementSelector String | jQuery Form element as a jQuery element or as a string to identify the HTML form.
submitCallback function | undefined OPTIONAL, function to call back when the submit button is pressed.
If the form element is declared with the data-zdk-submit property (for example data-zdk-submit="mycontroller:myaction"), then the JSON response returned by the specified controller action is passed to this callback function as parameter.
When the callback function returns false, no message is displayed by ZnetDK.
RETURNED VALUE Object | null The form as ZnetDK object on success, null otherwise.

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()

DESCRIPTION Load the form data from the identifier specified as parameter and the controller action specified through the data-zdk-load HTML5 attribute.
PARAMETERS
id String | Integer Identifier of the data to load in the form.
This identifier is sent through the POST parameter named id, to the controller action in charge of supplying the data to load in the input form (see data-zdk-load HTML5 attribute).
callback function | undefined OPTIONAL, callback function to execute once the data are loaded in the input form.
The data returned by the controller action (see data-zdk-load HTML5 attribute) are passed to this callback function as parameter.
RETURNED VALUE Boolean Value true if the data-zdk-load HTML5 attribute is defined for the form element, false otherwise.

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()

DESCRIPTION Initialize the data form from the specified value object.
PARAMETERS
valueObject Object Javascript object having properties named as every input field (HTML attribute name) in the data form.
isFormResetBefore Boolean | undefined OPTIONAL, when set to true or undefined, the form values are cleared before initialization.
RETURNED VALUE Boolean Value true if initialization succeeded, false otherwise.

EXAMPLE: method znetdkMobile.form.init()

<script>
    var myForm = znetdkMobile.form.make('#my-form');
    myForm.init({
        firstname: 'John',
        lastname: 'Doe',
        age: 34
    });
</script>

 Method reset()

DESCRIPTION Reset the input form by clearing the input fields and hidding the displayed error message. Hidden input fields are also reset.
RETURNED VALUE Boolean Value true when the input form is reset, false otherwise.

EXAMPLE: method znetdkMobile.form.reset()

<script>
    var myForm = znetdkMobile.form.make('#my-form');
    myForm.reset();
</script>

 Method getInputValue()

DESCRIPTION Get the value of the specified input field (HTML element of type input, textarea or select).
PARAMETERS
inputName String Name of the input field (HTML attribute name).
RETURNED VALUE String | Array | Boolean The value of the input field as a string.
An array is returned in case of a select element with the multiple property.
Returns false if no input field exists for the specified input name and if the HTML element is not of type select, textarea or input.

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()

DESCRIPTION Set the value of the specified input field (HTML element of type input, textarea or select).
PARAMETERS
inputName String Name of the input field (HTML attribute name).
inputValue String | Array String value to set to the input field.
Or an array of values if the HTML element is an input of type checkbox or a select with the multiple property set.
silent Boolean | undefined OPTIONAL, when different than true, an error is displayed into the browser console if the specified input field does not exist.
RETURNED VALUE Boolean Value true when succeeded.
Returns false if no input field exists for the specified input name, if the specified value does not match any radio button input and if the specified value is not an array while the input name is a select element with multiple property.

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()

DESCRIPTION Set the modified data state of an input form.
PARAMETERS
isModified Boolean If true, the form data are set modified. Otherwise if set to false, the form data are set not modified.
RETURNED VALUE Boolean Value true on success, false if the parameter is not a boolean value.

EXAMPLE: method znetdkMobile.form.setDataModifiedState()

<script>
    var myForm = znetdkMobile.form.make('#my-form');
    myForm.setDataModifiedState(false);
</script>

 Method isModified()

DESCRIPTION Indicates whether the input form data have been modified or not.
RETURNED VALUE Boolean Value true if the form data have been modified by the user, false otherwise.

EXAMPLE: method znetdkMobile.form.isModified()

<script>
    var myForm = znetdkMobile.form.make('#my-form');
    console.log(myForm.isModified());
</script>

 Method showError()

DESCRIPTION Display an error message on the top of the input form.
PARAMETERS
message String The error message.
inputName String | undefined OPTIONAL, The name of the HTML input (attribute name) on which the focus is set.
RETURNED VALUE Boolean Value true if message is shown successfully, false otherwise.

EXAMPLE: method znetdkMobile.form.showError()

<script>
    var myForm = znetdkMobile.form.make('#my-form');
    myForm.showError('Value is invalid!', 'my_input');
</script>

 Method hideError()

DESCRIPTION Hide the error message currently displayed into the input form.
RETURNED VALUE Boolean Value true if message is hidden successfully, false otherwise.

EXAMPLE: method znetdkMobile.form.hideError()

<script>
    var myForm = znetdkMobile.form.make('#my-form');
    myForm.hideError();
</script>

 Method setFocus()

DESCRIPTION Set the focus on the specified input field.
PARAMETERS
inputName String Name of the input field (HTML attribute name).
RETURNED VALUE Boolean Value true on success, false otherwise.

EXAMPLE: method znetdkMobile.form.setFocus()

<script>
    var myForm = znetdkMobile.form.make('#my-form');
    myForm.setFocus('firstname');
</script>

 Method setReadOnly()

DESCRIPTION Set form inputs to read-only state to avoid user modifications.
PARAMETERS
isReadOnly Boolean | undefined OPTIONAL, when set to true or undefined, the form values can't be changed. Otherwise if set to false, the form values can be changed.
RETURNED VALUE Boolean Value true on success, false otherwise.

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.

The following buttons are automatically displayed if a Data List is declared in the displayed view:

Additional custom action buttons can also be declared and displayed if required.

The znetdkMobile.action methods

 Method registerView()

DESCRIPTION Specify the action buttons to display each time the specified view is displayed and the function to call back when the action button is pressed.
PARAMETERS
viewId String ID of the view.
options Object For each button set as property add, refresh, search and scrollup, the sub-properties isVisible (Boolean) and callback (function).
RETURNED VALUE Boolean Value true if the options are set properly and the view exists, false otherwise.

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()

DESCRIPTION Declare a custom action button.
After its declaration, the custom button can be displayed for a specific view calling the znetdkMobile.action.registerView() method.
PARAMETERS
name String Name given to the custom button.
iconCssClass String Class name of the FontAwesome icon displayed on the button.
colorCssClass String Class name of the W3.CSS color used to display the button.
RETURNED VALUE Boolean Value true on success, false otherwise.

EXAMPLE: Definition of a custom action button

<script>
    znetdkMobile.action.addCustomButton('mybutton', 'fa-print', 'w3-yellow');
</script>

Autocomplete

JS Properties | JS Methods

The ZnetDK autocomplete component displays suggestions provided by a remote PHP controller action while the user enters text.

First, add into a ZnetDK view a HTML <input> element with the id attribute filled in and the type attribute set to search.
Next, call the znetdkMobile.autocomplete.make() method to initialize the autocompletion component.

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.

EXAMPLE: PHP controller action that provides suggestions

<?php
namespace app\controller;
class 
MyCtrl extends \AppController {
    static protected function 
action_suggestions() {
        
$request = new \Request();
        
$response = new \Response();
        
$suggestions = array();
        
$suggestions[] = array('label' => $request->query 'a');
        
$suggestions[] = array('label' => $request->query 'ab');
        
$suggestions[] = array('label' => $request->query 'abc');
        
$response->setResponse($suggestions);
        return 
$response;
    }
}
?>

The znetdkMobile.autocomplete properties

minStringLength, delay, maxNumberOfCachedItems, cacheLifetime

 Property minStringLength

DESCRIPTION Number of characters entered by the user before triggering the first AJAX request to the action of the remote PHP controller in charge of returning the suggestions.
DATATYPE Integer
DEFAULT VALUE 1

EXAMPLE: property minStringLength

<script>
    znetdkMobile.autocomplete.minStringLength = 3;
</script>

 Property delay

DESCRIPTION Time elapsed in milliseconds after the user typed a character, before triggering an AJAX request to the remote PHP controller action responsible for returning suggestions.
DATATYPE Integer
DEFAULT VALUE 300

EXAMPLE: property delay

<script>
    znetdkMobile.autocomplete.delay = 1000;
</script>

 Property maxNumberOfCachedItems

DESCRIPTION Number of different keywords for which suggestions are kept in cache memory. Set a value greater than zero to enable caching.
DATATYPE Integer
DEFAULT VALUE 0
VERSION >= 2.7

EXAMPLE: property maxNumberOfCachedItems

<script>
    const myList = znetdkMobile.autocomplete.make('#my-autocomplete', {
        controller: 'myctrl',
        action: 'suggestions'
    });
    myList.maxNumberOfCachedItems = 20;
</script>

 Property cacheLifetime

DESCRIPTION Life time of the memorized suggestions in cache. Expected values are:
  • 'page': cache memory is reset when the page is closed in the web browser.
  • 'selection': cache memory is reset after selecting a suggestion.
DATATYPE String
DEFAULT VALUE 'page'
VERSION >= 2.7

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()

DESCRIPTION Instantiate a new autocomplete object from the specified HTML input field element.
PARAMETERS
inputSelector String The selector of the input field as a jQuery text selector.
controllerAction Object The controller and the action to call remotely to retrieve the autocompletion suggestions.
onSelect function | undefined OPTIONAL, function to call back when a suggestion has been choosen by the user.
renderCallback function | undefined OPTIONAL, function called to customize the display of each suggestion. This function is called with the suggestion's data as parameter and must return the new label in text or HTML format.
RETURNED VALUE Object | null The instantiated autocomplete object or null if the instantiation failed.

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.

Call the znetdkMobile.messages.add() method to display a message for information, for warning or when an error occured.

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>

Call the znetdkMobile.messages.showSnackbar() method to display a transient snackbar message.

EXAMPLE: transient snackbar message

<script>
    znetdkMobile.messages.showSnackbar('Message when success...');
</script>

Call the znetdkMobile.messages.notify() method to display a notification message in a modal dialog box.

EXAMPLE: notification message

<script>
    znetdkMobile.messages.notify('Notification to the user', 'Notification message...', null, function() {
        alert('Click on OK button');
    });
</script>

Call the znetdkMobile.messages.ask() method to display a confirmation message in a modal dialog box.

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.

Call the znetdkMobile.ajax.request() method with a simple JavaScript object as the parameter to specify the AJAX request options.

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()

DESCRIPTION Send an AJAX request to a ZnetDK PHP application controller.
PARAMETERS
options Object The request parameters as Object with the properties below:
  • controller: the application controller name (mandatory)
  • action: the application controller action name (mandatory)
  • data: the data as JS Object to send to the controller action (optional)
  • callback: the function to callback when request succeeded
  • htmlTarget: the HTML element as jQuery object in which the request response is to append to.
  • errorCallback: the function to call back when request failed.
RETURNED VALUE jqXHR | Boolean The jQuery object returned by the jQuery $.ajax method or false if the control and action properties are not set properly.

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()

DESCRIPTION Load a remote view and add it to the DOM of the HTML page.
PARAMETERS
viewName String Name of the view to load without the .php file extension.
targetHtmlElement jQuery The HTML element as jQuery object that will contain the view once loaded.
callback function | undefined OPTIONAL, function to call back once the view had been added at the end of the target HTML container.
RETURNED VALUE jqXHR | Boolean The jQuery object returned by the jQuery $.ajax method or false if the view name is not specified and if the target HTML element is not a jQuery element.

EXAMPLE: method znetdkMobile.ajax.loadView()

<script>
    znetdkMobile.ajax.loadView('myview', $('#my-container'), onSuccess);
    function onSuccess() {
        console.log('View loaded.');
    );
</script>

 Method getParamsFromAjaxURL()

DESCRIPTION Returns the Ajax URL and its parameter as an Object.
RETURNED VALUE Object The AJAX URL as properties:
  • url: the URL without parameters.
  • paramName: the parameter name.
  • paramValue: the parameter value.

EXAMPLE: method znetdkMobile.ajax.getParamsFromAjaxURL()

<script>
    console.log(znetdkMobile.ajax.getParamsFromAjaxURL());
</script>

App Views

JS Methods | JS Events.

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()

DESCRIPTION Display the specified view tied to the navigation menu and in option, scroll its content to the position of the specified anchor.
If an HTML element exists with the zdk-viewreload CSS class inside the view, then the view is firstly removed from the application and reloaded before being displayed.
PARAMETERS
viewName String Name of the view to display, ie the name of the corresponding PHP script without the .php file extension.
The PHP scripts of the views are located into the INSTALL_DIR/applications/default/app/view/ folder.
anchor String OPTIONAL, HTML identifier of the anchor to be made visible by scrolling the content of the view.

EXAMPLE: Method displayView()

<script>
    znetdkMobile.content.displayView('myview', 'my-anchor');
</script>

 Method reloadView()

DESCRIPTION Reload and display the specified view and in option, scroll its content to the position of the specified anchor.
Reloading the view means that the view is firstly removed from the application and reloaded before being displayed.
This method is equivalent to the displayView() method when an HTML element exists with the zdk-viewreload CSS class inside the view.
PARAMETERS
viewName String Name of the view to reload, ie the name of the corresponding PHP script without the .php file extension.
The PHP scripts of the views are located into the INSTALL_DIR/applications/default/app/view/ folder.
anchor String OPTIONAL, HTML identifier of the anchor to be made visible by scrolling the content of the view.

EXAMPLE: Method reloadView()

<script>
    znetdkMobile.content.reloadView('myview');
</script>

 Method getDisplayedViewId()

DESCRIPTION Return the name of the view currently displayed.
RETURNED VALUE String The name of the view currently displayed.

EXAMPLE: Method getDisplayedViewId()

<script>
    var displayedView = znetdkMobile.content.getDisplayedViewId();
</script>

 Method goToAnchor()

DESCRIPTION Scroll the page to show the specified anchor. If the anchor is not specified, the anchor is read from the URL if it is set.
PARAMETERS
anchor String HTML ID of the anchor.
RETURNED VALUE String Value true when anchor exists and is displayed.

EXAMPLE: Method goToAnchor()

<script>
    znetdkMobile.content.goToAnchor('my-anchor');
</script>

The znetdkMobile.content events

 Event beforeviewdisplay

DESCRIPTION Event sent before displaying a view.
PARAMETERS
viewName String Name of the view that will be displayed.

EXAMPLE: beforeviewdisplay event

<script>
    $('body').on('beforeviewdisplay', function (event, viewName) {
        console.log(viewName);
    });
</script>

 Event afterviewdisplay

DESCRIPTION Event sent after displaying a view.
PARAMETERS
viewName String Name of the view just displayed.

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()

DESCRIPTION Hides automatically the page header when the page is scrolled down.
PARAMETERS
isEnabled String Identifier of the value stored locally.

EXAMPLE: Hiding header

<script>
    znetdkMobile.header.autoHideOnScroll(true);
</script>

 Method getConnectedUserLogin()

DESCRIPTION Get the login name of the connected user.
RETURNED VALUE Boolean The login name.

EXAMPLE: Getting login name

<script>
    const login = znetdkMobile.header.getConnectedUserLogin();
</script>

 Method getConnectedUserName()

DESCRIPTION Get the user name of the connected user.
RETURNED VALUE Boolean The user name.

EXAMPLE: Getting user name

<script>
    const username = znetdkMobile.header.getConnectedUserName();
</script>

 Method getConnectedUserMail()

DESCRIPTION Get the user email of the connected user.
RETURNED VALUE Boolean The user email.

EXAMPLE: Getting user email

<script>
    const userEmail = znetdkMobile.header.getConnectedUserMail();
</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.

Call the znetdkMobile.footer.adjustPosition() method to adjust the position of the App footer when the height of the application's content has changed.

EXAMPLE: adjusting the position of the App footer

<script>
    znetdkMobile.footer.adjustPosition();
</script>

Call the znetdkMobile.footer.hide() method to hide the footer.

EXAMPLE: Hiding the App footer

<script>
    znetdkMobile.footer.hide();
</script>

Call the znetdkMobile.footer.show() method to show the footer.

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()

DESCRIPTION Store in the web browser local storage the specified value.
PARAMETERS
storageKey String Identifier of the value stored locally.
value String The value to store.
RETURNED VALUE Boolean true if the storage succeeded, false otherwise.

EXAMPLE: Storing data

<script>
    znetdkMobile.browser.storeLocalData('customColor', 'blue');
</script>

 Method readLocalData()

DESCRIPTION Retrieve the value stored in the web browser local storage for the specified key.
PARAMETERS
storageKey String Identifier of the value stored locally.
RETURNED VALUE String | Boolean The value found or false if the value does not exist.

EXAMPLE: Reading data

<script>
    var customColor = znetdkMobile.browser.readLocalData('customColor');
    console.log(customColor);
</script>

 Method removeLocalData()

DESCRIPTION Remove the data matching the specified key from the web browser local storage.
PARAMETERS
storageKey String Identifier of the value stored locally.

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

DESCRIPTION Indicate if the service worker registration has succeeded.
DATATYPE Boolean
VERSION >= 2.7

EXAMPLE: property isRegistered

<script>
    console.log(znetdkMobile.serviceWorker.isRegistered);
</script>

The znetdkMobile.install methods

 Method isAppInstallable()

DESCRIPTION Checks whether the App is installable or not.
RETURNED VALUE Boolean Value true if App is installable (beforeinstallprompt A2HS event is fired).
VERSION >= 2.7

EXAMPLE: Checking if App is installable

<script>
    console.log(znetdkMobile.install.isAppInstallable());
</script>

 Method isAppInstalled()

DESCRIPTION Checks whether the App is installed or not.
RETURNED VALUE Boolean Value true if App is installed.
VERSION >= 2.7

EXAMPLE: Checking if App is installed

<script>
    console.log(znetdkMobile.install.isAppInstalled());
</script>

 Method showInstallView()

DESCRIPTION Displays the view for installing the App.
This view corresponds to the Installation screen displayed from the User panel when user authentication is enabled (see CFG_AUTHENT_REQUIRED PHP constant).
VERSION >= 2.7

EXAMPLE: Displaying installation view

<script>
    znetdkMobile.install.showInstallView();
</script>

 Method showUninstallView()

DESCRIPTION Displays the view for uninstalling the App.
This view corresponds to the Uninstallation screen displayed from the User panel when user authentication is enabled (see CFG_AUTHENT_REQUIRED PHP constant).
VERSION >= 2.7

EXAMPLE: Displaying uninstallation view

<script>
    znetdkMobile.install.showUninstallView();
</script>

 Method showInstallableMessage()

DESCRIPTION Displays the prompt to install the App.
This method can be useful to display on demand the installation prompt when the CFG_MOBILE_INSTALL_MESSAGE_DISPLAY_AUTO PHP constant is set to FALSE.
VERSION >= 2.7

EXAMPLE: Displaying prompt for installing App

<script>
    znetdkMobile.install.showInstallableMessage();
</script>

Miscellaneous Tools

The znetdkMobile.browser methods

 Method doPhoneCall()

DESCRIPTION Displays the screen for dialing a telephone number and pre-fills it with the telephone number specified in parameter.
PARAMETERS
phoneNumber String The phone number.
VERSION >= 2.7

EXAMPLE: Doing a phone call

<script>
    znetdkMobile.browser.doPhoneCall('+33701234567');
</script>

 Method sendSMS()

DESCRIPTION Displays the screen for writing a SMS and pre-fills it with the specified phone number and text of the SMS.
PARAMETERS
phoneNumber String The phone number.
message String The text of the SMS.
VERSION >= 2.7

EXAMPLE: Sending a SMS

<script>
    znetdkMobile.browser.sendSMS('+33701234567', 'Hello John Doe');
</script>

The znetdkMobile.file methods

 Method display()

DESCRIPTION Downloads from the specified URL in HTTP GET the specified resource (picture or document) and displays it.
When authentication is required (see CFG_AUTHENT_REQUIRED parameter) and user's session has expired, the login dialog is displayed to renew the user's session.
PARAMETERS
url String Url of the file to download. If pre-authentication of the user is required, the URL is usually obtained via a controller action by calling the General::getURIforDownload() PHP method.

EXAMPLE: Downloading a PDF document

<script>
    const docUrl = '<?php echo General::getURIforDownload('featurectrl', 'filename=document.pdf'); ?>';
    znetdkMobile.file.display(docUrl);
</script>