Merge pull request #14 from psbrandt/browser-sync

🔃 Live reloading and more with Browsersync

README.md

@@ -7,7 +7,7 @@
 
 > [Yeoman](http://yeoman.io) generator that scaffolds an [OpenMRS Open Web App](https://wiki.openmrs.org/display/docs/Open+Web+Apps+Module)
 
-[![OpenMRS OWA Asciicast](https://asciinema.org/a/35039.png)](https://asciinema.org/a/35039?autoplay=1)
+[![OpenMRS OWA Asciicast](screenshot.png)](https://asciinema.org/a/38974?autoplay=1)
 
 ## Features
 
@@ -17,6 +17,7 @@ The following features are currently supported:
   - [x] Production build with [Gulp](http://gulpjs.com/)
   - [x] Local deploy with Gulp
   - [x] Package management with [Bower](http://bower.io/)
+  - [x] Live reload, interaction sync and more with [Browsersync](https://www.browsersync.io/)
 
 ## Getting Started
 
@@ -26,6 +27,7 @@ The following features are currently supported:
  - Run `yo openmrs-owa` to scaffold the Open Web App
  - Run `gulp` to build distributable zip file
  - Run `gulp deploy-local` to deploy directly to your local server
+ - Run `gulp watch` for live reloading and more
 
 ## Extending
 
@@ -55,8 +57,17 @@ Any files that you add manually must be added in the `app` directory.
 The generator will read the following environment variables and use their values as the default when generating a new Open Web App:
 
 - `OMRS_OWA_LOCAL_DIR`: The directory to use for local deployment
+
+> e.g. `/Users/pascal/Downloads/openmrs-standalone-2.3.1/appdata/owa`
+
 - `OMRS_OWA_GITHUB_ID`: Your GitHub username
 
+> e.g. `psbrandt`
+
+- `OMRS_OWA_BASE_URL`: The base URL of your local OpenMRS server
+
+> e.g. `http://localhost:8082/openmrs-standalone`
+
 ## Contribute
 
 See the [contributing docs](https://github.com/yeoman/yeoman/blob/master/contributing.md).

app/index.js

@@ -108,6 +108,23 @@ module.exports = generators.Base.extend({
         name: 'Enterprise',
         value: 'enterprise'
       }]
+    }, {
+      type: 'input',
+      name: 'appEntryPoint',
+      message: 'What URL will your app be served from?',
+      default: function(answers) {
+        var suffix = 'owa/' + answers.appName.toLowerCase().replace(/\s+/g, "") + '/index.html';
+
+        if(process.env.OMRS_OWA_BASE_URL) {
+          return process.env.OMRS_OWA_BASE_URL.endsWith(path.sep) ? process.env.OMRS_OWA_BASE_URL + suffix : process.env.OMRS_OWA_BASE_URL + path.sep + suffix;
+        } else {
+          if(answers.deployType == 'standalone') {
+            return 'http://localhost:8081/openmrs-standalone/' + suffix;
+          } else {
+            return 'http://localhost:8080/openmrs/' + suffix;
+          }
+        }
+      }
     }, {
       type: 'input',
       name: 'localDeployDirectory',
@@ -137,9 +154,9 @@ module.exports = generators.Base.extend({
       this.appId = answers.appName.toLowerCase().replace(/\s+/g, "");
       this.appName = answers.appName;
       this.appDesc = answers.appDesc;
-      this.includeOMRSJS = hasFeature('includeOMRSJS');
       this.includeJQuery = hasFeature('includeJQuery');
       this.includeAngular = hasFeature('includeAngular');
+      this.appEntryPoint = answers.appEntryPoint;
       this.localDeployDirectory = answers.localDeployDirectory;
       this.devName = answers.githubId;
       this.githubRep = answers.appRepo;
@@ -159,6 +176,7 @@ module.exports = generators.Base.extend({
           name: this.pkg.name,
           version: this.pkg.version,
           appId: this.appId,
+          appEntryPoint: this.appEntryPoint,
           localDeployDirectory: this.localDeployDirectory.endsWith(path.sep) ? this.localDeployDirectory : this.localDeployDirectory + path.sep
         }
       );
@@ -278,6 +296,7 @@ module.exports = generators.Base.extend({
         {
           appName: this.appName,
           appId: this.appId,
+          appEntryPoint: this.appEntryPoint,
           localDeployDirectory: this.localDeployDirectory
         }
       );

app/templates/README.md

@@ -6,15 +6,18 @@ This repository contains the <%= appName %> OpenMRS Open Web App.
 
 > Add a description of what your app does here.
 
-For further documentation about OpenMRS Open Web Apps see [the wiki page](https://wiki.openmrs.org/display/docs/Open+Web+Apps+Module).
+For further documentation about OpenMRS Open Web Apps see
+[the wiki page](https://wiki.openmrs.org/display/docs/Open+Web+Apps+Module).
 
 ## Development
 
 ### Production Build
 
-You will need NodeJS 4+ installed to do this. See the install instructions [here](https://nodejs.org/en/download/package-manager/).
+You will need NodeJS 4+ installed to do this. See the install instructions
+[here](https://nodejs.org/en/download/package-manager/).
 
-Once you have NodeJS installed, you need to install Gulp and Bower (first time only) as follows:
+Once you have NodeJS installed, you need to install Gulp and Bower (first time
+  only) as follows:
 ````
 npm install -g gulp bower
 ````
@@ -30,7 +33,8 @@ Build the distributable using [Gulp](http://gulpjs.com/) as follows:
 gulp
 ````
 
-This will create a file called `<%= appId %>.zip` file in the `dist` directory, which can be uploaded to the OpenMRS Open Web Apps module.
+This will create a file called `<%= appId %>.zip` file in the `dist` directory,
+which can be uploaded to the OpenMRS Open Web Apps module.
 
 ### Local Deploy
 
@@ -40,15 +44,35 @@ To deploy directly to your local Open Web Apps directory, run:
 gulp deploy-local
 ````
 
-This will build and deploy the app to the `<%= localDeployDirectory %>` directory. To change the deploy directory, edit the `LOCAL_OWA_FOLDER` entry in `config.json`. If this file
-does not exists, create one in the root directory that looks like:
+This will build and deploy the app to the `<%= localDeployDirectory %>`
+directory. To change the deploy directory, edit the `LOCAL_OWA_FOLDER` entry in
+`config.json`. If this file does not exists, create one in the root directory
+that looks like:
 
 ```js
 {
-  "LOCAL_OWA_FOLDER": "/path/to/your/owa/directory"
+  "LOCAL_OWA_FOLDER": "<%= localDeployDirectory %>"
 }
 ```
 
+### Live Reload
+
+To use [Browersync](https://www.browsersync.io/) to watch your files and reload
+the page, inject CSS or synchronize user actions across browser instances, you
+will need the `APP_ENTRY_POINT` entry in your `config.json` file:
+
+```js
+{
+  "LOCAL_OWA_FOLDER": "<%= localDeployDirectory %>",
+  "APP_ENTRY_POINT": "<%= appEntryPoint %>"
+}
+```
+Run Browsersync as follows:
+
+```
+gulp watch
+```
+
 ### Extending
 
 Install [Bower](http://bower.io/) packages dependencies as follows:
@@ -57,7 +81,8 @@ Install [Bower](http://bower.io/) packages dependencies as follows:
 bower install --save <package>
 ````
 
-Be sure to include the following in your `html` files at the position you want the Bower dependencies injected:
+Be sure to include the following in your `html` files at the position you want
+the Bower dependencies injected:
 
 ````
 <!-- bower:js -->
@@ -67,6 +92,16 @@ Do the same for your Bower stylesheet dependencies, but replace `js` with `css`.
 
 Any files that you add manually must be added in the `app` directory.
 
+### Troubleshooting
+
+##### [HTTP access control (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS)
+
+You may experience problems due to the `Access-Control-Allow-Origin` header not
+being set by OpenMRS. To fix this you'll need to enable Cross-Origin Resource
+Sharing in Tomcat.
+
+See instructions [here](http://enable-cors.org/server_tomcat.html) for Tomcat 7 and [here](https://www.dforge.net/2013/09/16/enabling-cors-on-apache-tomcat-6/) for Tomcat 6.
+
 ## License
 
 [MPL 2.0 w/ HD](http://openmrs.org/license/)

app/templates/_package.json

@@ -6,16 +6,18 @@
     "type": "git",
     "url": "<%= githubRepo %>"
   },
-  "dependencies": {
+  "dependencies": {},
+  "devDependencies": {
+    "browser-sync": "^2.11.1",
     "del": "^2.2.0",
     "gulp": "^3.9.0",
     "gulp-load-plugins": "^1.2.0",
     "gulp-util": "^3.0.7",
+    "gulp-watch": "^4.3.5",
     "gulp-zip": "^3.0.2",
     "main-bower-files": "^2.11.1",
     "wiredep": "^3.0.0"
   },
-  "devDependencies": {},
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

app/templates/gulpfile.js

@@ -19,6 +19,7 @@ var del = require('del');
 var mainBowerFiles = require('main-bower-files');
 var wiredep = require('wiredep').stream;
 var gutil = require('gulp-util');
+var browserSync = require('browser-sync').create();
 
 var plugins = gulpLoadPlugins();
 
@@ -28,29 +29,30 @@ var htmlGlob = ['app/**/*.html'];
 var resourcesGlob = ['app/**/*.{png,svg,jpg,gif}', 'app/**/*.{css,less}',
   'app/**/*.js', 'app/manifest.webapp', /* list extra resources here */ ];
 
-  var getConfig = function () {
-    var config;
-
-    try {
-      // look for config file
-      config = require('./config.json');
-    } catch (err) {
-      // create file with defaults if not found
-      config = {
-        'LOCAL_OWA_FOLDER': '<%= localDeployDirectory %>'
-      };
-
-      fs.writeFile('config.json', JSON.stringify(config), function(err) {
-      if(err) {
-          return gutil.log(err);
-      }
-        gutil.log("Default config file created");
-      });
+var getConfig = function () {
+  var config;
 
-    } finally {
-      return config;
+  try {
+    // look for config file
+    config = require('./config.json');
+  } catch (err) {
+    // create file with defaults if not found
+    config = {
+      'LOCAL_OWA_FOLDER': '<%= localDeployDirectory %>',
+      'APP_ENTRY_POINT': '<%= appEntryPoint %>'
+    };
+
+    fs.writeFile('config.json', JSON.stringify(config), function(err) {
+    if(err) {
+        return gutil.log(err);
     }
+      gutil.log("Default config file created");
+    });
+
+  } finally {
+    return config;
   }
+}
 
 gulp.task('copy-bower-packages', function() {
   try {
@@ -91,6 +93,28 @@ gulp.task('resources', function() {
     .pipe(gulp.dest('dist'));
 });
 
+gulp.task('browser-sync-inject-css', ['deploy-local'], function() {
+  return gulp.src('app/**/*.css').pipe(browserSync.stream());
+});
+
+gulp.task('browser-sync-reload', ['deploy-local'], function() {
+  return browserSync.reload();
+});
+
+gulp.task('watch', function() {
+  // forget about all the error checking for now
+  var config = require('./config.json');
+
+  browserSync.init({
+    proxy: {
+      target: config.APP_ENTRY_POINT
+    }
+  });
+
+  gulp.watch('app/**/*.css', ['browser-sync-inject-css']);
+  gulp.watch('app/**/*.{js,html}', ['browser-sync-reload']); // reload on JS or HTML changes
+});
+
 gulp.task('deploy-local', ['build'], function() {
   var config = getConfig();