Omneo Shapes - Developer Guide

Read our introduction to Omneo Shapes here.

Getting started

Shapes exists to bring mobile-responsive Omneo components into your websites or projects faster, more consistently and with blazing performance 🔥

At its core, this library solves the overhead of designing components, fetching Omneo data, sharing state between separate ui objects and caching API request responses.

Installing your first shape

Include Shapes library

Shapes is hosted on the Omneo CDN, so there is no need to save the code locally in your project. We recommend accessing shapes through the main https://cdn.omneo.io/shapes branch; this is the most up-to-date and stable branch. However if you wish to use a specific library version, this can be accessed at https://cdn.omneo.io/shapes/release/{version}

To include the library in your site, just add the following code to the <head>:

<script type="text/javascript" src="https://cdn.omneo.io/shapes/omneo.shapes.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.omneo.io/shapes/omneo.shapes.css">

Add Shapes configuration

Once the JS and CSS files have been included, Shapes must be initialised with the API URL, API KEY (optional) and Omneo Profile Id. The following javascript snippet can be included in the <head> or <body>:

<script>
    omneoShapes({
        url: {{api_url}},
        token: {{api_token}},
        profileId: {{profile_id}}
    })
</script>

Check out Implementation for ideas on different ways to include Shapes in your project.

Adapting Shapes for your brand

Along with API and profile details, the omneoShapes() init function can take a hex value for tintColor, textColor and textColorSecondary, as well as a string value for fontFamily(). If a value of false is set, Shapes will attempt to use the global CSS properties for these values;

omneoShapes({
    url: {{api_url}},
    token: {{api_token}},
    profileId: {{profile_id}},
    tintColor: "#1680dc",
    textColor: "#333",
    textColorSecondary: "#999",
    fontFamily: false // Will default to body font family 
})

Add a Shape to the page

Each Shape is a self-rendering div, that can reside anywhere on a page - provided the div isn't programatically added or removed. All that a Shape requires is the data-omneo-shape attribute and the Shape handle.

<div data-omneo-shape="RewardBalance"></div>

The Shape div can include class names, ids and other regular HTML DOM properties:

<div data-omneo-shape="RewardBalance" id="rewards" class="balance"></div>

Shape settings

As well as regular HTML properties, some Shapes can accept a number of setting values to customise their logic or display. These settings are configured using a data-attribute, much like the data-omneo-shape value. Details of the settings available to each shape are available on the Shape list:

<div 
    data-omneo-shape="TransactionList"
    data-title="My Orders"
    data-auto-hide-pagination="false"
></div>

Setting types

While all data attribtues only capture string data, Shapes parses the values through a number of checks to achieve support for boolean, float, integer, string and JSON variables. A value of true or false will be parsed as a boolean, any number value will be passed as a float or integer accordingly and a string be passed through as normal.

Some shapes require a settings configuration in JSON format. To achieve this, just prepend the JSON string with "JSON" as below:

<div data-setting-handle='JSON {"test":"Don`t forget to read the notes below"}'>

Refer to the CommsGroup Shape for an example of a JSON setting in action.

Note

To ensure compatibiltiy, the data-attribute value must be wrapped in single quotes 'instead of the usual double quotes "

Single quotes in the payload

Where you would use a single quote, in the JSON, replace with a backtick (`). These will be converted to single quotes when the value is parsed

How It Works

The Shapes initialiser watches for the DOMContentLoaded event then triggers the following events:

  • Find all Omneo Shapes on the current page
  • Consolodate Omneo API requests used by all Shapes
  • Render Shapes in loading state
  • Fetch data from Omneo API
  • Update all Shapes with new data

These API requests are cached, so on future loads the components will be shown immediately. Whilst the data is cached, Shapes will fetch fresh data in the background, on each page load, to ensure they are up-to-date.

Styling Shapes

All shapes include the .Shape class, along with the Shape handle class, such as .TransactionList. This can be used to apply classes to Shapes through your site's CSS. To ensure priority when styling, we recommend using the div[data-omneo-shape] selector in your CSS:

div[data-omneo-shape] .Shape.TransactionList{
    padding: 8px 16px 16px;
    border-radius: 4px;
    box-shadow: 0 3px 20px 0 rgba(0,0,0,0.1);
}

Classes can also be applied to the Shape container, for a greater level of control around CSS selection.

Read more about implementing Shapes here.

 

Related articles