generator-cui-portlet

Starting point for CUI based liferay portlets.

Installation

Prerequisites

1. Node and npm - https://nodejs.org/en/ (every step after this requires npm)
2. Bower - run npm install -g bower from your command line
3. Grunt cli - run npm install -g grunt-cli
4. Yeoman - run npm install -g yo

Get started

1. Install the cui-ng generator - npm install -g generator-cui-portlet
2. Make a new folder, this is where your project will live
3. Open a command line on that folder and run yo cui-portlet
4. You will be asked a few questions. Don't worry if you make a mistake, you can always start over (by deleting everything in that new folder and re-doing step 3) or just change things later.
5. Copy the appConfig-example.json file into another file with the name appConfig.json, with the required customizations.

How it works

This generator enables you to always get the newest features of cui-idm-b2x without risking overwriting any of your customizations. The way we do that is by splitting your project into 2 main folders - app and app-custom.

app/ will always have the most up to date b2x code - the common-templates and modules folders specifically. To update it, all you have to do is run yo cui-ng:update from your new project's root.

app-custom/ is where your custom code should live. The grunt copy task is setup so that any files in this folder that have the same path and file name as the ones in the app folder will be the ones that your app uses.

How to customize the app

In this example, say we want to change the way the applications are being shown in the 'My applications' screen. What you would do is:

1. Make an applications folder within app-custom/modules/
2. Inside that folder, make another folder called myApplications (mimicking the structure withing the app folder)
3. Create a file called myApplications.html in that folder. This file will always override the one in the app folder, no matter what updates come in the future.

NOTES:

1. Every time you want to reference an asset in app-custom, be it an image or html template, make sure to point to app instead of app-custom, since everything gets moved to the app folder during the build process
2. All html files in app-custom get concatenated and merged in with the rest of your js files, using ng-templates. This helps reduce the number of http requests. If for some reason you need an html file to carry over (maybe to open in a new tab), simply create a non-concat folder in app-custom and put your html files in there (remember to follow the first note when referencing them)

The benefits of this yeoman generator should be clear now: You can change pieces in a file by file fashion without compromising your ability to get updates to the other moving pieces.

How to run the app

• Running grunt from the root of the project will start browsersync which is a grunt task that starts an auto-reloaded browser page. Every time you make a change to any file in app-custom the page will refresh with the newest changes
• grunt build concatenates and minifies all the assets needed to run this app and puts it into a 'build/' folder. Note that if you add image assets or any sort of assets that is not javascript or html you will need to change the build task (The tasks/ folder does not get updated when you run yo cui-ng:update)
• grunt demo launches a browsersync window from the build folder, giving you an accurate representation of what the app will look like once it's deployed
• yo cui-portlet:build-portlets will take you through the process of generating portlets
• yo cui-portlet:demo will let you demo what a portlet will look like based on a certain config

Other features

• From your app-custom/modules/ folder you can run yo cui-ng:add-module to kick start a new module structure with a basic state configuration.
• Likewise, from within a nested module folder (for example, app-custom/modules/applications/myApplications/) you can kick start a new feature by running yo cui-ng:add-controller. This will create a new controller attached to the applications module and, optionally, a new html template file that matches the name of the controller.

License

Copyright (c) 2015 Covisint Corporation. All Rights Reserved.