This compressed Reference Guide will walk you through why LaunchBrightly recommends data attributes, and provides a set of simple examples of the types of custom [data-lb] attributes and how they can be added to your HTML elements.
What we do
LaunchBrightly is a product screenshot automation platform for your customer support team that captures screenshots of your product elements and automatically updates the screenshots in your help center when product updates are made. As product updates are pushed to production, your help center will automatically be updated with premium quality screenshots. The reliable and fully automated screenshots process will mean your help center is never out of sync again providing your customers with a better overall experience and removing the unnecessary burden of manually updating product screenshots from your customer support team.
Why do we recommend custom data attributes?
The automated screenshot process is built on our Open Screenshot API which, on request, tries to locate DOM elements using selector queries. In plain english, we try to find the first instance of an HTML element on the page (URL) you would like us to take a screenshot of.
Our Platform provides a Screenshot Setup Wizard (WYSIWYG) which is a very user friendly visual point-and-select to what elements you want us to capture. Alternatively, for the tech savvy support individual, they may even adjust or write the selector by hand. This is all good and fine, and it will get the support team started immediately, but we sometimes see the Selector, HTML ID’s, ClassNames, Xpaths etc. change as you update your App. You might make honest changes to the Frontend that changes these identifiers, and some build processes might also update/obfuscate/minimize away this set of identifiers which could see LaunchBrightly lose the ability to find the element. This will force the support person to go find and update the product element once again.
To escape some of this potential fragility, and build some positive glue between Makers and Support, and ultimately remove the risk of the automatic process being disrupted, we recommend adding agreed upon custom data attributes to make this process more resilient and flexible.
Using the custom [data-lb] attributes will let the automated screenshot process know which HTML elements it should capture, and will NOT have any impact on your page or its functionality. Once the [data-lb] attribute has been embedded it will not need to be updated again and will mitigate potential follow up requirements from your customer support team as the attribute will be virtually “unbreakable.”
What are data attributes?
A few words to set the stage, which any intermediate Frontend Engineer can skip! 🙂
Data attributes allow us to store extra information on standard, semantic HTML elements without any hacks. They are completely ignored in rendering your HTML and therefore are no risk of affecting your page or functionality. These data attributes provide you with a clean, and non-intrusive, way to attach additional information to any of your HTML elements which is not necessary for your users but is useful for developers and machine processes like LaunchBrightly.
HTML syntax
The syntax for using data attributes is straightforward. Data attributes are key-value pairs consisting of a fixed attribute name and an attribute value. Syntax:
<element data-*="value">
- Attribute name. Your attribute name must be at least one character long, should not contain any capital letters and be prefixed with data-
- Attribute value. Your attribute value must include at least one character and can by any string.
Therefore, a data attribute is any attribute whose name starts with “data-” and contains at least one character after the hyphen; Such as data-lb.
Example
To illustrate the HTML syntax for data attributes, let’s take an example where we want to list the title of popular novels and use data attributes to attach the author to each novel's title, for some search engine to read. To do this we would use the “data-” prefix to name the attribute [data-author] and use the name of the author as the attribute value. Here is an example:
<!DOCTYPE html>
<html>
<head>
<title>Example custom data attribute in HTML</title>
</head>
<body>
<h1>Novels</h1>
<p>A list of the most popular novels of all time</p>
<ul>
<li data-author="J.R.R. Tolkien">Lord of the Rings</li>
<li data-author="J.K. Rowling">Harry Potter and the Sorcerer's Stone</li>
<li data-author="F. Scott Fitzgerald">The Great Gatsby</li>
</ul>
</body>
</html>
Your users would only see the titles, but others systems and processes can pick up the author name.
Introducing the [data-lb] attribute
In order to continually capture screenshots of all your product elements, the [data-lb] attribute allows you to take advantage of more robust attributes and remove the risk of casual CSS selectors breaking when changes to your Frontend code are made.
We provide a reference guide of the “syntax” (different data-lb-* attributes) below, but would highly recommend using the Implementation Worksheet (see next section). The worksheet provides a very easy and straightforward set of actions to take. Almost a copy-paste.
Types of [data-lb] attributes
Parent [data-lb] attributes
The parent [data-lb] attribute and its associate value is a unique identifier used by our screenshot automation servers to latch onto the exact product element (as defined in the platform) to capture as part of the automated product screenshot process. It is a 6 character string and is not case sensitive.
Below is an example of a parent [data-lb] attribute:
<div
id="navigation"
data-lb="ptsgjd"
class="flex w-full">
<div class="text-xs">Bla bla bla Feature Component</div>
</div>
It is very often the top outer element of a component which you would add the [data-lb] attribute to and it is recommended you make the insert as logical as possible, so changes to the layout of the page etc, which might see this component move, will “just'' see the [data-lb] attribute move along with it. This will ensure the most robust implementation of the automated product screenshot process and mitigate any potential follow up requests from your partners in the Support Org.
Nested child attributes
In addition to the above parent [data-lb] attribute we also support nesting (creating children) as 3 types of child actions can be attached in the platform and mentioned here as a casual reference only:
Clean
Your customer support team can identify elements they may want to remove or blur from the product screenshot to clean it and remove unnecessary noise from the version that is showcased to your customers in the help center.
Action
Likewise, your customer support team may want to add some text to the input box, display the dropdown or make sure a table is sorted the way they want it to best convey to your customers how a feature works.
Annotate
Finally, your customer support team is often eager to overlay annotations on the product screenshot, for example, adding an arrow to specifically point to the element a help article is referring to or adding a rectangle to highlight the specific area of the screenshot being referenced.
The nested attribute is, just like its parent, a simple identifier, and its associate value is a unique identifier used by our screenshot automation servers to latch on to the element and take any of the above 3 actions. Similarly to the parent this identifier is provided by the platform and exposed in the worksheet. It is a 6 character string and is not case sensitive.
Example of using parent and child attributes together
<div
id="navigation"
data-lb="ptsgjd"
class="flex w-full">
<div class="text-lg">Bla bla bla Feature Component</div>
<input type="text" />
<label data-lb="lksuir">Some long description</label>
</div>
Help on Implementation
If you have any questions at all please feel free to email as hello@launchbrightly.com. We are more than happy to answer any questions you have, do some QA on your behalf or lend any support we can to help with implementation. So don’t be shy to reach out! We monitor this email address regularly and are available to respond almost immediately.
Implementation Worksheet
Our implementation best practice is for your support team to identify all product elements, visually, using our Screenshot Setup Wizard (WYSIWYG), and use that as the backdrop for the generation of a simple straightforward worksheet. This worksheet will include the exact insert action for each [data-lb] attribute and a set of details for what and where detailing the following information for each [data-lb] attribute:
- The [data-lb] attribute which can be copied and pasted directly into your HTML
- The page URL where the [data-lb] attribute will live
- The existing CSS selectors attached to the HTML element that was captured as a helping hand to locate where to do the insert