Skip to main content

BILDIT Template Guide

This guide provides comprehensive information about creating and using templates in the BILDIT system. Templates are React components that include inline template variables, allowing marketers and content editors to customize content dynamically.

The Template System enables marketers and developers to build reusable, configurable UI blocks. Templates are authored as React components that declare inline variables. At edit time, these variables are transformed into form fields for content editors; at render time, variable values are injected into the component to produce the final UI.

What Is a Template?​

A template is a React component that includes inline template variables using the syntax $(name:Type="Default Value"). These variables are parsed at runtime, generating form fields for marketers and content editors to fill out dynamically.

Core Concepts​

  • Template: A React component representing a reusable UI block.
  • Template Variable: An inline declaration inside the component that becomes an editor field.
  • Grouping: Logical grouping of related variables for better editor UX.
  • Default Values: Sensible defaults that enable immediate previewing and safe fallbacks.

Template Variable Syntax​

Each variable follows this format:

$(variableName:Type="Default Value")

Supported Types​

  • String – Text field
  • Color – Hex/RGB/Named color picker
  • Boolean – Toggle switch
  • Number – Numeric input
  • Image – Scene7 slug (or file)
  • Link – URL input
  • Dropdown[Option1|Option2|...] – Dropdown selector
  • Component – References another reusable code block by ID

Grouping Fields​

Use //group {Group Name} and //endgroup comments to organize variables into visual groups in the Visual Experience Engine interface.

Example​

//group {Hero Settings}
const headline = $(headline:String="Welcome to BILDIT!");
const backgroundColor = $(backgroundColor:Color="#ffffff");
//endgroup

This grouping creates organized sections in the Web Visual Experience Engine interface, making it easier for content editors to find and modify related settings.

Sample Variable Declarations​

Here are practical examples of how to declare different types of template variables:

CTA Group​

//group {CTA}
const ctaText = $(ctaText:String="Click Here");
const ctaUrl = $(ctaUrl:Link="https://example.com");
const showArrow = $(showArrow:Boolean=true);
//endgroup

Image Group​

//group {Image}
const heroImage = $(heroImage:Image="default_image_slug");
//endgroup
const marginSize = $(marginSize:Dropdown[Small|Medium|Large]="Medium");

Color Example​

const primaryColor = $(primaryColor:Color="#007bff");

Template Examples​

Minimal Example​

Here's a simple template to get you started:

"use client";
import React from "react";

//group {Content}
const title = $(title:String="Endless Summer Sale");
const subtitle = $(subtitle:String="Get ready to save big!");
//endgroup

export default function Template() {
  return (
    <section className="p-6 text-center">
      <h1 className="text-3xl font-bold">{title}</h1>
      <p className="text-xl mt-2">{subtitle}</p>
    </section>
  );
}

Complete Example Template​

Here's a full example with image handling and advanced features:

"use client";

import React, { useMemo } from "react";
import Image from "next/image";

//group {Content}
const title = $(title:String="Endless Summer Sale");
const subtitle = $(subtitle:String="Get ready to save big!");
//endgroup

//group {Image}
const imageSlug = $(imageSlug:Image="default_slug");
//endgroup

const Template = () => {
  const imageUrl = useMemo(() => {
    return `https://belk.scene7.com/is/image/Belk/${imageSlug}?$DWP_PHOTO$`;
  }, [imageSlug]);

  return (
    <div className="w-full p-6 bg-white text-center">
      <h1 className="text-3xl font-bold">{title}</h1>
      <p className="text-xl mt-2">{subtitle}</p>
      <Image
        src={imageUrl}
        alt={title}
        width={800}
        height={400}
        className="mx-auto mt-4 rounded-lg"
      />
    </div>
  );
};

export default Template;

Template Component Guidelines​

When creating templates, follow these essential guidelines:

  • Always export a default functional component
  • Template variables must be declared at the top-level of the file
  • Use descriptive names and provide meaningful defaults
  • Group fields by intent to improve editor usability
  • Use useMemo() to prepare derived values like Scene7 URLs
  • Responsive image rendering is supported via a helper like PictureResponsiveImage
  • Keep layout responsive; avoid hardcoded values that conflict with variables

How It Works​

The template system operates through several key steps:

  1. Code Parsing: At build time or runtime, the $(...) syntax is parsed to extract variables and generate a field schema.
  2. Metadata Generation: The system builds metadata for each field (name, type, default, group).
  3. Editor UI Form: Based on this metadata, a form is rendered for editors inside the Visual Experience Engine.
  4. Runtime Rendering: When published, the system replaces the $(...) placeholders with the user-provided values to generate final React output.

Best Practices​

Follow these recommendations for optimal template development:

  • Use descriptive variable names that clearly indicate their purpose
  • Set sensible defaults for previewing and fallback scenarios
  • Group fields logically for improved Visual Experience Engine usability
  • Reuse components where possible via the Component type
  • Keep layout responsive using Tailwind utility classes
  • Test templates across different devices and screen sizes
  • Document complex logic with comments for future maintainers

Template Development Workflow​

  1. Plan your template structure and identify required variables
  2. Create the React component with template variables at the top
  3. Group related variables using //group comments
  4. Test the template in the Visual Experience Engine interface
  5. Iterate and refine based on content editor feedback
  6. Deploy and monitor template performance

Advanced Features​

Component References​

Use the Component type to reference other reusable templates:

const headerComponent = $(headerComponent:Component="default_header");

Conditional Rendering​

Combine Boolean variables with conditional logic:

const showBanner = $(showBanner:Boolean=true);
const bannerText = $(bannerText:String="Special Offer!");

// In your JSX:
{showBanner && (
  <div className="banner">
    {bannerText}
  </div>
)}

Responsive Images​

Use the Image type with responsive helpers:

const heroImage = $(heroImage:Image="default_hero");
// Use with PictureResponsiveImage component for optimal loading

Getting Help​

If you need assistance with template development:

  • Review the Troubleshooting Guide for common issues
  • Check the Best Practices for optimization tips
  • Test templates in the preview mode before publishing
  • Use the Visual Experience Engine interface to validate variable configurations

Ready to create your first template? Start with the Scheduled Content Management guide to see templates in action.