Install the App?

Getting Started

Your first steps with ZnetDK 4 Mobile

SUMMARY

INSTALLING ZNETDK FOR MOBILE
CUSTOMIZING THE STARTER APPLICATION
ADDING NEW VIEWS AND MENU ENTRIES
CONNECTING TO A DATABASE
ENABLING USER AUTHENTICATION
GOING FURTHER...

Installing ZnetDK for Mobile

The installation of ZnetDK for Mobile lasts only a few minutes...

Prerequisite

AMP logos

ZnetDK for Mobile can be installed on any machine or web hosting having a web server (i.e. Apache, NGINX...) and PHP pre-installed.
For database access, MySQL is also required.

For development purpose, an Apache MySQL PHP package can be easily installed on your PC (Windows or Linux) or Apple computer (see list of AMP packages).

For writing the code of your application, you can use a simple text editor or a code editor like Notepad++.
However, for accelerating the development and debugging effectively your application, it's better to use an IDE like NetBeans or Eclipse.

Downloading ZnetDK for Mobile

Just go to the Download page on this website and download the latest version.

Once the download terminated, you get a ZIP archive named znetdk4m-vxx.zip containing the files to install on your computer or your hosting machine.

Deploying ZnetDK upon a web server

The deployment consists in extracting the downloaded ZIP archive znetdk4m-vxx.zip into the internet publication folder.

The folder where to publish the web application depends on your AMP package or your hosting provider.
Here are some common web root folders where to publish a website:

  • WAMP: C:\wamp\www\
  • XAMPP: C:\xampp\htdocs\
  • Easy PHP: C:\Program Files (x86)\EasyPHP-Devserver-17\eds-www\
  • A Linux Hosting: /var/www/
  • Another Linux Hosting: /home/www/

Once the ZIP archive content is extracted, you should have a subdirectory named znetdk4m.
If this subdirectory is not directly extracted into the target web root directory, so in this case move it to the right directory on your local filesystem.
If you can't extract your ZIP archive on your remote hosting storage space, then extract it locally on your computer and transfer it to the target web root directory using the FTP service of your hosting provider or a FTP software like FileZilla.

Finally, if the web root folder is for example /home/www/, so you should see the /home/www/znetdk4m/index.php script file that is ran by default when accessing a ZnetDK application.

ZnetDK for Mobile - Deployment

Displaying the starter Application

ZnetDK for Mobile Starter App

By now, open your web browser and enter in the address bar, the URL http://mydomain.net/znetdk4m/ to display the home page of the ZnetDK for Mobile Starter Application.

If you installed ZnetDK locally on your computer, then enter the URL http://localhost/znetdk4m/.

The Starter Application displays the home page as illustrated on the photo beside.

When you scroll down the home page, you can see some extra information about the database access status.

Please ignore for the moment all the error messages displayed.
Indeed, the connection to the database is not yet configured.

The following chapters will describe how to proceed to connect successfully and to install the SQL security tables.

ZnetDK for Mobile - Database access status

It's now time for you to read the next chapter and customize your Starter Application...

Customizing the Starter Application

To customize the Starter Application, you're going to edit some PHP scripts that come with the installed ZnetDK 4 Mobile framework and that belong specifically to the default application.

The code of the applications you will develop is located into the applications/ subfolder, under the folder where ZnetDK is installed (for example /home/www/znetdk4m that will be named INSTALL_DIR/ afterward in this page).

Several applications can be published within the INSTALL_DIR/applications/ subfolder.

The code of the Starter Application is located into the INSTALL_DIR/applications/default/ subfolder.

ZnetDK for Mobile - Customizing

Changing the titles of the application

To modify the titles of the Starter Application, edit the INSTALL_DIR/applications/default/app/lang/locale.php PHP script.

The page title of the Starter Application is ZnetDK 4 Mobile by default.
This is the title displayed when bookmarking the application and also the one displayed on the web browser tab.
To change this title, modify the value of the LC_PAGE_TITLE constant.

EXAMPLE: locale.php

define('LC_PAGE_TITLE', 'My page title');
PHP

The other title displayed by default on the application header bar is Starter App.
Modify the value of the LC_HEAD_TITLE constant to change the application header bar title.

EXAMPLE: locale.php

define('LC_HEAD_TITLE', 'My App title');
PHP

The version number, the copyright and the Developed with ZnetDK text displayed on the Starter App footer can be customized too.

For that, edit again the INSTALL_DIR/applications/default/app/lang/locale.php script and modify the value of the LC_FOOTER_LEFT, LC_FOOTER_CENTER and LC_FOOTER_RIGHT constants.

EXAMPLE: locale.php

define('LC_FOOTER_LEFT', 'Version 2.0');
define('LC_FOOTER_CENTER', '<a href="http://mywebsite.org">My website</a>');
define('LC_FOOTER_RIGHT', '<b>Phone:</b> +33 678901234');
PHP

Setting the theme colors

ZnetDK for Mobile - Color themes

The ZnetDK for Mobile application UI was developed from the W3.CSS framework.

The default color theme applied to the Starter Application is the w3-theme-blue.
Browse and download the theme of your choice from the W3.CSS Color Themes page.

To apply another color theme, edit the INSTALL_DIR/applications/default/app/config.php configuration script of the application and then, set the URL of the W3.CSS theme for the CFG_MOBILE_W3CSS_THEME constant.

This constant already exists into the configuration PHP script and just need to be uncommented then modified.

EXAMPLE: config.php

define('CFG_MOBILE_W3CSS_THEME','https://www.w3schools.com/lib/w3-theme-blue-grey.css');
PHP

Setting the theme font

ZnetDK for Mobile - Theme font

The font set by default for the Starter Application is the Exo font coming from the Google Fonts.

To replace this font by another Google Font of your choice, edit again the INSTALL_DIR/applications/default/app/config.php configuration script and then, set the URL of the font for the CFG_MOBILE_CSS_FONT constant and the font family through the CFG_MOBILE_CSS_FONT_FAMILY constant.

Theses constants already exist into the configuration PHP script and just need to be uncommented then modified.

EXAMPLE: config.php

define('CFG_MOBILE_CSS_FONT', 'https://fonts.googleapis.com/css?family=Raleway&display=swap');
define('CFG_MOBILE_CSS_FONT_FAMILY', "'Raleway', sans-serif");
PHP

Setting custom logos

The Starter Application ZnetDK logos can be replaced by your own logos.

The ZnetDK logos are displayed both in the left vertical menu and as the favicon of the application.

The left vertical menu logo

ZnetDK for Mobile - Custom logo

To add your custom logo upon the left vertical menu, copy your logo file (with extension .JPEG, .PNG, .GIF...) into the INSTALL_DIR/applications/default/public/images/ folder.
Next, edit the INSTALL_DIR/applications/default/app/lang/locale.php script, uncomment the line matching the LC_HEAD_IMG_LOGO constant and at last replace the logo.png filename by the one of the custom logo.

EXAMPLE: locale.php

define('LC_HEAD_IMG_LOGO', ZNETDK_APP_URI.'images/mylogo.jpg');
PHP

ZNETDK_APP_URI is a PHP constant containing the URI of the application.

The favicon logo

ZnetDK for Mobile - Favicons

To set a custom favicon for the Starter App, you have first to create a favicon package. This favicon package can be easily generated from a website like RealFaviconGenerator.
Once your favicon ZIP package is downloaded, extract the files into the INSTALL_DIR/applications/default/public/images/favicons/ folder.

Next, edit the INSTALL_DIR/applications/default/app/layout/mobile_favicons.php script and paste the HTML code given by RealFaviconGenerator to include the favicon fileset into the web application main page.

Be sure to prefix each filename by the <?php echo $faviconDir; ?> PHP code as illustrated below. Indeed, the $faviconDir PHP variable contains the path of the folder where you copied the favicon files.

EXAMPLE: custom PHP script mobile_favicons.php

<link rel="apple-touch-icon" sizes="180x180" href="<?php echo $faviconDir; ?>apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="<?php echo $faviconDir; ?>favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="<?php echo $faviconDir; ?>favicon-16x16.png">
<link rel="manifest" href="<?php echo $faviconDir; ?>site.webmanifest">
<link rel="mask-icon" href="<?php echo $faviconDir; ?>safari-pinned-tab.svg" color="#5bbad5">
<link rel="shortcut icon" href="<?php echo $faviconDir; ?>favicon.ico">
<meta name="msapplication-TileColor" content="#ffc40d">
<meta name="msapplication-config" content="<?php echo $faviconDir; ?>browserconfig.xml">
<meta name="theme-color" content="#ffffff">
PHP HTML5

In addition, to make your web application installable on the user's terminal (see page Progressive Web App (PWA) for more info), you need to edit the site.webmanifest file and change in particular, the start_url field's value to "../../../../../".
Thereby, the web browser can find out through this relative path from the site.webmanifest file location, the folder where the index.php main page is for launching the application.

EXAMPLE: custom file site.webmanifest

{
  "name": "My custom APP",
  "short_name": "My APP",
  "description": "The description of my custom APP",
  "start_url": "../../../../../",
  "icons": [
    {
      "src": "android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "android-chrome-256x256.png",
      "sizes": "256x256",
      "type": "image/png"
    },
    {
      "src": "android-chrome-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "display": "standalone"
}
JSON

Finally, edit the INSTALL_DIR/applications/default/app/config.php configuration script and uncomment the two lines matching the CFG_MOBILE_FAVICON_DIR and CFG_MOBILE_FAVICON_CODE_FILENAME constants.

EXAMPLE: config.php

define('CFG_MOBILE_FAVICON_DIR', 'applications/' . ZNETDK_APP_NAME .'/public/images/favicons');
define('CFG_MOBILE_FAVICON_CODE_FILENAME', 'applications/' . ZNETDK_APP_NAME . '/app/layout/mobile_favicons.php');
PHP

ZNETDK_APP_NAME is a PHP constant containing the value 'default'.

Now, you can add a shortcut icon for the application on the Home Screen of your mobile phone or tablet and see your custom favicon.

Adding new views and menu entries

In this chapter, you will see how to add additional views to your Starter Application and how to display them when clicking on new navigation menu items.

New views

A view is a script written in HTML5 and in PHP whose content is intended to be displayed in the application.
A view is usually added to the application to display an input form, a list of data, a dashboard, a calendar, graphics, a photo album, documentation, etc.
The view content is displayed when the user clicks on a menu item.

Let's create 3 simple views with just a title and a paragraph.
To do so, add the 3 PHP scripts myview1.php, myview2.php and myview3.php to the INSTALL_DIR/applications/default/app/view/ folder.
Here is the HTML code of this 3 views below.

EXAMPLE: myview1.php

<h2>My First view</h2>
<p>Here is the text of my first view...</p>
HTML5

EXAMPLE: myview2.php

<h2>My Second view</h2>
<p>Here is the text of my second view...</p>
HTML5

EXAMPLE: myview3.php

<h2>My Third view</h2>
<p>Here is the text of my third view...</p>
HTML5

To display these views, we need now to tie them to the navigation menu as explain in the next chapter.

New menu items

Navigation in the application is provided by the left vertical menu and the horizontal menu above the displayed view.
The left vertical menu displays the Level one menu items while the horizontal menu displays the Level two menu items.

Now let's tie to the navigation menu, the 3 previously created views.
Edit the INSTALL_DIR/applications/default/app/menu.php PHP script and add the 4 highlighted lines of code into the Menu::initAppMenuItems() method as shown below.

EXAMPLE: menu.php

static public function initAppMenuItems() {
    \MenuManager::addMenuItem(NULL, 'home', 'Home', 'fa-home');
    
    \MenuManager::addMenuItem(NULL, 'myview1', 'My first view', 'fa-hourglass-1');
    \MenuManager::addMenuItem(NULL, '_myotherviews', 'My other views', 'fa-hourglass');
    \MenuManager::addMenuItem('_myotherviews', 'myview2', 'My second view', 'fa-hourglass-2');
    \MenuManager::addMenuItem('_myothesviews', 'myview3', 'My third view', 'fa-hourglass-3');
    
    \MenuManager::addMenuItem(NULL, '_authorizations', LC_MENU_AUTHORIZATION, 'fa-unlock-alt');
    \MenuManager::addMenuItem('_authorizations', 'z4musers', LC_MENU_AUTHORIZ_USERS, 'fa-user');
    \MenuManager::addMenuItem('_authorizations', 'z4mprofiles', LC_MENU_AUTHORIZ_PROFILES, 'fa-key');
}
PHP
adding new menu items

Now if you refresh the display of the application in your web browser and then click on the menu button (  ) on the top left of the screen, you should see 2 new menu items within the left vertical menu.

One level menu

My first view menu item is a Level one menu item. When you click on it, the myview1.php view is displayed and the My first view label is also displayed on the horizontal menu.
If we look a little closer to the \MenuManager::addMenuItem(NULL, 'myview1', 'My first view', 'fa-hourglass-1') function call, we can observe that the first parameter is set to NULL to indicate this is a Level one menu item.
The second parameter 'myview1' is the name of the view to display (without the .php extension) when clicking on the menu item.
The third parameter 'My first view' is the menu item label displayed on the navigation vertical et horizontal menus.
The last parameter 'fa-hourglass-1' is the name of the Font Awesome 4.7 icon to display for this menu item.

Two levels menu

On the other hand, My other views menu item is a Level two menu item. When you click on it, the myview2.php view is displayed and the My second view and My third view menu items are displayed on the horizontal menu. To display the myview3.php view, you have to click on My third view menu item.
It is the call to \MenuManager::addMenuItem(NULL, '_myothersview', 'My other views', 'fa-hourglass') which allows to add the Level one My other views menu item. The second parameter '_myothersview' does not match any view. It only serves to identify the Level 1 menu item when adding Level 2 items.
Indeed, the last two calls to \MenuManager::addMenuItem('_myothersview', ...) are done with the '_myothersview' value as first parameter to indicate that the parent menu item is My other views.

Connecting to a Database

This chapter describes the way to configure the Starter Application for connecting it to a local or remote MySQL database.

The database features

The database is a MySQL or MariaDB database created with the utf8_unicode_ci characterset.

The database user must have all the necessary privileges to connect to the database (locally or remotely as needed) and to SELECT, INSERT, UPDATE, and DELETE rows from the database tables.

Configuring the Application

Edit the INSTALL_DIR/applications/default/app/config.php script then uncomment and modify the following constant values.

EXAMPLE: config.php

define('CFG_SQL_HOST', '127.0.0.1');
define('CFG_SQL_PORT', NULL);
define('CFG_SQL_APPL_DB', 'znetdk-db');
define('CFG_SQL_APPL_USR', 'znetdk');
define('CFG_SQL_APPL_PWD', 'password');
PHP

CFG_SQL_HOST: host name of the machine where the database MySQL is installed.
CFG_SQL_PORT : TCP/IP port number on which the SQL Server listens (optional, for remote database).
CFG_SQL_APPL_DB: database created for the application.
CFG_SQL_APPL_USR: user declared in the application database.
CFG_SQL_APPL_PWD: the user's password.

Checking the connection

Once you configured the connection to the database, return to the home view of the Starter Application to check the connection status.
Click on the Reload to check again button to reload the home view after any change of the database connection settings.

Ignore for the moment the error concerning the Security SQL tables. It means that SQL tables are missing. You will see how to add these tables in the next chapter.

check database connection

Enabling user authentication

You will see in this chapter how to install the Security SQL Tables, how to declare the users of the Startup Application and then, how to enable the login form for authenticating them.

Installing the Security SQL Tables

The Security SQL tables are required to store user informations, credentials and profiles.

First, go to the Download page on this website and download the Security SQL script.
Next, import this SQL script into your database with phpMyAdmin or directly in command line by calling the MySQL Client.
Finally, display again the home view of your Starter Application and check the Database connection status.
The message properly installed would be displayed when all the Security SQL tables are correctly installed.

check installation of the security SQL table

Declaring users

To declare users and allow them to connect to the application, go to the Starter Application navigation menu and click on the Authorizations menu item.
Next, click on the red Plus button (+) located at the bottom right of the screen to display the user input form.
Fill in the form then click on the Save button.
Do not forget to check the Full Menu access option to give the user, full access to the application's navigation menu.

If you want to restrict the user's access to a subset of navigation menu items, create first a user profile in which only those menu items are selected.
Then, when you register the user, select the user profile that you just created and this time, the Full Menu access option should be left unchecked.

creating a new user

Configuring user authentication

When you install ZnetDK for Mobile, the embedded Starter Application is not configured by defaut for displaying the login form.

To enable user authentication, edit the the INSTALL_DIR/applications/default/app/config.php configuration script of the application and then change the value of the CFG_AUTHENT_REQUIRED constant to TRUE as illustrated below.

EXAMPLE: config.php

define('CFG_AUTHENT_REQUIRED',TRUE);
PHP

Checking user authentication

log in to the ZnetDK for Mobile Starter Application

It is now time to log in to the application with the previously registered user account.

With authentication now enabled, reload the Starter application in the web browser to display the login form.

Enter the credentials of the previously created user. The application now can be only used by authenticated users.

Going further...

Congratulations! You have successfully customized and configured your Starter Application. You are ready to develop your business features in PHP and JavaScript.
To manage a list of contacts with your Starter Application, I invite you to read the Tutorial on this website.

Nevertheless, if you have trouble installing, customizing or developing your first application, feel free to post your questions, comments or feedback on the official ZnetDK Forum.