Skip to content

allenduy/394P1

BranchesTags

Repository files navigation

generator-m

NPM version Coverage Status Build Status Dependency Status Download Month

Why you need it

Build mobile Cordova/PhoneGap apps quickly with the tools you love: Yeoman, Gulp, Bower, AngularJS, Ionic & of course Cordova. All in one sexy generator.

What's in the box

We use:

Working nicely with the following technology stack:

Install

Prerequisites

Generator

npm install -g generator-m

Generate App

create new directory - and cd into it.

mkdir myApp && cd $_

run the generator - and follow the instructions

yo m

IMPORTANT: Cordova needs an empty directory to work. Please run any other setup (e.g. git init) after running yo m.

Get started

gulp watch

Prepares everything for development and opens your default browser. Get ready to start coding!

gulp watch

Livereloads your application when changing/adding/deleting files to immediately reflect the changes you make. If you don't want this task to open your browser, just add the --no-open option and navigate to http://localhost:9000 yourself. For your convenience any occurring jscs, jshint or jsonlint errors will be presented to you on every livereload.

File structure

└──  app/           - your application folder
│   └──  bower_components/    - local installation of bower packages
│   └──  main/                - ---main module---
│   │   ├──  assets/          - assets: fonts, images, translation, etc... goes here
│   │   ├──  constants/       - angular constants
│   │   ├──  controllers/     - angular controllers
│   │   ├──  directives/      - angular directives
│   │   ├──  filters/         - angular filters
│   │   ├──  services/        - angular services
│   │   ├──  styles/          - scss styles
│   │   ├──  templates/       - angular templates
│   │   └──  main.js          - angular module definition, routing etc...
│   └──  anotherModule/       - ---another  module---
│   │   ├──  ...
│   ├──  app.js               - application module, includes main module, ionic, ui-router etc ...
│   └──  index.html           - angular entry point, injects: app files, bower files, fonts,  ...
├──  gulp_tasks/    - gulp tasks
├──  hooks/         - cordova hooks
├──  nodes_modules/ - local installation of node modules
├──  platforms/     - cordova platforms
├──  plugins/       - corodova plugins
├──  www/           - your gulp build goes here, cordova starts building from here
├──  .bowerrc       - bower configuration
├──  .editorconfig  - editor configuration
├──  .gitattributes - git's attribute configuration
├──  .gitignore     - git's ignore configuration
├──  .jscsrc        - jscs configuration
├──  .jshintignore  - jshint ignore
├──  .jshintrc      - jshint configuration
├──  .travis.yml    - travis continuous integration configuration
├──  .yo-rc.json    - yeoman's .yo-rc.json
├──  bower.json     - bower dependencies
├──  config.xml     - cordova's config.xml
├──  gulpfile.js    - entry point to all gulp tasks
├──  jenkins.sh     - shell script for jenkins continuous integration 
├──  package.json   - node dependencies configuration
├──  README.md      - the generator's README.md

More gulp tasks

gulp --cordova 'run any command'

A local wrapper for cordova cli (allows to use different cordova CLI versions in different projects). For instance instead of running cordova plugins ls you'd write the following to list all the installed plugins:

gulp --cordova 'plugin ls'

Head over to the cordova cli documentation or their github page to learn how to use the cordova cli. Remember that when using generator-m you don't need to install cordova globally!

gulp --cordova 'build-related task'

If you run one of the following cordova commands: build <platform>, run <platform>, emulate <platform> or prepare <platform>, gulp build will build your app into the www folder, before cordova will take it from there. For instance if you want to test your app on your connected ios device, run:

gulp --cordova 'run ios' # runs gulp build, then cordova run ios

Sometimes you don't want gulp build to run every time before the cordova command is run. In that case simply add the --no-build option and gulp build will be skipped.

gulp watch-build

Builds into www, watches version in www and opens your browser. Good for debugging and testing your build!

gulp watch-build

Add the --no-build option and gulp build will be skipped. The --no-open options is available here as well, in case you don't want your browser to open automatically and would rather navigate to http://localhost:9000 yourself.

gulp build

Builds your angular app and moves it to the www folder. Usually you don't run this command directly, but it will be implicitly run by gulp watch-build and any build-related cordova tasks (as explained above).

gulp build

Note that the build will not complete if you have any jscs, jshint or jsonlint errors in your code! Sometimes it's necessary to let the build run anyway. Use the --force-build option to do so. The --minify option will minify javascript, css, html and images. These options will also work for all the build-related cordova tasks!

gulp environment

Handles your environments (dev, prod, and any other you'd like).

How does it work?

Your main module contains the two files env-dev.json and env-prod.json located under app/main/constants/. Any key value pair you define in those files will be copied into the Config.ENV constant located in app/main/constants/config-const.js. So when you're working on dev, all key value pairs from the main module's env-dev.json will be copied to your config-const.js. Simply inject the Config constant in any service or controller where you need to use it.

Choosing an environment

When you run gulp watch or gulp build it will default to the dev environment:

gulp watch                # defaults to --env=dev
gulp build                # so does this
gulp --cordova 'run ios'  # and any other command that uses gulp build

Alternatively you can run the following to switch to the prod environment

gulp watch --env=prod
gulp build --env=prod
gulp --cordova 'run ios' --env=prod

While you're running gulp watch you can even switch the environment you're currently working on without having to restart your watch task. Simply type:

gulp environment --env=<env>

Gulp will livereload with your new environment!

Creating a new environment

If you find yourself faced needing more than a dev and a prod environment simply create a new file: app/main/constants/dev-env5.json, fill it with the desired values and then run one the following:

gulp watch --env=env5
gulp build --env=env5
gulp environment --env=env5
Environments when using several modules

In case your project grows large and you have several modules in your project you will probably find yourself wanting to share environments across all modules. No problem. Every module you create has it's own Config constant located in app/module/constants/config-const.js. But only your main module contains the actual environments. The gulp tasks will automatically copy the environments to all of your modules' Config.ENV constants.

gulp config

Manages project configuration. Modifies cordova's config.xml

gulp config --setVersion=1.1.0
gulp config --setBuild=12 
gulp config --setBundle=com.new.bundle
gulp config --setName='hello world' # USE WITH CARE! (see below)
gulp config --setDescription='a small app to make the world a happy place'
gulp config --setAuthor='Your Name---your@mail.com---http://yourwebsite.com'

Important: When changing the name of your project, it may lead to problems with the platform projects. This can be avoided by re-adding your platforms and plugins: gulp cordova-install. Check out the full description of this command further down under the section Git integration.

Running on Windows

The generator should work just like on unix/mac except there's one difference, when running gulp --cordova tasks. They need doublequotes. So write this:

gulp --cordova "run ios" # will work on windows

instead of this:

gulp --cordova 'run ios' # won't work on windows

Sub-generators

yo m:module - creates a new module

  1. yo m:module <moduleName> - create a new module
  2. add your module to the app/app.js:
'use strict';
angular.module('myProject', [
  // your modules
  'main',
  '<newModuleName>'
]);
  1. navigate to http://127.0.0.1:9000/#/<module-name-in-snake-case> in your browser.
  2. Done! - see your new module in action!

yo m:others

The <moduleName> is optional and defaults to the main module when left blank

yo m:constant <constantName> <moduleName>
yo m:controller <controllerName> <moduleName>
yo m:directive <directiveName> <moduleName>
yo m:filter <filterName> <moduleName>
yo m:template <templateName> <moduleName>
yo m:service <serviceName> <moduleName>

If you have gulp watch running, gulp will automatically inject your new files into your application and they will be available right away.

Git integration

The generator provides a default set of configuration for git:

Leaving them as they are generated, you will allow git to exclude all of the 3rd party code from your project. Specifically this means:

  • no bower components
  • no node modules
  • no cordova platforms and plugins

After git clone

Since all these files are excluded from git you need to install all of them when you start with a fresh clone of your project. In order to do so, run the following commands in that order:

npm install # installs all node modules including cordova, gulp and all that
bower install # install all bower components including angular, ionic, ng-cordova, ...
gulp cordova-install # install all cordova platforms and plugins

gulp cordova-install

Both npm and bower keep track of the installed packages and their versions using the package.json and bower.json respectively. Unfortunately cordova does not provide a cordova install command and no cordova.json file to keep track of the installed platforms, plugins and their versions. We think it should, that's why we created an issue for that in the cordova project. We'll keep you updated!

For now you can run our custom gulp cordova-install which will install all platforms and plugins. Unfortunately, for now, with no guarantee of version. This means, that cordova will always install the latest versions. Sometimes, especially with plugins, this can lead to code incompatibilities.

cordova versions in .yo-rc.json

If you care a lot about the stability of your code (like we do), keep reading!

In order to be able to manage your cordova platform and plugin versions at all, we built in a little workaround. It's not great but it does it's duty until there's a better solution. For every platform and plugin you install with gulp --cordova you can add a version to the .yo-rc.json file. For instance, you'd install the splashscreen plugin and the android platform via:

gulp --cordova 'plugin add org.apache.cordova.splashscreen'
gulp --cordova 'platform add android'

Then you check their versions by running:

gulp --cordova 'plugin ls' # let's say splashscreen version is 1.0.0
gulp --cordova 'platform ls' # let's say android version is 3.6.4

Modify the .yo-rc.json to look something like this:

{
  "generator-m": {
    "answers": {
      // ...
      ],
      "platforms": [
        "ios", // will install newest version
        "android@3.6.4" // will install 3.6.4
      ],
      "plugins": [
        "org.apache.cordova.device", // will install newest version
        "org.apache.cordova.dialogs", // will install newest version
        "org.apache.cordova.splashscreen@1.0.0", // will install 1.0.0
      ]
    }
  }
}

Now running gulp cordova-install will install all the appropriate versions.

It's important to note that the versions you supply in .yo-rc.json do not take effect until you have manually installed the platforms and plugins with the respective gulp --cordova command.

Troubleshooting

If you're experiencing difficulties using the generator please refer to the Troubleshooting section in our wiki or create an issue!

Options for debugging and development

yo m --appName='App Name' # set appName via CLI
yo m --skip-welcome-message # skips welcome message
yo m --skip-sdk # skip adding cordova platforms and plugins (sdk-specific) for travis
yo m --skip-install # for debugging purposes, no npm and bower install
yo m --skip-prompts # for debugging purposes, run with predefined answers
yo m --ios-only # in conjunction with --skip-prompts
yo m --android-only # in conjunction with --skip-prompts
yo m --no-cordova # in conjunction with --skip-prompts, no platforms/plugins

Want to contribute?

Start by reading our:

  1. Mission Statement
  2. Contribution Guide

License

Code licensed under MIT. Docs under Apache 2. PhoneGap is a trademark of Adobe.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages