Overview

This article contains the Gtmhub best practices for writing insight HTML and CSS.

Ordering of Elements

  • A style tag, if present, should be at the start of the insight

  • Next should be the displayed HTML for the insight

  • Next should be any repeatable HTML template blocks used in Angular

  • Last should be a script tag for JavaScript, if needed

Style Tag/CSS

  • Only one style tag per insight should be used

  • All styles should be prefixed with the ID of the wrapper div of the insight to prevent unintentional effects on other insights or other UI elements

    • Unless the specific intent is to affect something outside the insight

      • If you are doing this, add a comment to your CSS specifically indicating what you intend to change

    • This is especially true when targeting elements by HTML tag or if your class names have risk of collision with Gtmhub classes or classes in other insights.

❌Avoid This

.table {
background-color: HotPink
}

✔️Do This

#reallyUglyInsight .table {
background-color: HotPink
}

Displayed HTML

  • All displayed HTML should be wrapped in a single div with a unique ID for the insight

    • Watch out when cloning an insight - make sure to update this ID

  • Avoid repeated use of inline styles on individual elements

    • Use a class or CSS instead

    • This de-clutters the HTML and makes it easier to make bulk changes in the future

    • If your style only needs to apply to one element, using an inline style is fine

❌Avoid This

<div id="badExample">
<span style="color: green">{{data.value1}}</span>
<span style="color: green">{{data.value2}}</span>
<span style="color: green">{{data.value3}}</span>
</div>

✔️Do This

<style>
#goodExample span {
color: green;
}
</style>

<div id="goodExample">
<span>{{data.value1}}</span>
<span>{{data.value2}}</span>
<span>{{data.value3}}</span>
</div>

✔️Or Do This

<style>
#goodExample .goodInsightValue {
color: green;
}
</style>

<div id="goodExample">
<span class="goodInsightValue">{{data.value1}}</span>
<span class="goodInsightValue">{{data.value2}}</span>
<span class="goodInsightValue">{{data.value3}}</span>
</div>
  • Avoid generic class names that may result in unintentional inheritance of styles from Gtmhub - including styles that don’t exist today but may be added in the future

    • If you specifically want to inherit the properties of existing classes, then using them is OK. Be aware they may change without warning

    • To help guarantee uniqueness of your class, pre-pend the insight div ID

❌Avoid This

<div class="column">

✔️Do This

<div class="insightDivId-column">

No Data or One Row of Data

  • Make sure to handle the “No Data” case in the event that data is not returned by the SQL

  • For cases where multiple rows of data are generally expected, verify that a single row of data returned is handled properly.

    • In this case, the data.default property will not be populated in the Angular data model


See Also

Code Best Practices: Insight JavaScript

Code Best Practices: Insight SQL

Did this answer your question?