MiniGap
Minigap is a client-side javascript framework for PhoneGap
Disclaimer
This project is yet in a very early stage of development and is not complete.
This README is used as a specification of what it will be, even if part of it have been implemented already there is no guarantee that the source of this package code reflects or will reflect it in any way.
This disclaimer will go away with the first alpha release.
Istallation
npm install -g minigap
Setup a new application
minigap new myApp
This will create an initial application layout in myApp
folder that you can use to further develop and install development dependencies.
Then type
cd myApp
minigap start
And you can start to develop inside your browser. To use it along with PhoneGap you need to setup a new target.
Directory Structure
myApp/
lib/
minigap.js
www/
css/
app.css
js/
app.coffee (or app.js)
templates/
index.html
targets/
browser/
dev/
dist/
Building your app
Now that you are ready to create your application you would like to know how to build it.
Minigap builds soruces compiling javascript/coffeescript, templates and html files passing your source through a compiler able to preprocess files.
Preprocessor is used to concatenate files and perform conditional compilation of code using macros in a way similar to c/c++
preprocessor.
Preprocessing Macros
Preprocessing Macros are comments starting with =
eg.
Javascript
//= if development
...
//= end
Coffeescript
#= if development
…
#= end
HTML (sorry for spacings my markdown editor goes crazy with html comments)
< !--= if development -- >
...
< !--= end -- >
Preprocessing Directives
Inclusion
#= include <mylib.js>
Direct Output
#= print VALUE
Conditional compilation
#= if CONDITION
...
#= else if CONDITION
...
#= else
...
#= end
Condition Operators
- ! or not
- & or and
- || or or
- < or lt
- > or gt
- <= or lte
- >= or gte
- == or eq
- != or neq
Preprocessor environment
Minigap sets some preprocessor variables you can use as conditions.
When building for development the development
variable is set to true.
When building for production the production
variable is set to true.
When building for a specific target the target
variable is set to the target name.
So you can do things like this:
#= if development
console.log "debug: #{myVar}"
#= end
or this:
< !--= if development -- >
<script src="weinre_target_xyz.js"></script>
< !--= end -- >
or this:
#= if target == 'ios'
…
#= else if target == 'android'
...
#= end
Managing Targets
Phonegap can target different devices and architectures. Minigap would hopefully simplify the task of building the same app for different targets.
In order to do so original Phonegap projects are mirrored inside the minigap project tree. These mirrors are used for building development packages. Any time you want to release your code you can create production bundles from command line.
Production bundles are deployed back to their original locations.
Configuring targets
grunt.initConfig
# ..
minigap:
# ...
targets:
ios: '../myPhonegapIos'
android: '../myPhonegapAndroid'
# ...
Now that your targets is set up you should run the mirror
task that create copies of targets inside the directory tree.
grunt mirror
This command would create a mirror of any target inside yourApp/[target]
directories.
From now on you will use these directory for development. Any time you want to create production build, the application is copyied to its original target.
Development
Minigap is designed to speed-up PhoneGap development process. A typical downside of phonegap development against regoular browsers is that you have to recompile and re-launch simulator any time you change something in your code. This task can be very annoying and slow.
To overcome this problem minigap ships with a mini-server that once started serves your assets. This way any change to the source is immediately reflected in your Phonegap runtime.
To start the server just lauch the grunt start
task specifing the relative target.
minigap start [target]
This task will start the development server and watch for changes in your source so they are automatically rebuilt.
Also it will setup a WebSocket firing events on every rebuild. You can listen to it in order to refresh the page when code is updated.
Preprocessing
minigap dist ios
to get ready to distribute your app.
Client side framework
Controllers
MiniGap adapt tipical components of a mobile application to let you handle them all the same way.
MiniGap applications are event-driven
Minigap.controller
'app.start': ->
console.log "Application Started"
'/': ->
@requests [
path: '/top_events'
,
path: '/top_events'
params:
section: 'sport'
,
path: '/top_events'
params:
section: 'music'
],
(response) ->
@render 'templates/home', response
Default Events
Application
- 'app.started'
Router
- 'hashchange:scope' or just 'scope'
- 'submit:scope'
- 'before:scope'
- 'after:scope'
Origin
- 'origin.[name].requestSent'
- 'origin.[name].responseReceived'
Socket
- 'socket.[name].[evt]'
TemplateEngine
- 'template.[name].rendered'
Custom events
You can use app.emit()
to send custom events
Copyright (c) 2013 mcasimir
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.