Lucit Template HTML Guide¶

This is a guide to the HTML structure for Lucit Templates

Overview¶

Lucit Template HTML is combined with Render App HTML to produce a final HTML document

This guide describes the structure of this HTML

Rules¶

The following "rules" are in effect for our HTML templates. These rules help to ensure that we can render these templates in the Lucit Template Designer (a WYSIWYG design tool) and that the templates will render as expected in Render App on every screen format size.

All first layer elements

MUST be either a div or a video element
- Why? - The Lucit Template Designer can only detect layers that are div or video elements
MUST be siblings that are direct children of the Render App Container div
- Why? - The Lucit template designer creates a layer list based on the direct children of the parent div lc_dt_container
MUST have an id attribute
- id MUST begin with ONE OF the following prefixes:
- img_ Image elements where the image is a user uploaded asset
- data_source_img_ Image elements where the image comes from a data source macro
- data_source_text_ Text elements where the text comes from a data source macro
- obj_ Any other elements, especially if linked to any pre-existing Designer Elements
- After the prefix, it MUST have some unique text or id. Typically this is a 7 character alphanumeric string, but can be any unique string of text.
- Exceptions The exception to this rule is if the element is the rectangle_default_bg (the default background) then its ID is rectangle_default_bg
MUST be absolutely positioned inside their parent div container (class lc_dt_container) which is provided by render app
- Why - Absolute positioning is used to ensure that the template is responsive to different screen formats
- Positioning is provided by css classes, and, the custom CSS applied.
- Positioning MUST be in relative units (percentages) NOT IN pixels
MUST have the lc_ut_designer class
MUST have one of the following element primary classes
- lc_dt_text
- lc_dt_image
- lc_dt_video
- lc_dt_object
- lc_dt_object_svg
MUST have the following attributes
- id - Must be unique
- title
- class
- x-objectcode - A code that maps to the Field Map that provided this element
- x-fieldname - Name of field in the Layers Panel
MAY have the following attributes
- style
- data-value - For dynamic elements, contains macros from the Field Map. This attribute is used to store the dynamic value of the element before any formatting or changes are made to it.
- x-placeholder - A placeholder that appears when no macro value has been set on a dynamic field
- x-optional-field - if true this dynamic field does not have to be filled out during Post Ad, if empty or false, then when posting an ad, the user will be required to fill out a value for this field.
- x-element-settings - Contains configurable settings for this dynamic element
- x-element-setting-values - Contains the values of those settings that were selected
- x-group-parent-id - If this dynamic element belongs to an application data source - This is the LCUID of the data source
- x-animations - A serialized array of JSON objects containing the animations to apply to this element.
- data-max-font-size - When a lc_dt_text element has the lc_format_fit_text class, this is the maximum size that the font will grow to. This is represented in vmax units. If empty, there is no max size.
- data-max-chars - For dynamic lc_dt_text elements, the maximum number of characters that will be displayed in this element. If empty, there is no limit
- data-max-chars-show-ellipsis - For lc_dt_text elements when data-max-chars is set, whether or not to show an ellipses at the end of any cut-off text
- data-video-delay - For lc_dt_video elements, how long to delay, in seconds before playing this video
- muted - MUST exist For lc_dt_video elements, MUST be set to muted
- preload - MUST exist For lc_dt_video elements, MUST be set to metadata
- playsinline - MUST exist For lc_dt_video elements, MUST be set to playsinline
- poster - For lc_dt_video elements, the url to the poster / display image for this video
Inner HTML MAY contain
- Text when element is lc_dt_text
- SVG or HTML code when element is lc_dt_object_svg or lc_dt_object
Style attribute MUST NOT contain any styles, other than background-image
- background-image: url('') when element is lc_dt_image
All Other css styles (other than backgroud-image) MUST BE added to the CSS blocks and not as inline styles in the HTML. (This includes positioning, formatting, etc.) See CSS Guide for more information
Text elements that are not dynamic and should be editable by the user MUST HAVE the lc_dt_text_editable class. (This allows a user to edit the text of the field in the Lucit Template Designer)
All dynamic elements (with data source macros) MUST HAVE the lc_dt_data class
All dynamic elements with video or image macros that reference a user uploaded image, MUST HAVE the lc_dt_asset class
Elements with Designer Functions MUST HAVE the lc_dt_data_function class
Elements that were added from the built-in Template Elements, MUST HAVE the lc_dt_element class

Functional Classes¶

The following is a list of CSS classes that provide function in some way to elements

lc_dt_text Is a text element that will have Inner HTML containing text
- These element may contain one of the following additional classes
  - lc_format_fit_text auto grow-shrink dynamic text to fit the bounds of the div
  - lc_format_{function} special functional classes used by Designer Text Formatting Functions. For example, lc_format_price_us formats the text as a price with a dollar sign. lc_format_round_integer will round the number to the nearest integer, etc.
lc_dt_asset Any image or video element uploaded to the template by the user has this class to signify that is an upload asset
lc_dt_image An image element that contains a background image in the style attribute
- These elements may contain one of the following additional classes
  - lc_dt_preserve_aspect preserves its aspect ratio
  - lc_dt_image_full_size_stretch stretch to completely fill the size of the screen
  - lc_dt_default_background A default background layer for the canvas. Does not appear in the layers panel as editable in any way
lc_dt_video A video element. MUST be ONLY assigned to video tag element.
lc_dt_object A div element that can contain additional html in its Inner Html
lc_dt_object_svg a div element that contains svg in its Inner Html
lc_dt_data A div that contains dynamic data - Typically also will have a data-value attribute
lc_dt_data_function Custom fields that render their values using Designer Functions have this class
lc_dt_element This element was added from our built in element library or from an app that provides elements
lc_dt_text_editable Non-dynamic text elements have this to indicate that the user can edit the text of this element on the canvas by double-clicking on it

ID's¶

ID's for elements MUST begin with img_, data_source_img_, data_source_text_ or obj_ UNLESS the element is the rectangle_default_bg div.

Using Placholder Images when creating Templates¶

If you are creating the raw HTML and CSS from these documents, or, you are an LLM / AI that is generating code. It is important to use pre-existing elements as placeholders if you expect the user to then later provide a different image, logo, icon, photo, etc.

For images, it is recommended to use the Element HTML from one of the elements in Designer Elements that are named Placeholder : {Some Name}

This set of place holders are nice placeholder images that can be added and styled in a template.

When these appear, a user can then take the following actions to replace the image

Click on the small {} icon that appears above the image when you have selected it
Right click on the image, and choose "Replace Image" from the context menu
Click on the image, and then in the Edit panel, find the REPLACE IMAGE button and click on it.

The user can then select a new image to replace the place holder

You may however, use any of the pre-built elements in the Designer Elements when creating a template. There are many images, svgs and text to choose from if they meet your needs.

Examples¶

Here are some examples

Text

This is a text element that is editable by the user in the Template Designer. Note the lc_dt_text_editable class

The font size for this element will auto resize based on the height/width of the box - Note the lc_format_fit_text class

<div
  id="obj_your_new_text_era87f9b"
  title="Your New Text"
  x-objectcode="your_new_text"
  class="lc_ut_designer lc_dt_element lc_dt_text lc_dt_text_editable lc_format_fit_text"
  style=""
  x-fieldname="your_new_text"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
  Your New Text
</div>

Dynamic Text Element

Note the {item.title} macro, the data-value attribute, and the lc_dt_data class (all required for dynamic elements with macros)

The font size for this element will auto resize based on the height/width of the box - Note the lc_format_fit_text class

<div
  id="data_source_text_fldrsep6"
  title=""
  x-objectcode="item_title"
  class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text"
  x-placeholder="Your Caption"
  x-optional-field="false"
  x-fieldname="Title"
  data-value="{item.title}"
  x-element-settings="{}"
  x-element-setting-values="{}">
  {item.title}
</div>

Optional Dynamic Text Element

Note the {item.description} macro and x-optional-field="true"

During the Post Ad process, a user will see a text box to fill out a value for this field, but, this field will not be required, and the user can post an ad and leave this field blank.

If x-optional-field was false (default) then the user would be required to fill out this field before continuing with the post ad process.

This only applies to templates that are being used to manually create ads via the Post Ad Process

<div
  id="data_source_text_fldrsep6"
  title=""
  x-objectcode="item_description"
  class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text"
  x-placeholder="Your Caption"
  x-optional-field="true"
  x-fieldname="Title"
  data-value="{item.title}"
  x-element-settings="{}"
  x-element-setting-values="{}">
  {item.description}
</div>

Dynamic Text Element with a Screen Data Macro

Note the {digital_board.location.city} macro that will pull the correct city name depending on where this ad is playing

<div
  id="data_source_text_5cy777xh"
  title=""
  x-objectcode="digital_board_location_city"
  class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text"
  x-placeholder="Anytown"
  x-optional-field="false"
  x-fieldname="City"
  data-value="{digital_board.location.city}"
  x-element-settings="{}"
  x-element-setting-values="{}">
  {digital_board.location.city}
</div>

User Uploaded Image

An image that was uploaded, or, dragged and dropped onto the Template Designer canvas.

Note that this contains a macro {LCUID-LM-27b02a5d-a7c6-480e-a1aa-68ff62b9953b.options.public_url} that represents an Image object in Lucit. Note the lc_dt_asset class that represents that this file was user uploaded. At render time, the macro is replaced by the full url to the image.

Note that this element does not require lc_dt_data because the macro is not a "data source" but is a placeholder for a user uploaded image

<div
  id="img_1189942"
  title=""
  x-objectcode="asset_img"
  x-assetid="1189942"
  x-fieldname="icon"
  class="lc_ut_designer lc_dt_asset lc_dt_image lc_dt_preserve_aspect"
  style="background-image: url('{LCUID-LM-27b02a5d-a7c6-480e-a1aa-68ff62b9953b.options.public_url}');"
  data-value="{LCUID-LM-27b02a5d-a7c6-480e-a1aa-68ff62b9953b.options.public_url}"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
</div>

User Uploaded Background Image

An image uploaded by the user, and Stretch to fill the screen was selected. Note the lc_dt_image_full_size_stretch class

<div
  id="img_1189944"
  title=""
  x-objectcode="asset_img"
  x-assetid="1189944"
  x-fieldname="5starauto-demo-creative"
  class="lc_ut_designer lc_dt_asset lc_dt_image lc_dt_image_full_size_stretch"
  style="background-image: url('{LCUID-LM-c9e99b29-16ef-499f-a71a-e0373f0a13ea.options.public_url}');"
  data-value="{LCUID-LM-c9e99b29-16ef-499f-a71a-e0373f0a13ea.options.public_url}"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
</div>

Dynamic Image

A dynamic image provided during template render. Either manually during the Post Ad process, or, by a Inventory type data source when generating ads

Note the {item.options.primary_image_public_url} as well as the lc_dt_data class that will provide the full url to the image during render.

<div
  id="data_source_img_yjzr38ga"
  title=""
  x-objectcode="item_options_primary_image_public_url"
  class="lc_ut_designer lc_dt_data lc_dt_image"
  x-placeholder="https://lucit.app/assets/designer/image_placeholder_Item.png"
  x-fieldname="Item Image"
  style="background-image: url('{item.options.primary_image_public_url}');"
  data-value="{item.options.primary_image_public_url}"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
</div>

User Uploaded Video

A video uploaded by the user, and Stretch to fill the screen was selected. Note the lc_dt_image_full_size_stretch class and the lc_dt_asset class that represents that this file was user uploaded.

Also note the 2 macros. {LCUID-LMV-a79c7fba-174b-42e5-9d5d-c80df702a1c5.options.public_url} is the url to the video file, and {LCUID-LMV-a79c7fba-174b-42e5-9d5d-c80df702a1c5.options.thumbnail_public_url} is the url to a static poster image of the video

<video
  id="video_25"
  title=""
  x-objectcode="asset_video"
  x-fieldname="Log Out"
  class="lc_ut_designer lc_dt_asset lc_dt_video lc_dt_image_full_size_stretch"
  muted="muted"
  preload="metadata"
  playsinline="playsinline"
  poster="{LCUID-LMV-a79c7fba-174b-42e5-9d5d-c80df702a1c5.options.thumbnail_public_url}"
  data-value="{LCUID-LMV-a79c7fba-174b-42e5-9d5d-c80df702a1c5.options.public_url}"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
  <source
    src="{LCUID-LMV-a79c7fba-174b-42e5-9d5d-c80df702a1c5.options.public_url}" />
</video>

Lucit Element - Rectangle

A rectangle shape from the Shapes list. Note the lc_dt_element class that represents that this element was added from the Elements Panel from the list of available elements.

<div
  id="obj_rectangle_qysc0epm"
  title="Rectangle"
  x-objectcode="rectangle"
  class="lc_ut_designer lc_dt_element lc_dt_object"
  style=""
  x-fieldname="rectangle"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
  <div></div>
</div>

Lucit Element - (svg) Circle

An svg circle from the Shapes list. Note the lc_dt_element class that represents that this element was added from the Elements Panel from the list of available elements.

<div
  id="obj_circle_63o1a0h4"
  title="Circle"
  x-objectcode="circle"
  class="lc_ut_designer lc_dt_element lc_dt_object lc_dt_object_svg"
  style=""
  x-fieldname="circle"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
  <svg
    height="100%"
    width="100%"
    viewBox="0 0 100 100"
    preserveAspectRatio="xMidYMid meet"
    pointer-events="none">
    <circle
      cx="50"
      cy="50"
      r="40"></circle>
  </svg>
</div>

Lucit Element - Background Image

A background image element from the Backgrounds list

<div
  id="obj_pink_sky_wl0mwuth"
  title="Pink Sky"
  x-objectcode="pink_sky"
  class="lc_ut_designer lc_dt_asset lc_dt_image lc_dt_image_full_size_stretch"
  style="background-image: url('https://lucore-bucket-images-prod2.s3.us-east-2.amazonaws.com/5155/img_67ec2019046e6_295d3b237c0331e6171e.jpg');"
  x-fieldname="pink_sky"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
</div>

Lucit Dynamic Countdown Element

The countdown element that has customizable settings to render a countdown to a specific date

Note that this element has x-element-settings and x-element-setting-values configured.

x-element-settings uses the Form Fields to render a form when a user edits the settings of this element after adding it to their template. The values of those settings are stored in x-element-setting-values

<div
  id="obj_countdown_hours_and_days_tvguddxi"
  title="Countdown : Hours and Days"
  class="lc_ut_designer lc_dt_element lc_dt_text lc_dt_text_editable lc_format_fit_text"
  x-element-settings='{"fields":[{"key":"targetDate","name":"Target Date","type":"datetime","placeholder":"12\/25\/2024"},{"key":"prefix","name":"Prefix","type":"text","default_value":"Only"},{"key":"suffix","name":"Suffix","type":"text","default_value":"Until the big day!"},{"key":"resultStyle","enum":"true","name":"Style","type":"text","placeholder":"days_hours","enum_options":[{"label":"Days No Label","value":"days_no_label"},{"label":"Days","value":"days"},{"label":"Days, Hours","value":"days_hours"},{"label":"Hours","value":"hours"}]}]}'
  x-fieldname="countdown_hours_and_days"
  x-optional-field="false"
  x-element-setting-values='{"prefix":"Only","suffix":"Until the big day!","targetDate":"2026-12-25T13:07","resultStyle":"days_hours"}'
  x-placeholder="countdown_hours_and_days">
  0 days
</div>

Custom Field (Text) using the fnConcat designer function

This custom text field renders a single text element for multiple macros using the built in fnConcat Designer Function and concatenating both text and macros together into a single text field. Note the lc_dt_data_function class that signifies that this element contains a Designer Function.

Also note how in this example, we use the double curly brace style for wrapping the macros that appear in Javascript. This helps prevent escapaing issues.

<div
  id="data_source_text_h8syielw"
  title=""
  x-objectcode="custom_field_zcjrporn"
  class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text lc_dt_data_function"
  x-placeholder="Pre-Owned 2009 Ford Focus"
  x-optional-field="false"
  x-fieldname="Make Modela and Year"
  data-value="{fnConcat([
'Pre-Owned ',
'{{item.year}}',
' ',
'{{item.make}}',
' ',
'{{item.model}}',
]);}"
  x-element-settings="{}"
  x-element-setting-values="{}">
  {fnConcat([ 'Pre-Owned ', '{{item.year}}', ' ', '{{item.make}}', ' ',
  '{{item.model}}', ]);}
</div>

Custom Field (Image) using fnConcat to get the url to a team logo icon

This custom image field renders a single image element for multiple macros using the built in fnConcat Designer Function and concatanating both text and macros together into a single url that is used to get the image.

<div
  id="data_source_img_be9pcje2"
  title=""
  x-objectcode="custom_field_1ve302cj"
  class="lc_ut_designer lc_dt_data lc_dt_asset lc_dt_image lc_dt_data_function"
  x-placeholder=""
  x-fieldname="Custom Image Field"
  style="background-image: url('{fnConcat([
'https://example.com/images/',
'{{item.inventory_attributes.teams_home_id}}',
'.png'
]);}');"
  data-value="{fnConcat([
'https://example.com/images/',
'{{item.inventory_attributes.teams_home_id}}',
'.png'
]);}"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}"></div>

Element with animations

This element has 2 animations that are applied to it. Note the x-animations property.

Each animation provides its settings and these are turned into CSS styles during the rendering of the template.

<div
  id="obj_hexagon_obf5c7nj"
  title="Hexagon"
  x-objectcode="hexagon"
  class="lc_ut_designer lc_dt_element lc_dt_object lc_dt_object_svg"
  style=""
  x-fieldname="hexagon"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}"
  x-animations='[{"number":1,"name":"bounce","duration":1,"delay":0.25,"iteration":1,"direction":"normal","fillMode":"backwards"},{"number":2,"name":"bounceOutDown","duration":1,"delay":1.25,"iteration":1,"direction":"normal","fillMode":"forwards"}]'>
  <svg
    width="100%"
    height="100%"
    viewBox="0 0 1080 1080"
    pointer-events="none">
    <polygon
      points="784.64 108.67 1040 540 791.07 971.33 286.78 971.33 40 540 288.93 108.67 784.64 108.67"></polygon>
  </svg>
</div>

Full example with multiple elements¶

This is an example of a template with multiple elements

This is what you would see if using the HTML Tab on the Code Editor in the Template Designer

<div
  id="rectangle_default_bg"
  title=""
  x-objectcode="rectangle"
  class="lc_ut_designer lc_dt_object lc_dt_default_background"
  x-fieldname="rectangle"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}"></div>

<div
  id="obj_deep_relief_zgrfgxql"
  title="Deep Relief"
  x-objectcode="deep_relief"
  class="lc_ut_designer lc_dt_element lc_dt_object lc_dt_image_full_size_stretch"
  x-fieldname="deep_relief"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}"></div>

<div
  id="obj_rectangle_bezseekc"
  title="Rectangle"
  x-objectcode="rectangle"
  class="lc_ut_designer lc_dt_element lc_dt_object"
  style=""
  x-fieldname="rectangle"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
  <div></div>
</div>
<div
  id="obj_your_new_text_ty89hitu"
  title="Your New Text"
  x-objectcode="your_new_text"
  class="lc_ut_designer lc_dt_element lc_dt_text lc_dt_text_editable lc_format_fit_text"
  style=""
  x-fieldname="your_new_text"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}">
  Welcome To My Store
</div>

<div
  id="data_source_img_95dj7s8c"
  title=""
  x-objectcode="item_options_primary_image_public_url"
  class="lc_ut_designer lc_dt_data lc_dt_image"
  x-placeholder="https://lucit.app/assets/designer/image_placeholder_Item.png"
  x-fieldname="Custom Picture"
  style="background-image: url('{item.options.primary_image_public_url}');"
  data-value="{item.options.primary_image_public_url}"
  x-optional-field="false"
  x-element-settings="{}"
  x-element-setting-values="{}"></div>

<div
  id="data_source_text_2qt0j27j"
  title=""
  x-objectcode="item_title"
  class="lc_ut_designer lc_dt_data lc_dt_text lc_format_fit_text"
  x-placeholder="Sally Smith"
  x-optional-field="false"
  x-fieldname="Customer Name"
  data-value="{item.title}"
  x-element-settings="{}"
  x-element-setting-values="{}">
  {item.title}
</div>

Adding HTML to a template¶

When adding RAW HTML to a template, you can do this typically without issue, but with the following caveats

Unless you follow the strict rules (see above) the element is unlikely to later be editable by the user designing the template
The layers panel may not correctly show this element
You may have rendering issues when rendering multiple template sizes

When designing custom HTML, a good source for examples and inspiration is the Lucit Dynamic Elements Reference which has hundreds of examples of all types