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.
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
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.
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
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/
...
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
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
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
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