client-sdk

Integration Guide

This guide explains how to integrate Streamlined CMS into an HTML website to enable inline content editing.

Quick Start

Add this script tag to your HTML <head> (not at the end of <body>):

<head>
    <script
        src="https://cdn.streamlinedcms.com/client-sdk/v0.1/streamlined-cms.min.js"
        data-app-id="YOUR_APP_ID"
    ></script>
</head>

The script must be in <head> so it can load and apply saved content before the page renders. Placing it at the end of <body> would cause a flash of default content.

Get your App ID from your app details on app.streamlinedcms.com.

Script Configuration

The script tag accepts these data-* attributes:

Attribute	Required	Description
`data-app-id`	Yes	Your application ID from Streamlined CMS
`data-api-url`	No	Override the API endpoint (for development)
`data-app-url`	No	Override the app URL (for development)
`data-log-level`	No	Logging verbosity: `error`, `warn`, `info`, `debug`, `trace`

Marking Editable Elements

Add data-scms-* attributes to HTML elements to make them editable. Each element needs a unique ID within its context.

Text (`data-scms-text`)

Use text for any single piece of content: headings, paragraphs, labels, captions, etc. Authors get a clean inline editing experience.

<h1 data-scms-text="hero-title">Welcome to Our Site</h1>
<p data-scms-text="hero-subtitle">We build great products.</p>

Prefer text over HTML. If you have three headings, use three data-scms-text elements—not one data-scms-html containing all three. This gives authors a better editing experience and keeps content structured.

HTML (`data-scms-html`)

Use HTML only when the author needs to control the actual HTML code, or when a combination of other element types (text, link, image) won’t work. Authors edit via a code editor in the toolbar.

<div data-scms-html="about-content">
    <p>This content supports <strong>bold</strong>, <em>italic</em>, and more.</p>
    <ul>
        <li>List items</li>
        <li>And other HTML</li>
    </ul>
</div>

When to use HTML:

Content with tables or complex formatting
Blocks where the structure itself needs to be editable
Cases where you can’t break the content into separate text/link/image elements

When NOT to use HTML:

Individual headings, paragraphs, or labels (use data-scms-text)
A paragraph that just needs one link (use data-scms-text + data-scms-link)
Multiple separate elements that could each be their own editable (use multiple data-scms-text)

Images (`data-scms-image`)

For <img> elements. Authors can select new images from the media manager.

<img
    data-scms-image="hero-image"
    src="default-hero.jpg"
    alt="Hero image"
/>

Links (`data-scms-link`)

For <a> elements. Authors can edit the URL, link text, and target.

<a data-scms-link="cta-button" href="/get-started">Get Started</a>

Groups (`data-scms-group`)

Groups organize how content is stored. Wrap sections of your page in groups to control whether content is shared across pages or isolated to a specific page.

Add data-scms-group to a container element. All editable elements inside are stored under that group ID.

Shared Groups (headers, footers, sidebars)

Use the same group ID across multiple pages to share content. Edit once, update everywhere.

<header data-scms-group="header">
    <div data-scms-text="logo">Company Name</div>
    <nav>
        <a data-scms-link="nav-home" href="/">Home</a>
        <a data-scms-link="nav-about" href="/about">About</a>
        <a data-scms-link="nav-contact" href="/contact">Contact</a>
    </nav>
</header>

Page-Specific Groups

Use a unique group ID per page to isolate that page’s content storage.

<!-- On about.html -->
<main data-scms-group="page-about">
    <h1 data-scms-text="title">About Us</h1>
    <div data-scms-html="content">...</div>
</main>

<!-- On contact.html -->
<main data-scms-group="page-contact">
    <h1 data-scms-text="title">Contact Us</h1>
    <div data-scms-html="content">...</div>
</main>

Both pages can use the same element IDs (title, content) because they’re in different groups.

Why Use Groups

Efficiency: Content is fetched and stored by group, reducing API calls
Sharing: Shared groups (like header) sync content across all pages automatically
Isolation: Page-specific groups keep content organized and allow reusing element IDs
Clarity: Groups make it clear which content belongs together

Note: If groups are nested, the innermost group takes precedence. Elements inside the inner group are stored under the inner group’s ID; the outer group is ignored for those elements.

Templates (`data-scms-template`)

Use templates for repeating content blocks where authors need to add, remove, or reorder items.

Add data-scms-template to the wrapper element that will contain all instances. The first child element inside becomes the template that gets cloned for each instance. Authors can add new instances, delete existing ones, and reorder them.

Important: The attribute goes on the wrapper, not on individual items. Do NOT put data-scms-template on the repeating item itself.

<!-- The attribute goes on the wrapper (team-grid), NOT on team-card -->
<div class="team-grid" data-scms-template="team-member">
    <!-- This first child is the item template - it gets cloned for each instance -->
    <div class="team-card">
        <img data-scms-image="photo" src="placeholder.jpg" alt="Team member" />
        <h3 data-scms-text="name">Team Member Name</h3>
        <p data-scms-text="role">Role / Title</p>
    </div>
</div>

Your HTML can include one or many instances—the SDK uses the first child as the template structure and manages all instances from there. You don’t need to reduce existing instances down to one; leave your HTML as-is.

Note: If you have multiple instances in your HTML, ensure they all have the same structure (elements, IDs, and classes). The SDK expects all instances to match the first child’s structure.

When to use templates:

Lists (feature lists, benefit lists, navigation items)
Team member listings
Testimonials or reviews
Product cards
FAQ accordions
Blog post previews
Portfolio items

When NOT to use templates:

Single, non-repeating content (use regular editable elements)
Content where the count is fixed and known (just use individual elements)

Note: Nested templates (a template inside another template) are not supported. The inner template will be ignored.

Groups Inside Templates

You can use groups inside templates for content that should be identical across all instances. Edit it once, and it updates everywhere.

<div data-scms-template="product-card">
    <div class="product">
        <div data-scms-group="promo-banner">
            <span data-scms-text="promo-text">Free Shipping on Orders $50+</span>
        </div>
        <img data-scms-image="product-image" src="placeholder.jpg" alt="Product" />
        <h4 data-scms-text="product-name">Product Name</h4>
        <p data-scms-text="product-price">$0.00</p>
    </div>
</div>

In this example, the promo banner text is shared across all product cards, while the image, name, and price are unique to each instance.

Authors need a way to sign in to enable editing. You should add a sign-in link to your footer, typically in the copyright line. Add the data-scms-signin attribute to a link element:

<footer>
    <p>&copy; 2025 Company Name | <a href="#" data-scms-signin>Sign In</a></p>
</footer>

The SDK automatically:

Attaches click handlers for sign-in
Changes the text to “Sign Out” when authenticated
Restores the original text when signed out

Note: If you forget to add a data-scms-signin element, the SDK will append a default sign-in link to the page. This fallback is unstyled and may not match your design, so always add your own.

Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Website</title>
    <script
        src="https://cdn.streamlinedcms.com/client-sdk/v0.1/streamlined-cms.min.js"
        data-app-id="YOUR_APP_ID"
    ></script>
</head>
<body>
    <!-- Shared header across all pages -->
    <header data-scms-group="header">
        <div data-scms-text="logo">My Company</div>
        <nav>
            <a data-scms-link="nav-1" href="/">Home</a>
            <a data-scms-link="nav-2" href="/about">About</a>
        </nav>
    </header>

    <!-- Page-specific content (unique group per page) -->
    <main data-scms-group="page-home">
        <h1 data-scms-text="title">Welcome</h1>
        <div data-scms-html="intro">
            <p>This is the intro paragraph with <strong>rich text</strong> support.</p>
        </div>
        <img data-scms-image="hero" src="hero.jpg" alt="Hero image" />

        <!-- Repeating team section -->
        <section>
            <h2 data-scms-text="team-heading">Our Team</h2>
            <div data-scms-template="team-member">
                <div class="team-card">
                    <img data-scms-image="photo" src="placeholder.jpg" alt="Photo" />
                    <h3 data-scms-text="name">Name</h3>
                    <p data-scms-text="role">Role</p>
                </div>
            </div>
        </section>
    </main>

    <!-- Shared footer across all pages -->
    <footer data-scms-group="footer">
        <p data-scms-text="copyright">&copy; 2025 My Company</p>
        <a href="#" data-scms-signin>Sign In</a>
    </footer>
</body>
</html>

Element ID Guidelines

Use descriptive, kebab-case IDs: hero-title, nav-link-1, team-photo
IDs must be unique within their context (page, group, or template)
Template element IDs are scoped to each instance, so name in one team member doesn’t conflict with name in another

SEO & Accessibility

SEO attributes (alt text, title) and accessibility attributes (ARIA labels, roles) can be configured in the CMS after content is set up. No additional HTML markup is required.

Browser Support

The SDK is designed to work on all modern browsers (desktop and mobile).

This site is open source. Improve this page.