Create a new Component

In this task you'll be:

  • Installing the Squiz DXP Component Service local development tools
  • Creating a new component
  • Deploying & previewing your component in the Squiz DXP Component Service
  • Adding your new component to a Component Set
  • Testing the component in the Squiz CMS

For example purposes, we'll be creating a simple Bootstrap Popover.

Installing the Squiz DXP Component Service

The first step to using the Component Service is to install the local development environment so that you can develop and test components locally.

The Component Service uses a local CLI tool . The CLI tool is used to run a local development server and deploy your components to the DXP. Install the CLI tool using Node Package Manager (NPM).

Prerequisites

Please check to ensure you have following software installed or available on your computer

Squiz DXP Component Service Prerequisites

Let's get going...

  1. Execute the following installation command
npm install --global @squiz/dxp-cli-next
  1. Create a new local folder for your component
  2. Ensure that your Command Prompt is starting in the folder you just created
  3. Run the following command
dxp-next cmp init ./

You should now be presented with a series of questions:

If you are creating the example Bootstrap Popover, use these values, otherwise create your own.

  • What is the component name?
    cs-popover
  • What is the component displayName?
    Popover
  • What is the component description?
    Popover or tooltip to appear over HTML button
  • What is the component namespace?
    YOURNAME-components
    Change YOURNAME to your First Name

Open your code editor of choice and you should now see the following files have been created:

Component Service New Project

Further Reading

Check out the documentation for further information about the file structure

Squiz DXP Component Service File Structure

Updating the preview

For local development purposes let's include Bootstrap into our preview.html

  1. Open previews/preview.html
  2. Copy the following CSS link tag
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN" crossorigin="anonymous">
  1. Paste this into preview.html, directly above the close </head> tag (line 5)
  2. Copy the following Javascript script tag
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js"></script>
  1. Paste this into preview.html, directly above the close </body> tag (line 9)
  2. Save preview.html

Creating editable component fields

As this is a new component there are currently no 'input' fields.

To create a basic Popover, we will require:

  • Botton Text
  • Popover Heading
  • Popover  Content
  1. Open manifest.json
  2. Copy the following code
      "input": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "popHeading": {
            "type": "string",
            "title": "Popover Heading"
          },
          "popContent": {
            "type": "string",
            "title": "Popover Content"
          },
          "popBtnText": {
            "type": "string",
            "title": "Popover Button Text"
          }
        },
        "required": ["popHeading", "popContent", "popBtnText"]
      },
  1. Replace line 20 ("input": {},) with the code copied above
    Remove any blank lines created by pasting the code

Further Reading

Check out the documentation for further information about the Input Field Types available

Squiz DXP Component Service Input Field Types

Icons

The Squiz DXP Component Service uses the icon set from Material UI.

In line 9 of manifest.json you'll see an object called "icon" that has 2 properties ("id & "color")

To make your new component have it's own unique icon, or to include a common colour scheme for your Component Set you can alter the following:

Change the Icon

  • Open Material UI Icons and search for an appropiate icon (e.g. comment)
  • Copy the 'Ligature' name (comment_bank)
  • Replace the current Icon ID value (fiber_new) with your new Ligature value

Change the colour scheme

The "color" property can have one of two 'types': enum, or hex.

  • Change the current 'type' from enum to hex
  • Change the current 'value' from blue to a hex colour code (e.g. #2D2D2D).

Looking for some inspiration? Use the FlatUI colour picker

Creating example data

To test your new component locally, you'll need some example data.

  1. Open the file 'previews/example.data.json'
  2. Copy the following code
{
    "popHeading":"Test Popover Heading",
    "popContent":"The best place to start building brilliant experiences, fast!",
    "popBtnText":"Click to toggle Popover"
}
  1. Replace the current blank array inside 'previews/example.data.json' with the copied code

Creating the Component Template

  1. Open 'main.js'
    The main.js file is where we create the rendering for the component. In this example we have kept everything very simple, but you can use any templating framework such as Handlebars. The Component Service also allows you to use any Javascript Library such as ReactJS, VueJS
    The current function returns a simple Hello World statement
  2. Copy the following code
  return `
    <button type="button" class="btn btn-lg btn-success" data-bs-toggle="popover" data-bs-title="${input.popHeading}" data-bs-content="${input.popContent}">
      ${input.popBtnText}
    </button>
  `
  1. Replace the current return in main.js (line 2)

Updating client side javascript

Your newly created component can also have client side javascript automatically deployed and rendered within any page that uses your component.

  1. Open  static/default.js
  2. Copy the following code
document.addEventListener('DOMContentLoaded', () => {
    const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]');
    const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl));
});
  1. Paste the copied code into static/default.js

Test your component locally

  1. Ensure all files are saved
  2. Making sure your command prompt is in your local folder, run the following command
dxp-next cmp dev ./

Deploying your component

  1. Ensure that the Command task for testing your component locally is stopped
  2. Log into your DXP Component Service instance by running this command