Skip to main content

FE Developors Guides

Markup

Building your site using the HTML Markup is straightforward and easy.

Getting Started with Markup​

Building your site using the HTML Markup is straightforward and easy. Using the Forge-ui markup keeps your page up to date with the Refinitiv UX guidelines without you having to re-develop it yourself. It also provides the common interactivity you'd need

Setup the page​

To get started you need to set up your sites environment. Simply add the Forge-ui main.css file to your document's <head>.

<head>
  <link href="https://refinitiv-forge-ui-VERSION.now.sh/bundles/main.css" rel="stylesheet">
</head>

Replace the VERSION text the above example with the version you wish to consume, seperated with dashes. For example if you are using version v29.3.0 the URL would be: https://refinitiv-forge-ui-v29-3-0.now.sh/bundles/main.css

Use the Markup​

All of our components are documented under the components menu in the design system website. Firstly make sure you are on the correct version of the design system for the version of the bundles you are consuming.

When you have found the UI Component you want to use you'll find the default Markup under the Markup Tab.

For example our DateTime Component provides the following Markup:

<time datetime="2016-03-02 13:57">March 2, 2016</time>

You can then copy that markup, with the button in the markup preview and paste it into the body of your page. Your page will then look something like this:

<head>
  <link href="https://refinitiv-forge-ui-VERISON.now.sh/bundles/main.css" rel="stylesheet">
</head>
<body>
  <time datetime="2016-03-02 13:57">March 2, 2016</time>
</body>

Adding Interactivity with Forge-ui Bundles​

You may ask how to add interactivity to the HTML Markup. The preffered method is to use our Forge-ui Bundles. The Forge-ui Bundles include common interactivity for the components that require it.

Our bundle works by scanning the DOM for markup-containers that contain components with a data-rehydatable data-attribute. We then dynamically import the smaller bundle required for that component and apply the Javascript. This process is called Rehydration.

Setup the page​

You'll need to add our bundle to your page. Just before the closing body tag, add the following: <script src="https://refinitiv-Forge-ui-VERSION.now.sh/bundles/main.js"></script> The same versioning information applies as per adding the CSS. Your base page template would look then look similar to this:

<head>
  <link href="https://refinitiv-forge-ui-VERISON.now.sh/bundles/main.css" rel="stylesheet">
</head>
<body>
  <script src="https://refinitiv-forge-ui-VERSION.now.sh/bundles/main.js"></script>
</body>

Currently CDN linking at the page level is the only supported way to bring in our JS and CSS bundles. There are a number of reasons for this. Find out more in our "How our bundles work" guide.

WARNING: Don't attempt to use the Forge-ui bundles by serving them yourselves. This is not currently supported.

data-attributes​

Data attributes are used by our components to provide the initial inputs to the Javascript code. These data-attributes are essentially arguments for functions that return the desired UI. Any component that has a data-attribute of data-rehydratable can be bootstrapped by our bundles dynamically.

Read more about a components specific data-attributes on the component specific pages.

Markup Containers​

Although a component requires a data-rehydratable in order for our Javascript bundles to attach their interactivity. In order to be efficent they also required to be within a markup container. A markup container highlights areas of the DOM that we want to attach the Forge-ui logic to.

A markup container is just a div with the data-react-from-markup-container data-attribute: <div data-react-from-markup-container="true">

All data-rehydratable components must be contained within a data-react-from-markup-container however markup containers must never be nested within themselves. The best practice is to add this as close to the leaf components as possible.

To achieve this in AEM place data-react-from-markup-container attributes at the template level only.

Forge-ui Bundles Summary​

You need to add the CDN link to the bundles to your page to have access to Forge-ui interactivity Dynamic components require both a data-rehydratable data-attribute and to be within a markup-container.

Adding interactivity without Forge-ui Bundles​

If the Forge-ui Javascript bundles don't provide the interactivity that you require, you can attach your own interactivity to the Markup however you see fit. You could use standard Javascript or even jQuery.

Remember that by adding your own interactivity you are taking on the maintenance burden. We provide no support for your custom interactivity. We suggest you contact the Forge-ui team to discuss your requirements, there may be an opporuntity for us to provide that interactivity for you.

Prior to adding your own interactivity you must opt out of the Forge-ui interactivity for that component.

Opting out of Forge-ui interactivity​

As per the previous section, a rehyratable component requires both a data-rehydratable data-attribute and to be within a markup-container. If you wish to add your own logic to a component. You have to remove one or both of these. The component will then not be rehydrated with our Javascript logic.

WARNING: Don't attach your own interactivity to a rehydrated component, it will not work properly. You MUST opt out of rehydration if you are to use your own interactivity.

Build your interactivity​

Because you are not rehydrating that component you can hook into that markup however you see fit. We'd suggest adding data-attributes for your JS to hook into the markup.

You can then ship your Javascript to the browser however you see fit.