Kiwii

Kiwii is a lightweight unopinionated HTML5 Hybrid Mobile App framework. Kiwii relies on Backbone to build your MVC web application. It relies on Backbone.Radio for messaging, React for viewing and Ratchet and Font-Awesome for styling. However, you are not forced to use these technologies for messaging and styling. With a little effort, you can replace them by your preferred solutions.

And of course, Kiwii relies on Cordova to convert your web application into a Mobile Hybrid Application.

Kiwii is just Backbone! Kiwii aims at providing a very thin framework to reduce the overhead and thus to get a very fast Mobile Hybrid Application. And, Kiwii aims at providing a totally transparent framework without magic behind the curtains. With Kiwii we want to keep the framework as simple as possible. We want the developer to understand what it does.

A Kiwii webapp mainly consists of one HTML page, one CSS file, one Javascript file and a set of loosely coupled Backbone/React MVC modules.

If you are familiar with Backbone, Kiwii is really easy to use. If you aren't, you need to learn Backbone first as Kiwii is just a minimal glue around Backbone to facilitate its use.

Kiwii is shipped with a running minimalist webapp having a few pages and a vertical responsive menu. You can immediately start building your webapp from this skeleton.

Besides, Kiwii includes a CLI script, kiwii.js, to assist you on adding a new module (§ Add a new module).

Kiwii creates the webapp by building all the Javascript project files into an UMD bundle that it attaches to the HTML page (§ Architecture).

Kiwii relies on Babel and Browserify for the build. Thus, you can write ES6 Javascript code if you wish.

Kiwii uses Gulp to build a distribution version.

Prerequisites

Kiwii needs Node and Gulp for installation and building. They should be installed on your PC. As Gulp is only required to create a distribution version, you can start without.

Quick Startup

You can easily get your first Kiwii webapp running in a couple of minutes by just typing a few command lines. But first, you need to create an empty folder. It will contain your webapp.

Then, you have to install the Kiwii package globally. Open a terminal session and type the command:

npm install kiwii -g

If you don't have the rights to install Kiwii globally, you can install it locally in your project. Open a terminal session, move to your working directory - the empty folder you created - and type the following command:

npm install kiwii

Now populate your empty folder and create your first web app:

// populate
kiwii populate -n myapp
// Or, if you installed the package locally:
./node_modules/kiwii/bin/kiwii.js populate -n myapp
// Install Node.js packages
npm install
// Build your first webpapp
npm run build

Your working directory should contain now a set of files and a folder public that contains the webapp.

As your webapp is just the HTML file public/index.html with CSS files and a Javascript bundle attached, you can visualize it into your browser by a simple drag and drop of the file index.html.

Make sure that your Desktop browser is emulating mobile devices. Check out how to configure Google Chrome and Firefox to enable Mobile device mode.

Do it and you will see your webapp running. that's all!

Architecture

Kiwii webapp organization closely matches the Backbone structure. The webapp consists of one HTML file public/index.html, one CSS file public/css/style.css, and one Javascript file public/js/app.js.

When the HTML page is loaded into the browser, it imports the file style.css and starts the Javascript file app.js.

The file style.css imports a set of dependent CSS files (see the file). These CSS files define the general styling (Ratchet) and the font used (Font-Awesome) plus the styling specific to each Backbone module (see below).

The file app.js starts a Javascript script (see the file). It initializes Backbone URL history and starts the Backbone router public/js/router.js.

Thus, the basic structure of Kiwii webapp is:

public
  |_ index.html
  |_ css
  |   |_ style.css
  |_ js
      |_ main.js
      |_ router.js

At this basic structure, we add Kiwii Backbone modules.

There is a specific Backbone module that build the app by aggregating all the React components together.

public
  |_ app
      |_ app.js
      |
      |_ components
      |   |_ header.js
      |   |_ menu.js
      |   |_ body.js
      |   |_ footer.js
      |   |_ layout.js
      |
      |_ css
      |   |_ header.css
      |   |_ menu.css
      |   |_ body.css
      |   |_ footer.css
      |
      |_ models
      |   |_ appModel.js
      |
      |_ views
          |_ appView.js

The folder components contains all the React components to aggregate together to build the app. header.js, menu.js, body.js and footer.js are the basic React components and layout.js is the composite React component.

app.js is the interface of the module and appView.js contains the code for rendering the app (ReactDOM.render()).

The other specific views (home, settings, legal, etc.) are under pages:

public
  |_ pages
      |_ home
          |_ home.js
          |
          |components
          |   |_ body.js
          |
          |_ css
          |   |_ home.css
          |
          |_ models
          |   |_ homeModel.js
          |
          |_ views
              |_ homeView.js

The folder pages contains a set of folders. Each folder is a Kiwii Backbone module.

A Kiwii Backbone module consists of an interface, a view, a model, a React component and a style sheet.

The interface (here home.js) is the link with the other parts of the webapp. It sends and listens messages from the router/controller. It updates the model (here homeModel.js) and the view (here homeView.js). Models and Views have no link with the outside. They must go through the interface.

The React component (here body.js) contains the JSX structure of the page to display.

The style sheet (here home.css) defines what style to apply to this specific page.

Build

Kiwii provides three commands to build and run your webapp:

• npm run build,
• npm run watch,
• npm run app,

npm run build launches a script that bundles all the Javascript files, of your project, in one big file public/js/wapp.js. This file is attached to public/index.html.

npm run watch, as its name lets think, launches a script that watches the files of your project. If one file is modified, it automatically updates public/js/wapp.js.

npm run app creates an HTTP server listening on port 3000 and launches your default browser with the URL http://localhost:3000. You should see your webapp running in it.

Add a new module

When you want to add a new page, a new Kiwii Backbone module, to your project, you don't need to create all files and folders manually. You just need to type:

kiwii add -n <new_module_name> -p 'public/pages'
// Or, if installed locally:
./node_modules/kiwii/bin/kiwii.js add -n <new_module_name> -p 'public/pages'

The script creates a skeleton for the new Kiwii Backbone module. Then, you just need to fill the views and models functions and to complete the template and the style sheet.

When your module is ready to be tested, you need to instantiate it in public/js/router.js.

Create a distribution version

Kiwii provides two commands to build and run your webapp:

• npm run makedist,
• npm run dist,

But, before building a distribution version, you need to install the gulp module globally if it isn't done yet.

npm install -g [email protected]

When done, you can build your distribution version. Type:

• npm run makedist: it will create a folder _dist with all the files required for your webapp. Mainly one HTML file, one big CSS file and one big Javascript file. The two last files include an header copyright defined in tasks/.js.

• npm run dist: it creates an HTTP server listening on port 3000 and it launches your default browser with the URL http://localhost:3000. You should see your distribution webapp running in it.

Create a Mobile Hybrid Application

Now that your Kiwii webapp is ready, you can convert it to a Mobile Hybrid Application thanks to Cordova. If you aren't familiar with Cordova learn it first otherwise you won't understand what is described below.

First, install Cordova if it is not done yet. Type

npm install -g cordova

Then, create a new empty directory, open a terminal, go to this directory and type:

cordova create myapp

Go to myapp directory, throw away the folder www, copy _dist and rename it www.

Create a browser platform

Now we are going to test the Hybrid Application into the browser. We need to install the browser platform by typing the command (from myapp directory):

cordova platform add browser

Then run the Hybrid Application:

cordova run browser

Your Hybrid Application runs now at the address http://localhost:8000.

Create an IOS Application

Be aware, you can create an IOS app only from a Mac OS X platform with Xcode tools installed.

If you are on a Mac and you have Xcode installed, type the command:

cordova platform add ios

Add the plugins:

cordova plugin add cordova-plugin-device
cordova plugin add cordova-plugin-console
cordova plugin add cordova-plugin-geolocation
cordova plugin add cordova-plugin-statusbar

Build the IOS Application:

cordova build ios

Then go to myapp/platforms/ios/ and double click the file HelloCordova.xcodeproj. It launches Xcode. When the Xcode application is opened, select the menu Product -> Run. Xcode will open the IOS Simulator and you will see your IOS Hybrid Mobile App running!

Enjoy!

License

MIT.