Liferay-Instant-Deploy-Theme-Changes-Gulp-Script: A JavaScript repository from emiloberg

#Liferay Instant Deploy Theme Changes Gulp Script

This small Gulp script will monitor your source code theme folder and when a file is changed it will inject those changes into the server, recompile the scss and LiveReload your browser.

Demonstration on Liferay dev.life Sessions

What this script does

1. Instantly inject those theme changes into the server.

This is done by by copying the changed files to the Liferay server (tomcat/webapps/your-theme).

Out of the box, Liferay listens to changes in the webapps folder and the changes will be visible as soon as you reload your browser. However, if you edit the (s)css, you don't even need to reload the browser - see third point below.

2. Makes sure that the scss is recompiled into a css file if needed.

If you edit a scss file, the scss needs to be preprocessed and a css file needs to be created. Liferay will do this as well. However which scss file that file is imported in (and therefor which scss if you edit a scss partial, Liferay is not smart enough to understand file needs to be preprocessed.

When a scss partial file is changed, this script will add a timestamp comment in the entry point scss file (the scss file which imports the changed file)

As the entry point scss file is changed, Liferay will pick up on this and re-preprocess the file and create a css file.

3. LiveReload. If the scss is changed, the browser is updated instantly - without need to reloading the page.

For LiveReload to work, you need to install a small browser plugin for Chrome, Firefox or Safari or add a javascript snippet to your html. Browser plugin is prefered as you don't have to remove it before going live.

###Installation

Make sure you have Node.js installed. Run node -v to get current installed version if unsure.
Make sure you have Gulp installed. Run gulp -v to get current installed version if unsure. If not install, run npm install -g gulp to install.
cd to monator-liferay-instant-deploy-theme-tool directory
run npm install to download all dependenciese.
Open Gulpfile.js in your favourite text editor and edit the paths (see below).
run Gulp to start watching for files. Leave that terminal running as long as you want the app to be active.
Enable LiveReload in your browser if you want LiveReload. In Chrome, you do this by clicking on the LiveReload icon next to your url bar.

###Settings Open Gulpfile.js for editing.

First, you need to configure 2 folders to watch for changes:

themeSource - your theme root folder, most likely what you have version controlled.
partialsSource - the path to your scss partials.

In both cases you want to define a Glob using the minimatch syntax.

Common used syntax:

*  - matches any characters but slash (/).
** - matches any characters including slash (/). Meaning, recursively include subfolder(s), if any.
[^#]*[^~] - - matches any character but slash (/), and also not files with `#` as the first character or `~` as its last character.

Example: Matching all files in webapp its subdirectories.

themeSource: '/code/my-project/my-theme/src/main/webapp/**'

Example: Matching all files begining with an underscore (_) and ending with .scss, in a subdirectory to partials.

partialsSource: '/code/my-project/my-theme/src/main/webapp/css/partials/**/_*.scss'

Example: Matching all files but not temporary files created by your editor, which names either start with # and/or end with ~. Example matching

themeSource: '/code/my-project/my-theme/src/main/**/[^#]*[^~]'

Then you need to configure:

themeServer - the theme root folder on the server (tomcat/webapps/your-theme).
entryPointSource - the path to your entry point css file (the css file which imports your scss partials).
entryPointFolderServer - the folder path on the server where theentryPointSource is placed (on the server).

###Problem Solving

You're getting errors in your Liferay log.

If you're getting an error, like Caused by: java.util.concurrent.ExecutionException: org.jruby.embed.EvalFailedException this is most probbly because of a timing problem where Liferay tries to recompile the SCSS before the changed files are copied to your server. Fix by editing the gulpfile.js and increase var timingDelay = 0;. Try a value around 100 (milliseconds).

#####Script crashing due to temporary files created by your editor. Change your Glob pattern to exclude those temporary files. Usually the file names of temporary files start with # or end with ~. See the example a few lines up in this readme.

#####Nothing happening when saving a file First. Make sure your paths are correct.

Second. This script works by checking timestamps. If a source code file has a newer timestamp then one on the server - it's copied to the server. For this to work, you need to have the timezone correct on your server.

Liferay has GMT as default Timezone, this can be modified by editing tomcat/bin/setenv.sh and changing the GMT to e.g. GMT+2.

Duser.timezone=GMT+2

You may also cd into ... /tomcat/webapps/your-theme/ and run

find . -exec touch {} \;

to recursively "touch" all theme files which will update their timestamp.

emiloberg/Liferay-Instant-Deploy-Theme-Changes-Gulp-Script

Demonstration on Liferay dev.life Sessions

What this script does

You're getting errors in your Liferay log.