Documentation

Using the Fragments Toolkit

The Fragments Toolkit helps you develop and manage Fragments locally, using your favorite tools. Here you’ll use the toolkit to generate a Fragments Project with sample Fragments, deploy it, and add your own Fragments Collection to it.

Setting Up the Toolkit

The toolkit requires this software:

NPM and Yarn are package managers that you’ll use to install the the toolkit and modules it depends on.

Liferay’s setup_tutorial.sh script provides commands for setting up Yeoman, Yarn, and the toolkit. The script is available in the example ZIP file and all of our example JavaScript project ZIP files.

  1. Start with installing an NPM and Node.js via a Node.js LTS.

  2. Download and unzip the example JavaScript project ZIP file.

    curl https://learn.liferay.com/dxp/latest/en/site-building/developer-guide/developing-page-fragments/liferay-x2y6.zip -O
    
    unzip liferay-x2y6.zip
    
  3. Set up the Fragments Toolkit and its dependencies using the setup_tutorial.sh script.

    cd liferay-x2y6
    
    ./setup_tutorial.sh
    

Resolve all unmet requirements reported by the script and rerun the script until it reports that your environment is ready.

Create a Fragments Project

The Fragments Toolkit’s yo liferay-fragments command launches an interface for generating a Fragments Project.

Warning

Don’t nest Fragments projects. Make sure to create new Fragments projects in their own location, outside of any existing Fragments projects.

If you’re in the liferay-x2y6 project folder, exit it (e.g., cd ..).

Here’s how to generate a Fragments Project:

  1. Launch the project generator by executing the yo liferay-fragments command:

    yo liferay-fragments
    
  2. Name your project. For this example, accept the default project name by clicking enter.

    ? Project name (Sample Liferay Fragments)
    
  3. Indicate whether to add sample content. For this example, enter Yes.

    ? Add sample content? Yes
    Creating directory
       force .yo-rc.json
      create src/.gitkeep
      create .editorconfig
      create .gitignore
      create liferay-npm-bundler.config.js
      create package.json
      create README.md
    Adding sample content...
    Warning: some of these fragments are not compatible all
    portal versions, please check the generator documentation before using them:
    https://www.npmjs.com/package/generator-liferay-fragments#creating-new-fragments
    Running yarn...
    Done!
    You're ready to create fragments.
      create src/sample-collection/collection.json
      create src/sample-collection/sample-fragment/index.html
      create src/sample-collection/sample-fragment/main.js
      create src/sample-collection/sample-fragment/styles.css
      create src/sample-collection/sample-fragment/fragment.json
      create src/sample-collection/sample-fragment/configuration.json
      create src/sample-collection/sample-fragment-with-new-editables/index.html
      create src/sample-collection/sample-fragment-with-new-editables/main.js
      create src/sample-collection/sample-fragment-with-new-editables/styles.css
      create src/sample-collection/sample-fragment-with-new-editables/fragment.json
      create src/sample-collection/sample-fragment-with-new-editables/configuration.json
      create src/sample-collection/sample-fragment-with-react/index.html
      create src/sample-collection/sample-fragment-with-react/main.js
      create src/sample-collection/sample-fragment-with-react/styles.css
      create src/sample-collection/sample-fragment-with-react/fragment.json
      create src/sample-collection/sample-fragment-with-react/configuration.json
    

Congratulations on generating your Fragments Project!

The generator creates each project in a folder derived from the project name. For example, since you named the project Sample Liferay Fragments, the generator created a project folder called sample-liferay-fragments.

Import the Sample Collection

Import the sample Fragment Collection to Liferay to view the Fragments:

  1. Run the command below to start the Docker container:

    docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.1-ga2
    
  2. Import the Fragment Collection to your Liferay instance invoking the yarn run import command in your sample-liferay-fragments project folder. Alternatively, you can import the Fragment Collection manually.

    yarn run import
    yarn run v1.22.10
    warning package.json: No license field
    $ yo liferay-fragments:import
    ? Liferay host & port http://localhost:8080
    ? Username [email protected]
    ? Password [hidden]
    Checking connection...
    Connection successful
    
    ? Company ID liferay.com
    ? Group ID Liferay DXP
    Building project...
    Importing project...
    Project imported
        force .yo-rc.json
        force ../../.yo-rc-global.json
    Done in 21.43s.
    
  3. Verify that the Fragment Collection is available. Point your browser to https://localhost:8080, and under the Site Menu on the left side of the screen, go to DesignFragments. The Collection appears in the Collection list.

    The Collection is available.

    Note

    For Liferay DXP 7.1 and 7.2, instead navigate to SiteSite BuilderPage Fragments under the Product Menu to get to the Fragments page.

  4. Select a Fragment to view it in the Fragments Editor.

    Here is the sample Fragment with React.

Great! You successfully deployed a Fragment Collection.

Collection Format Overview

Fragment Collections use this project structure:

  • collection.json: a text file that describes the Collection.

    {
        "description": "Optional description",
        "name": "Collection name"
    }
    
  • language.properties (optional): language keys defined for the Collection.

  • [fragment-name]/: a folder containing all of the files for a Fragment.

    • configuration.json(optional): a JSON file that defines the Fragment’s configuration. See Adding Configuration Options to Fragments for more information.

    • fragment.json: a text file that describes the Fragment.

      {
          "cssPath": "styles.css",
          "configurationPath": "configuration.json",
          "htmlPath": "index.html",
          "jsPath": "main.js",
          "name": "Fragment name",
          "type": "[component|react]"
      }
      

      Update the *Path properties with the names of your CSS, configuration, HTML, and JavaScript files.

    • index.html: the HTML source for the Fragment.

    • main.js: the JavaScript source for the Fragment.

    • styles.css: the CSS source for the Fragment.

  • resources/ (optional): a folder containing any additional images or files the Fragments need. See Including Default Resources in Fragments for more information.

The Fragments Toolkit facilitates creating Fragment Collections.

Add a New Collection and Fragment

Create a Fragment Collection in your existing project with the yarn run add-collection command and answer the prompts with your Collection’s name and an optional description:

yarn run add-collection

> yo liferay-fragments:collection

? Collection name (required) My Collection
? Collection description (optional) This is my new Fragment Collection.
   create src/my-collection/collection.json

Resulting collection.json file:

{
    "description": "This is my new Fragment Collection.",
    "name": "My Collection"
}

Create a New Fragment

The add-fragment command generates a Fragment per your input.

  1. Run the add-fragment command.

    yarn run add-fragment
    

    The CLI starts the process:

    > yo liferay-fragments:fragment
    
  2. Name your Fragment.

    ? Fragment name (required) My Jumbotron
    
  3. Choose whether to use React or another JavaScript framework. React requires Liferay 7.3+. For this tutorial, please decline using React.

    ? Use React (or other JS framework)? No
    
  4. Use the new editable element syntax for Liferay 7.3+.

    ? Use new data-lfr editable syntax? Yes
    

    Note

    If you accepted using React in your fragment, the toolkit assumes you’re on Liferay 7.3+ and configures the new editable element syntax.

    Note

    Please see Fragment-Specific Tags for more information on Liferay’s editable data syntax.

  5. Select the Collection you just created (My Collection).

    ? Choose a collection (my-collection)
       create src/my-collection/my-jumbotron/index.html
       create src/my-collection/my-jumbotron/main.js
       create src/my-collection/my-jumbotron/styles.css
       create src/my-collection/my-jumbotron/fragment.json
       create src/my-collection/my-jumbotron/configuration.json
    

    Note

    The fragment.json defines the paths to the Fragment’s CSS, HTML, and JavaScript. If you change any of these file names, update their paths in the fragment.json.

Here is the Fragment’s index.html:

<div class="my-jumbotron">
    <h1 data-lfr-editable-id="title" data-lfr-editable-type="text">
        My Jumbotron
    </h1>
</div>

The Fragment HTML uses the new data-lfr editable syntax.

Edit Your Fragment

Modify any part of your Fragment.

For example, you can build off of the above HTML and use Clay’s Bootstrap-based components to create Fragment with an attention-getting headline and description, as demonstrated in this index.html:

<div class="component-my-jumbotron">
    <div class="jumbotron">
        <h1
            class="display-4"
            data-lfr-editable-id="01-title"
            data-lfr-editable-type="rich-text"
        >
            Editable Jumbotron Headline
        </h1>

        <p
            class="lead"
            data-lfr-editable-id="02-lead"
            data-lfr-editable-type="rich-text"
        >
            Edit this text to call extra attention to featured content or information.
        </p>

        <hr />

        <p
            data-lfr-editable-id="03-text"
            data-lfr-editable-type="rich-text"
        >
            Edit this text to provide more information.
        </p>

        <a
            class="btn btn-primary btn-lg"
            data-lfr-editable-id="04-label"
            data-lfr-editable-type="link"
            href="#"
        >
            Editable Link
        </a>
    </div>
</div>

Note

If you are using Liferay 7.2 or below, remove the data-lfr-editable-[id|type] attributes and wrap the content elements in lfr-editable elements as described in Fragment-Specific Tags.

The first div element’s class="component-my-jumbotron" attribute attempts to uniquely identify this Fragment on a page.

Tip

In your Fragment’s HTML file, use the main wrapper element (the <div> in the example above) to uniquely identify the Fragment so it doesn’t conflict with other components on a page.

Next the <div class="jumbotron"/> element wraps the content, applying Bootstrap’s jumbotron component. This component makes the content stand out. Here are the content elements:

  • <h1 class="display-4" ...>Editable Jumbotron ... creates the Fragment’s heading. It uses Bootstrap’s display-4 size style. The data-lfr-editable- attributes make the heading text editable. The data-lfr-editable-id="03-text" attribute identifies the element and the data-lfr-editable-type="rich-text" attribute declares the content type.

  • <p class="lead" ...>Edit this text ... is the lead body text distinguished by Clay’s lead style component. The data-lfr-editable- attributes make the paragraph editable.

  • The <hr/> and next <p ... elements produce a horizontal rule and another editable paragraph, respectively.

  • <a class="btn btn-primary btn-lg" ... specifies a modifiable link. The btn-primary class styles it as a main button and btn-lg makes it large. The href="#" attribute takes the user to the top of the page when the link is clicked. The data-lfr-editable-type="link" attribute makes the link editable.

You can also include resources in your Fragments. See Including Default Resources in Fragments for more information.

Note

The Fragment and configuration object are passed in as arguments in JavaScript and are available as fragmentElement and configuration parameters, respectively.

Import Your New Fragment

You can import your new Fragment as you did the original example Fragment:

  1. Run the import command and provide your credentials:

    yarn run import
    
  2. Verify that the new Fragment Collection is available. Point your browser to https://localhost:8080, and under the Site Menu on the left side of the screen, go to DesignFragments. The Collection appears in the Collection list.

The Collection is available.

Great! Now you know how to use the Fragments Toolkit to create and manage Fragments. See the Fragments Toolkit Command Reference for more toolkit command information.