diff --git a/README.md b/README.md index 4089054..eec0c98 100644 --- a/README.md +++ b/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). diff --git a/app/index.js b/app/index.js index 51e5646..fe5ecde 100644 --- a/app/index.js +++ b/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 } ); diff --git a/app/templates/README.md b/app/templates/README.md index f4fd284..e09a3ca 100644 --- a/app/templates/README.md +++ b/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 ```` -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: ```` @@ -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/) diff --git a/app/templates/_package.json b/app/templates/_package.json index 98b5695..35f43f8 100644 --- a/app/templates/_package.json +++ b/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" }, diff --git a/app/templates/gulpfile.js b/app/templates/gulpfile.js index 6750ce7..e8b6d8a 100644 --- a/app/templates/gulpfile.js +++ b/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(); diff --git a/screenshot.png b/screenshot.png new file mode 100644 index 0000000..7aea0d2 Binary files /dev/null and b/screenshot.png differ