Adding a unique identifier for your component

The C3 AI UI Framework allows its JSON components to be wrapped with a unique identifier. This document will go over how to enable this as well as examples of how to use this for styling and testing.

Copy link to this section

Enable wrapWithMetadataId

Every instance of UiSdlComponent has the option for wrapWithMetadataId, which is a boolean option to create a div around the component with a custom class name from the component's ID.

For example, let's take ExampleModule.MyGrid:

// ExampleModule.MyGrid.json

{
  "type": "UiSdlConnected<UiSdlDataGrid>",
  "component": {
    "wrapWithMetadataId": true,
    "dataSpec": {
      ...
    }
  }
}

This will result in a UiSdlDataGrid that is wrapped in an extra div with the class c3-metadata-id-examplemodule-mygrid.

Copy link to this section

Using metadataId for styling

One use for UiSdlComponent#wrapWithMetadataId is custom styling. Oftentimes, there will be uses where you may want one instance of a component to have unique styling without affecting any other components. For example, imagine a UiSdlDataGrid with ID ExampleModule.MyGrid that you would like to have a different background color to show more contrast from the layer below. In this case, you can add the following to your css/scss file:

.c3-metadata-id-examplemodule-mygrid {
  .c3-card {
    background: #dddddd
  }
}

For more information about overriding styles, you can see this document.

Copy link to this section

Using metadataId for testing

Another use case for unique identifiers is testing. When testing, we often want to be able to interact with specific components on the page. Normally this can be done by signifying where the component is in the DOM compared to other components; however, this is rather frail since it will fall apart if the page layout changes.

To solve this, we can use UiSdlComponent#wrapWithMetadataId to be able to always refer to one component and just refer to certain parts of the component. For example, with the ExampleModule.MyGrid grid, we may have a test to click an action button.

// test_examplePage.js
LukeBrowser.runJasmine('test_examplePage.js', function (browser, filename) {
  describe('test_examplePage.js', function () {
    beforeAll(function () {
      this.client = LukeBrowser.init();
      this.client.goto('examplePage');
      this.originalNumRows = 10;
    });

    describe('click action button to add row', function () {
      it('should add row', function () {
        this.client.search('.c3-metadata-id-examplemodule-mygrid .c3-button-add-row').click();
        this.client.searchAll('.grid-row').size().assert('toEqual', this.originalNumRows + 1);
      });
    })
  })
});

Even if the layout of the page changes, this test will always be able to click the Add Row button of ExampleModule.MyGrid thanks to using UiSdlComponent#wrapWithMetadataId.