Bizzo Mendix PWAs Generator

Convert Mendix Apps to Progressive Web Apps PWAs

Demo

Check & install Demo app, a simple Todo App

Or you can also take a quick look here!

Getting Started

These instructions will walk with you step by step through the process of creating/converting Mendix Apps to Progressive Web Apps.

Prerequisites

This Generator requires node & gulp-cli to be installed on your machine.

you can check if you already have node installed by opening your command line tool and typing :

$ node --version
>> v8.9.4 // output your installed node version number

If you don't have node on your machine, you can download it from its official website Nodejs.org

After making sure that you have node installed, let's check if you have gulp-cli installed, you can do that by typing in your command line tool:

$ gulp -v
>> CLI version 1.3.0 // output your installed node version number

If you don't have gulp-cli installed on your machine, you can install it by typing the following command in your command line tool:

$ npm install gulp-cli -g

After having node & gulp-cli installed we are now ready to go! 👍

Usage :

Download Bizzo PWA Package
Extract the content of the downloaded bizzo-pwa.zip into your Mendix Application root folder.

your root folder now should have a structure like this :

YOUR-MENDIX-APP-NAME
├── deployment
├── javasource
├── pwa_assets
│   ├── pwa_icons
│   ├── _bizzo-scripts
│   └── _bizzo-tags 
│   └── bizzo-connectivity-listener.js 
│   └── bizzo-sw-register.js 
│   └── manifest.json
├── resources
├── theme
│   ├── styles
│   ├── index.html
│   └── ...
├── userlib
├── widgets
├── .classpath
├── .project
├── bizzo.config.json
├── gulpfile.js
├── package.json
├── YOUR_APP_NAME.mpr
└── ...

Open your command line and run npm install Make sure that all the requirements are set and installed on your machine

IMPORTANT NOTE: after running npm install DO NOT forget to add node_modules folder to your svn ignore list

Now, in your index.html add the following comments:

Before the closing tag <head>...</head> add :

    <head>
        ....... meta tags
        ........ link tags
        ......... etc
        .........
        <!-- bizzo-tags -->
        <!-- bizzo-tags-end -->
    </head>

the generator will use this comment/hook to inject the required meta tags into your index.html file.

Before the closing tag <body>...</body> add :

    <body>
        ....... html tags
        ........ 
        ......... script tags
        ......... etc
        <!-- bizzo-scripts -->
        <!-- bizzo-scripts-end -->
    </body>

the generator will use this comment/hook to inject the required scripts into your index.html file.

From your Mendix app root folder, open your command line tool and run the following command :

npm run bizzo-pwa

We're done! re-run your Mendix App which became now a progressive web app. 😎🥇

What does `npm run bizzo-pwa' do ?

It will read the config file bizzo.config.json in your root folder ( read how to set configuration ) and generate/inject/add the required files/tags for your mendix project.

⚙ Configuration: bizzo.config.json

This file contains the configuration for your Mendix PWA project,and is the only place that you need to work with while you're using this generator. Below we will explore all properties in this file :

{
    "appShortName":"Bizzo MX-PWA",
    "appName" :"Bizzo MX-PWA Boilerplate",
    "deploymentFolderPath": "./deployment/web",
    "extentionsToBeCached":["html","js","css","svg","png","jpg"],
    "sourceFolderPath":"./theme",
    "themeColor" : "#000000",
    "backgroundColor":"#ffffff",
    "appIcons":[
        {"img_512":"https://raw.githubusercontent.com/bizzomate/Bizzo-PWA/master/static/lab_512.png"},
        {"img_192":"https://raw.githubusercontent.com/bizzomate/Bizzo-PWA/master/static/lab_192.png"},
        {"img_128":"https://raw.githubusercontent.com/bizzomate/Bizzo-PWA/master/static/lab_128.png"}
    ],
    "offlineEnabled" : false
}

The contnten above is the default configuration

appShortName (Type : String)

Progressive Web Apps are installable therefore this property will be used to provide a short human-readable name for the application. This is intended for when there is insufficient space to display the full name of the web application, like device (desktop / mobile) homescreens.

appName (Type : String)

The name that will be displayed in the app splash screen after installing the app.

deploymentFolderPath (Type : String, Default : ./deployment/web)

The directory from which your web app is being served 99.99% you won't change this property

extentionsToBeCached (Type : Array Of String)

Array of file formats that your app contains and you'd like these files to be cached.

sourceFolderPath (Type : String, Default : ./theme)

The directory which contains your source files ( index.html, styles, scripts ...etc ) 99.99% you won't change this property

themeColor (Type : String)

A Hex number which represents your app theme color.

backgroundColor (Type : String)

A Hex number which represents your app's splash screen background color.

appIcons (Type : Array of Objects):

This piece of configuration requires you to set 3 different sizes for your app's icons [512x512, 192x192, 128x128], by default it has the following value:

"appIcons":[
        {"img_512":"https://raw.githubusercontent.com/bizzomate/Bizzo-PWA/master/static/lab_512.png"},
        {"img_192":"https://raw.githubusercontent.com/bizzomate/Bizzo-PWA/master/static/lab_192.png"},
        {"img_128":"https://raw.githubusercontent.com/bizzomate/Bizzo-PWA/master/static/lab_128.png"}
    ]

How to edit this property ?

After running npm run bizzo-pwa a folder named pwa_icons will be added to your theme folder, add your icons to this > folder, let's say that your icons have the following names [my-icon-512.png, my-icon-192.png, my-icon-128.png]; Now, back to your config file you need only to add your icons names as the following :
"appIcons":[
        {"img_512":"my-icon-512.png"},
        {"img_192":"my-icon-192.png"},
        {"img_128":"my-icon-128.png"}
    ]
IMPORTANT : Icons Must always be placed in your pwa_icons folder.

What are these sizes ?

512x512 icon will be used in your app's splash screen as an icon/ a logo.

128x128 & 192x192 icons will be used for your app's icon on smart devices home screens.

offlineEnabled (Type : boolean, Default False)

Mendix has the ability to create offline enabled apps, set this property to true if your app is offline enabled.

Best Practices 👌🐱‍👤:

During development, it's recommended to create a separate mendix project settings (different port number) for your PWA, as in your PWA, service worker will intersect your app's requests and serve cached static contents (scripts, styles, images, icons, etc ...) if exist, although each time you run npm run bizzo-pwa the cached content will be updated, it's better to have a separated settings for your PWA in order to prevent any confusion.

You can achieve that in your Mendix Modeler by doing the following :

Create new project configuration.

And select it while working on your app.

Now let's say you wanna continue working on your project, for instance working on theming your project, you can return to use your previous project settings ( port number ) and have to go index.html and comment out the following script bizzo-sw-register.js :

<!-- <script src="bizzo-sw-register.js"></script> -->

By doing that you'll ensure that there are NO side effects coming from your PWA scripts or settings.

What browser to use for development?

Chrome 👍

During development, in your chrome dev tools in Service Workers tab check the option update on reload, this option will ensure that your service worker bizzo-sw.js is always in sync and up to date with the generated version using this generator.

How to delete an installed PWA ?

On your desktop/laptop you can delete an installed PWA by typing in the address bar of your chrome browser chrome://apps/ and then hitting Enter, a page with all installed apps will open, then right click on your app's icon and Remove from chrome.

On your smart device (phone / tablet), you can just uninstall it as it is a native app.

And you can clear your chrome browser cache on your smart device by typing in your address bar chrome://offline-internals

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
build		build
docs/images		docs/images
pwa_assets		pwa_assets
static		static
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
bizzo.config.json		bizzo.config.json
gulpfile.js		gulpfile.js
mendix_pwa.png		mendix_pwa.png
package-lock.json		package-lock.json
package.json		package.json

License

bizzomate/Bizzo-PWA

Folders and files

Latest commit

History

Repository files navigation

Bizzo Mendix PWAs Generator

Demo

Getting Started

Prerequisites

Usage :

What does `npm run bizzo-pwa' do ?

⚙ Configuration: bizzo.config.json

appShortName (Type : String)

appName (Type : String)

deploymentFolderPath (Type : String, Default : ./deployment/web)

extentionsToBeCached (Type : Array Of String)

sourceFolderPath (Type : String, Default : ./theme)

themeColor (Type : String)

backgroundColor (Type : String)

appIcons (Type : Array of Objects):

How to edit this property ?

offlineEnabled (Type : boolean, Default False)

Best Practices 👌🐱‍👤:

Demo Show 🎦:

App installed on a desktop

Install app on your smart device

Open installed app

Splash screen

App opened (displayed in 'full-screen mode' as a native app)

App icon

Issues

About

Topics

Resources

License

Stars

Watchers

Forks

Languages

appShortName (Type : `String`)

appName (Type : `String`)

deploymentFolderPath (Type : `String`, Default : `./deployment/web`)

extentionsToBeCached (Type : `Array Of String`)

sourceFolderPath (Type : `String`, Default : `./theme`)

themeColor (Type : `String`)

backgroundColor (Type : `String`)

appIcons (Type : `Array of Objects`):

offlineEnabled (Type : `boolean`, Default `False`)