Install the App?
Settings
Settings of the ZnetDK for Mobile Starter Web App
SUMMARY
- The global parameters in the
INSTALL_DIR/applications/default/app/config.phpscript. - The application labels in the
INSTALL_DIR/applications/default/app/lang/locale.phpscript. - The application Apache parameters in the
INSTALL_DIR/.htaccessscript.
Application labels and logo
The PHP constants defined below can be modified to customize some labels and the navigation menu logo of your Web app.
PHP Constants
LC_PAGE_TITLE, LC_HEAD_TITLE, LC_FOOTER_LEFT, LC_FOOTER_CENTER, LC_FOOTER_RIGHT, LC_HEAD_IMG_LOGO
Constant LC_PAGE_TITLE
EXAMPLE
define('LC_PAGE_TITLE', 'My page title');
Constant LC_HEAD_TITLE
EXAMPLE
define('LC_HEAD_TITLE', 'My App title');
Constant LC_HEAD_IMG_LOGO
EXAMPLE
define('LC_HEAD_IMG_LOGO', ZNETDK_APP_URI . 'images/mylogo.png');
Database settings
The following parameters are required to connect your Web App to a MySQL database and so, query data through the \DAO and \SimpleDAO ZnetDK classes, both based on the PHP PDO class.
See Getting Started | Connecting to a database for more information.
PHP Constants
CFG_SQL_HOST, CFG_SQL_PORT, CFG_SQL_APPL_DB, CFG_SQL_APPL_USR, CFG_SQL_APPL_PWD, CFG_SQL_TRACE_ENABLED
Constant CFG_SQL_HOST
EXAMPLE
define('CFG_SQL_HOST', 'localhost');
Constant CFG_SQL_PORT
EXAMPLE
define('CFG_SQL_PORT', '35105');
Constant CFG_SQL_APPL_DB
EXAMPLE
define('CFG_SQL_APPL_DB', 'mydatabase');
Constant CFG_SQL_APPL_USR
EXAMPLE
define('CFG_SQL_APPL_USR', 'myuser');
Constant CFG_SQL_APPL_PWD
EXAMPLE
define('CFG_SQL_APPL_PWD', 'mypassword');
Constant CFG_SQL_TRACE_ENABLED
EXAMPLE
define('CFG_SQL_TRACE_ENABLED', TRUE);
Authentication
To limit access to your application to only authorized users, authentication must first be enabled (see CFG_AUTHENT_REQUIRED PHP constant).
Next, authorized users can be declared via the User Management form.
In addition, user rights on menu items and data can be restricted by adding profiles through the Profile Management form (see Profile management and user rights).
PHP Constants
CFG_AUTHENT_REQUIRED,
CFG_SESSION_DEFAULT_MODE,
CFG_SESSION_SELECT_MODE,
CFG_SESSION_TIMEOUT,
CFG_DEFAULT_PWD_VALIDITY_PERIOD,
CFG_CHECK_PWD_VALIDITY,
CFG_FORGOT_PASSWORD_ENABLED,
CFG_FORGOT_PASSWORD_REQUEST_TRACE_ENABLED
CFG_APPLICATION_VERSION
Parameters to enable user authentication and configure the user session.
See Getting Started | Enabling user authentication for more information.
Constant CFG_AUTHENT_REQUIRED
EXAMPLE
define('CFG_AUTHENT_REQUIRED', TRUE);
Constant CFG_SESSION_DEFAULT_MODE
EXAMPLE
define('CFG_SESSION_DEFAULT_MODE', 'public');
Constant CFG_SESSION_SELECT_MODE
EXAMPLE
define('CFG_SESSION_SELECT_MODE', FALSE);
Constant CFG_SESSION_TIMEOUT
EXAMPLE
define('CFG_SESSION_TIMEOUT', 5);
Constant CFG_DEFAULT_PWD_VALIDITY_PERIOD
EXAMPLE
define('CFG_DEFAULT_PWD_VALIDITY_PERIOD', 3);
Constant CFG_CHECK_PWD_VALIDITY
EXAMPLE
define('CFG_CHECK_PWD_VALIDITY', '/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{12,}$/');
Constant CFG_FORGOT_PASSWORD_ENABLED
EXAMPLE 1: config.php, display of the Forgot your password?
link
define('CFG_FORGOT_PASSWORD_ENABLED', TRUE);
EXAMPLE 2: forgotpassword.php, emails sent via a custom app/controller/ForgotPassword class
<?php
namespace app\controller;
/* PHP script named 'forgotpassword.php' installed into the following directory:
'INSTALL_DIR/applications/default/controller/'
*/
/* PHPMailer is directly installed into the application */
use PHPMailer\PHPMailer\PHPMailer;
require 'app/phpmailer/src/Exception.php';
require 'app/phpmailer/src/PHPMailer.php';
class ForgotPassword extends \AppController {
/* Send email for confirmation */
static public function sendConfirmation($emailAddress, $confirmationUrl) {
$subject = 'Confirm your request for a new password';
$body = "Hello<br>Confirm your request by clicking <a href=\"{$confirmationUrl}\">this link</a>.";
if (!self::sendMail($emailAddress, $subject, $htmlMessage)) {
throw new \Exception('Unable to send email for confirmation!');
}
return TRUE;
}
/* Send password by email after confirmation */
static public function sendNewEmail($emailAddress, $tempPassword) {
$subject = 'Your new temporary password';
$body = "Hello<br>Here is your temporary password: <b>{$tempPassword}</b>";
if (!self::sendMail($emailAddress, $subject, $htmlMessage)) {
throw new \Exception('Unable to send temporary password!');
}
return TRUE;
}
/* Example of private sendMail method based on PHPMailer. Email is sent via PHP mail */
static private function sendMail($emailAddress, $subject, $htmlMessage) {
$mail = new PHPMailer();
$mail->setFrom('admin@example.com');
$mail->addAddress($emailAddress);
$mail->Subject = $subject;
$mail->msgHTML($htmlMessage);
return $mail->send();
}
}
?>
Constant CFG_FORGOT_PASSWORD_REQUEST_TRACE_ENABLED
EXAMPLE
define('CFG_FORGOT_PASSWORD_REQUEST_TRACE_ENABLED', TRUE);
Constant CFG_APPLICATION_VERSION
EXAMPLE
define('CFG_APPLICATION_VERSION', 2);
User management
ZnetDK includes in standard a dedicated view to manage the users authorized to access to the Web Application.
To manage users, the following requirements must be fulfilled:
- A menu item is defined in the
menu.phpof the application to access to thez4musers.phpview (see procedure). - The Web App is connected to a MySQL database (see procedure).
- The Security SQL tables for storing user authentication data must have been created in the database (see procedure).
To give access to users in the Web Application, follow the procedure Declaring the users.
User rights
Rights are generally granted to users though Profiles.
However, if no particular restriction applies to users, then no profile is required. Users must simply be declared with the Menu Access Full option checked.
Profile management and user rights
ZnetDK includes in standard a dedicated view to manage user profiles that can be assigned to users in order to restrict their rights in the Web Application.
To manage profiles, the following requirements must be fulfilled:
- A menu item is defined in the
menu.phpof the application to access to thez4mprofiles.phpview (see procedure). - The Web App is connected to a MySQL database (see procedure).
- The Security SQL tables for storing user authentication data must have been created in the database (see procedure).
A profile is generally created to restrict access to menu items in the application. In that case, the Menu Access Full option must be unchecked when assigning the profile to users.
It can also be defined to limit the visibility of the data when it is for some confidential, for example according to the department in the company in which the user works.
A profile can also be used to add specific functionalities to certain users or, on the contrary, to remove particularly sensitive functionalities.
When editing a user, one or several profiles can be assigned to him according to the rights we want to grant him.
The PHP API provides useful methods like \controller\Users::hasProfile() and \controller\Users::hasMenuItem() to grant specific rights to users programmatically based on their profiles and the menu items they have access to.
User panel
The User panel is displayed when clicking the user icon on the App header.
Only authenticated users have access to the User panel (see CFG_AUTHENT_REQUIRED parameter).
The following screens are displayed when you click the corresponding User panel button.
Password screen
My user rights screen
Installation screen
Uninstallation screen
Password validity period
When a user logs into the application, if their password has expired (see Expire on
entry field in the Edit a profile form), they are asked to renew it.
To renew their password, users have to enter the following informations:
- Original password: this is the original password which has expired and needs to be changed.
- New password: the new password which replaces the expired password.
- Confirmation: the confirmation of the new password (the same than the one entered for the
New password
field).
Users can also renew their password before it has expired from the User panel.
User account Disabled or Archived
Application theming
Colors, font and logos can be customized through the parameters described below.
See Getting Started | Customizing the Starter Application for more information.
PHP Constants
CFG_MOBILE_W3CSS_THEME, CFG_MOBILE_CSS_FONT, CFG_MOBILE_CSS_FONT_FAMILY, CFG_MOBILE_FAVICON_CODE_FILENAME, CFG_MOBILE_FAVICON_DIR
Constant CFG_MOBILE_W3CSS_THEME
EXAMPLE
define('CFG_MOBILE_W3CSS_THEME', 'https://www.w3schools.com/lib/w3-theme-blue-grey.css');
Constant CFG_MOBILE_CSS_FONT
EXAMPLE
define('CFG_MOBILE_CSS_FONT', 'https://fonts.googleapis.com/css?family=Poppins&display=swap');
Constant CFG_MOBILE_CSS_FONT_FAMILY
EXAMPLE
define('CFG_MOBILE_CSS_FONT_FAMILY', "'Poppins', sans-serif");
Constant CFG_MOBILE_FAVICON_CODE_FILENAME
EXAMPLE
define('CFG_MOBILE_FAVICON_CODE_FILENAME', 'applications/' . ZNETDK_APP_NAME . '/app/layout/mobile_favicons.php');
Constant CFG_MOBILE_FAVICON_DIR
EXAMPLE
define('CFG_MOBILE_FAVICON_DIR', 'applications/' . ZNETDK_APP_NAME .'/public/images/favicons');
App extra CSS and JS libraries
Additional CSS stylesheets and JavaScript libraries can be loaded for extending the web application capabilities through the following parameters.
PHP Constants
Constant CFG_APPLICATION_CSS
EXAMPLE
define('CFG_APPLICATION_CSS', serialize(array('applications/' . ZNETDK_APP_NAME . '/public/css/myscript.css', 'https://extracsslibrary.net/lib.css')));
Constant CFG_APP_JS
EXAMPLE
define('CFG_APP_JS', serialize(array('applications/' . ZNETDK_APP_NAME . '/public/js/myscript.js', 'https://extrajslibrary.net/lib.js')));
Language settings
By default, the Starter App shipped with ZnetDK 4 Mobile is configured to be displayed in English (CFG_DEFAULT_LANGUAGE parameter set to 'en' in the config.php of the application).
The core features of ZnetDK are translated in English, French and Spanish.
To display your Web APP in French, set CFG_DEFAULT_LANGUAGE to 'fr'. For a display in Spanish, set CFG_DEFAULT_LANGUAGE to 'es'.
To translate your App into a language not translated in standard, for example in Portuguese:
- Copy the
INSTALL_DIR/engine/core/lang/locale_en.phpenglish core translation script into theINSTALL_DIR/applications/default/app/lang/folder, - Rename the copied
locale_en.phpscript by changing theenfilename suffix to the ISO 639-1 country code corresponding to your country, in this case tolocale_pt.php. - Edit the new
locale_pt.phpscript and translate the PHP constant values in Portuguese. - Edit the
INSTALL_DIR/applications/default/app/config.phpPHP script and change the value of theCFG_DEFAULT_LANGUAGEparameter fromento'pt'. - Refresh your Web App in your web browser; the title, the footer, the user and profil management features are now translated in Portuguese.
It is also possible to translate a view of the application directly into several languages.
For example, if a view is originally named myview.php with text displayed in English, then it might be suffixed with its language code (eg myview_en.php).
This view once translated into Spanish will be named myview_es.php and the one translated into French will be named myview_fr.php.
Thus, the view corresponding to the language to be displayed for the application will be chosen automatically by ZnetDK.
Finally, the display of the application can be set to a specific language by reloading it with the ?lang=<iso code> parameter added to its URL.
For example, to display the application in Spanish: https://mydomain/myapp?lang=es.
See on the Code Snippets page an example of Multilingual application.
PHP Constants
Constant CFG_DEFAULT_LANGUAGE
EXAMPLE
define('CFG_DEFAULT_LANGUAGE', 'es');
Constant CFG_MULTI_LANG_ENABLED
EXAMPLE
define('CFG_MULTI_LANG_ENABLED', TRUE);
Locale settings
The locale is used by ZnetDK to display dates and amounts formatted according to the user's language.
The locale can be set globally through the single LC_LOCALE_ALL PHP constant described below.
However, this implies that the desired locale is installed on the web server.
Alternatively, the locale can be directly customized using the following PHP constants, independently of the locales installed on the web server: LC_LOCALE_DECIMAL_SEPARATOR, LC_LOCALE_THOUSANDS_SEPARATOR, LC_LOCALE_NUMBER_OF_DECIMALS, LC_LOCALE_CURRENCY_SYMBOL, LC_LOCALE_CURRENCY_SYMBOL_PRECEDE, LC_LOCALE_CURRENCY_SYMBOL_SEPARATE, LC_LOCALE_DATE_FORMAT, LC_LOCALE_CSV_SEPARATOR
PHP Constants
LC_LOCALE_ALL, LC_LOCALE_DECIMAL_SEPARATOR, LC_LOCALE_THOUSANDS_SEPARATOR, LC_LOCALE_NUMBER_OF_DECIMALS, LC_LOCALE_CURRENCY_SYMBOL, LC_LOCALE_CURRENCY_SYMBOL_PRECEDE, LC_LOCALE_CURRENCY_SYMBOL_SEPARATE, LC_LOCALE_DATE_FORMAT, LC_LOCALE_CSV_SEPARATOR
Constant LC_LOCALE_ALL
EXAMPLE
define('LC_LOCALE_ALL', serialize(array('fr_FR', 'french', 'fr_FR.utf8')));
Constant LC_LOCALE_DECIMAL_SEPARATOR
EXAMPLE
define('LC_LOCALE_DECIMAL_SEPARATOR', ',');
Constant LC_LOCALE_THOUSANDS_SEPARATOR
EXAMPLE
define('LC_LOCALE_THOUSANDS_SEPARATOR', ' ');
Constant LC_LOCALE_NUMBER_OF_DECIMALS
EXAMPLE
define('LC_LOCALE_NUMBER_OF_DECIMALS', 2);
Constant LC_LOCALE_CURRENCY_SYMBOL
EXAMPLE
define('LC_LOCALE_CURRENCY_SYMBOL', '€');
Constant LC_LOCALE_CURRENCY_SYMBOL_PRECEDE
EXAMPLE
define('LC_LOCALE_CURRENCY_SYMBOL_PRECEDE', FALSE);
Constant LC_LOCALE_CURRENCY_SYMBOL_SEPARATE
EXAMPLE
define('LC_LOCALE_CURRENCY_SYMBOL_SEPARATE', ' ');
Constant LC_LOCALE_DATE_FORMAT
EXAMPLE
<?php
// ZnetDK version <= 2.7
define('LC_LOCALE_DATE_FORMAT', '%d-%m-%y');
// ZnetDK version >= 2.8
define('LC_LOCALE_DATE_FORMAT', 'd-m-y');
Constant LC_LOCALE_CSV_SEPARATOR
EXAMPLE
define('LC_LOCALE_CSV_SEPARATOR', ';');
Views loading
By default, a view is loaded only once on demand, is not removed from the DOM (Document Object Model) when it is hidden, and therefore is not reloaded when it is displayed again on subsequent times.
This behaviour can be changed via the following PHP constants.
PHP Constants
Constant CFG_VIEW_PRELOAD
EXAMPLE
define('CFG_VIEW_PRELOAD', TRUE);
Constant CFG_VIEW_PAGE_RELOAD
EXAMPLE
define('CFG_VIEW_PAGE_RELOAD', TRUE);
Stored documents
Pictures, documents and other files uploaded by users or generated by the Starter App can be stored within the INSTALL_DIR/applications/default/documents/ private directory whose absolute file path is accessible via the CFG_DOCUMENTS_DIR PHP constant described below.
PHP Constants
Constant CFG_DOCUMENTS_DIR
EXAMPLE
define('CFG_DOCUMENTS_DIR', '/home/documents');
Web Services
Controller actions can be exposed as Web Services.
The POST method should be used to call a Web Service. The GET method is reserved for downloading files.
The web service is authenticated through Basic Authentication. A dedicated user is generally declared in the application to call a web service.
For example, to execute the MyController::action_dostuff() controller action of the Application deployed at https://mydomain.com/mydir/, with the user account wsuser to authenticate, submit via the POST method the following URL:
EXAMPLE
https://wsuser:password@mydomain.com/mydir/?control=mycontroller&action=dostuff&my_param=myvalue
See below for PHP constants to configure controller actions to expose as a web service.
PHP Constants
Constant CFG_HTTP_BASIC_AUTHENTICATION_ENABLED
EXAMPLE
define('CFG_HTTP_BASIC_AUTHENTICATION_ENABLED', TRUE);
Constant CFG_ACTIONS_ALLOWED_FOR_WEBSERVICE_USERS
EXAMPLE
define('CFG_ACTIONS_ALLOWED_FOR_WEBSERVICE_USERS', serialize([
'wsuser|mycontroller:dostuff',
'wsuser|mycontroller:download'
]));
Constant CFG_DOWNLOAD_AS_POST_REQUEST_ENABLED
EXAMPLE
define('CFG_DOWNLOAD_AS_POST_REQUEST_ENABLED', TRUE);
HTTP errors 403 and 404
According to the directory where ZnetDK for mobile is installed, the HTTP Error 403 (access forbidden) and HTTP error 404 (page not found) must be handled properly by adjusting the Apache Web Server ErrorDocument parameter.
Then, if users attempt to access a page that does not exist or to which access is denied, then they will be automatically redirected to the dedicated ZnetDK HTTP error page.
The view displayed in case of HTTP errors is INSTALL_DIR/engine/core/view/httperror.php.
This view can be customized after having copied it into the INSTALL_DIR/applications/default/app/view/ folder.
Configuration scenarios
CASE 1: App deployed directly at http://mydomain/
For example, your web root directory is /var/www/html/ and so the file path of the .htaccess file shipped with ZnetDK is /var/www/html/.htaccess.
Here is below the path to specify for the ErrorDocument statement in the ZnetDK's .htaccess file.
.htaccess (in web server root directory)
ErrorDocument 403 /index.php?control=httperror&action=403
ErrorDocument 404 /index.php?control=httperror&action=404
CASE 2: App deployed at http://mydomain/mysubdirectory/
For example, your web root directory is /var/www/html/, the subdirectory is named mysubdirectory/ and so the file path of the .htaccess file shipped with ZnetDK is /var/www/html/mysubdirectory/.htaccess.
Here is below the path to specify for the ErrorDocument statement in the ZnetDK's .htaccess file.
.htaccess (in web server subdirectory)
ErrorDocument 403 /mysubdirectory/index.php?control=httperror&action=403
ErrorDocument 404 /mysubdirectory/index.php?control=httperror&action=404
Progressive Web App (PWA)
The ZnetDK 4 Mobile Starter Web application is natively configured to be a Progressive Web App.
A default service worker is started when loading the application.
The Starter Web App can be installed on devices with a web browser that supports A2HS feature like Chrome and Safari.
PHP Constants
Constant CFG_MOBILE_SERVICE_WORKER_URL
EXAMPLE
define('CFG_MOBILE_SERVICE_WORKER_URL', 'my-sw.js');
Constant CFG_MOBILE_INSTALL_MESSAGE_DISPLAY_AUTO
EXAMPLE
define('CFG_MOBILE_INSTALL_MESSAGE_DISPLAY_AUTO', FALSE);
Miscellaneous
Additionnal application settings are described in this section.
PHP Constants
Constant CFG_IS_IN_MAINTENANCE
EXAMPLE
define('CFG_IS_IN_MAINTENANCE', TRUE);