Liferay Fragments CLI

This is a CLI for developing fragments for Liferay DXP. It allows

generating fragments from scratch
exporting them from a Liferay instance
importing them into a Liferay instance

It also supports developing with your preferred desktop tools, while the CLI watches your changes and sends them to a Liferay instance, so that you can try them in your browser immediately.

Requirements

NodeJS 8+
NPM 6+
Yeoman 2+

Installation

First, install Yeoman and generator-liferay-fragments using npm (we assume you have pre-installed node.js).

npm install -g yo
npm install -g generator-liferay-fragments

The first step is always to generate a new project. You must do this even if you will be exporting the fragments from a Liferay instance:

yo liferay-fragments

This command will guide you through a project creation and will ask you some simple questions. Then you can just cd to this new project and start working.

cd my-new-fragments-project

Usage

Once you've created your project, there are several npm scripts that allow you to create fragments and fragment collections, export fragments from a Liferay instance, and manage your existing fragments.

Creating New Fragments

Fragments are always grouped inside collections. To create a collection, run

npm run add-collection

You can create as many collections as desired.

Once a collection has been created, you can add as many fragments as desired inside by running

npm run add-fragment

Fragments Directory Structure

Collections and fragments must follow a specific (although simple) directory structure so that they can be imported into a Liferay instance. The information about each collection and fragment is stored inside JSON files, and you can change them manually.

This is a sample directory structure with two collections and two fragments within the first collection:

src/
- collection-a/
  - collection.json
  - fragment-1/
    - fragment.json
    - index.html
    - styles.css
    - main.js
  - fragment-2/
    ...
- collection-b/
  ...

Exporting fragments from a Liferay instance

Instead of creating fragments from scratch, it's also possible to export them from an existing Liferay instance. This is very useful to continue the development of fragments with any desired desktop tool such as VSCode, Atom, Sublime, etc. It also facilitates keeping the code of the fragments under version control and using any desired development tool (e.g., SaSS, babel, etc.).

To export the fragments from an existing Liferay instance, run the export command. It will guide you through the information that you need to connect to Liferay and choose among its sites:

npm run export

Importing fragments into a Liferay instance

After you've created your own fragments or after you've made modifications to exported fragments, you can import them into a Liferay instance by running:

npm run import

You can also ask the Fragments CLI to watch for further changes and import them automatically. This is very useful during development time, so that you can work with your preferred editor and the browser to check the changes automatically imported into Liferay.

npm run import:watch

Previewing fragments with a Liferay Server

Warning: this functionality is only available with Liferay 7.2 Fixpack 1 or later. You also need to include the marketplace Oauth 2 Plugin in your Liferay Portal.

Sometimes you may want to see how a fragment will look once it has been imported to Liferay. With the preview command, you can specify a Liferay Server and see your fragments rendered without importing them. Moreover, this command also autoreloads features, so you can make changes in your fragments rapidly.

npm run preview

Packaging fragments for distribution

After you have finished the development of fragments, they can be distributed as a ZIP file, which can be imported inside any Liferay site. To prepare the ZIP file, run

npm run compress

tsubasahomma / generator-liferay-fragments