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

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.

See below the properties and methods of the data list object.

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 znetdkMobile.list properties

rowsPerPage, heightDiffForNewPage, uniqueSearchedKeyword, 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 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 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

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

 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.
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');
</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>

Input form

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

 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.
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.
PARAMETERS
inputName String Name of the input field (HTML attribute name).
RETURNED VALUE String | Boolean The value of the input field, false otherwise.

EXAMPLE: method znetdkMobile.form.getInputValue()

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

 Method setInputValue()

DESCRIPTION Set the value of the specified input field.
PARAMETERS
inputName String Name of the input field (HTML attribute name).
inputValue String Value to set to the input field.
silent Boolean | undefined OPTIONAL, when different than true, an error is displayed into the browser console if the specified input field not exists.
RETURNED VALUE Boolean Value true when succeeded, false otherwise.

EXAMPLE: method znetdkMobile.form.setInputValue()

<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 Get the value of the specified input field.
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

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;
    }
}
?>

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 Content

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

 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>

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, viewId) {
        console.log(viewId);
    });
</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, viewId) {
        console.log(viewId);
    });
</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>