Core Binding Attributes

Fundamental attributes for binding data to HTML elements

Core binding attributes are the foundation of DBindly. They handle the essential task of taking data from your collections and displaying it in your HTML elements.

Connecting to Your Data

Before using binding attributes, you need to understand how DBindly knows which data to display.

Single Data Item (One Row)

To display a specific row from your collection, you have three options:

Option 1: URL Parameter (Easiest)

Add ?did=YOUR_DATA_ID to your page URL:

https://yoursite.com/product?did=prod_abc123

DBindly automatically loads this data when the page loads.

Option 2: JavaScript API

<div id="product">
  <h1 dbind_data="name"></h1>
  <p dbind_data="description"></p>
</div>
 
<script>
  // Load specific data by ID
  DBindly.load('prod_abc123');
</script>

Option 3: Real-Time Reactive Binding

<!-- Subscribe to real-time updates for this data -->
<div dbind_reactive="prod_abc123">
  <h1 dbind_data="name"></h1>
</div>

Where to find the Data ID:

  1. Go to your DBIndly Dashboard
  2. Open your Collection
  3. Each row shows its unique Data ID (e.g., prod_abc123)
  4. Copy the Data ID to use in your code

Entire Collection (Multiple Rows)

To display all items from a collection, use dbind_collection with the collection's slug:

<div dbind_collection="products">
  <div dbind_repeat="data">
    <h3 dbind_data="name"></h3>
  </div>
</div>

Where to find the Collection Slug:

  1. Go to DBIndly Dashboard → Collections
  2. Click on your collection
  3. The Slug is shown in settings (e.g., products, blog-posts)

Note: The slug is URL-safe (lowercase, hyphens for spaces). "My Products" becomes my-products.

dbind_data

Purpose: Bind text content to a data field. This is the most commonly used DBindly attribute.

Syntax:

<element dbind_data="fieldName"></element>
<element dbind_data="nested.field.path"></element>

Basic Usage

The dbind_data attribute replaces the text content of an element with the value of the specified field.

<!-- Simple field binding -->
<h1 dbind_data="title"></h1>
<p dbind_data="description"></p>
<span dbind_data="author"></span>

Data:

{
  "title": "Welcome to DBindly",
  "description": "The easiest way to add dynamic content to any website.",
  "author": "John Doe"
}

Result:

<h1>Welcome to DBindly</h1>
<p>The easiest way to add dynamic content to any website.</p>
<span>John Doe</span>

Nested Properties

Access nested data using dot notation. This is essential for complex data structures.

<!-- Nested object access -->
<span dbind_data="user.name"></span>
<span dbind_data="user.profile.avatar"></span>
<span dbind_data="company.address.city"></span>

Data:

{
  "user": {
    "name": "Jane Smith",
    "profile": {
      "avatar": "https://example.com/avatar.jpg",
      "bio": "Software developer"
    }
  },
  "company": {
    "name": "TechCorp",
    "address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "country": "USA"
    }
  }
}

Result:

<span>Jane Smith</span>
<span>https://example.com/avatar.jpg</span>
<span>San Francisco</span>

Deeply Nested Access

There's no limit to nesting depth:

<span dbind_data="order.items.0.product.name"></span>
<span dbind_data="settings.notifications.email.frequency"></span>

Array Index Access

Access specific array elements by index:

<!-- First item (index 0) -->
<span dbind_data="tags.0"></span>
 
<!-- Second item (index 1) -->
<span dbind_data="tags.1"></span>
 
<!-- Access nested property of array item -->
<span dbind_data="products.0.name"></span>

Data:

{
  "tags": ["JavaScript", "Web Development", "Tutorial"],
  "products": [
    { "name": "Widget A", "price": 29.99 },
    { "name": "Widget B", "price": 49.99 }
  ]
}

Use Cases

1. Product Display

<article class="product">
  <h2 dbind_data="name"></h2>
  <p dbind_data="description"></p>
  <span class="price" dbind_data="price"></span>
  <span class="sku" dbind_data="sku"></span>
</article>

2. User Profile

<div class="profile-card">
  <h3 dbind_data="user.displayName"></h3>
  <p dbind_data="user.bio"></p>
  <span dbind_data="user.location"></span>
  <span dbind_data="user.memberSince"></span>
</div>

3. Blog Post Meta

<div class="post-meta">
  <span class="author" dbind_data="author.name"></span>
  <span class="date" dbind_data="publishedAt"></span>
  <span class="category" dbind_data="category.name"></span>
  <span class="reading-time" dbind_data="readingTime"></span>
</div>

4. E-commerce Order

<div class="order-summary">
  <span dbind_data="orderNumber"></span>
  <span dbind_data="customer.name"></span>
  <span dbind_data="shipping.address.city"></span>
  <span dbind_data="total"></span>
  <span dbind_data="status"></span>
</div>

Combining with Format

Use dbind_format alongside dbind_data for formatted output:

<span dbind_data="price" dbind_format="currency:USD"></span>
<span dbind_data="createdAt" dbind_format="date:relative"></span>
<span dbind_data="percentage" dbind_format="percent"></span>

Important Notes

  • Security: dbind_data automatically HTML-escapes content, preventing XSS attacks
  • Missing Data: If the field doesn't exist, the element content becomes empty
  • Type Coercion: All values are converted to strings for display

dbind_html

Purpose: Bind raw HTML content to an element. Use with extreme caution - only for trusted content.

Syntax:

<element dbind_html="fieldName"></element>

When to Use dbind_html

Use dbind_html only when:

  • Content comes from a trusted CMS you control
  • Rich text editors generate the content
  • You've sanitized the HTML server-side
  • Markdown has been converted to HTML

When NOT to Use dbind_html

Never use dbind_html for:

  • User-generated content (comments, reviews, etc.)
  • Data from untrusted third-party APIs
  • Content that users can edit directly
  • Any situation where you don't control the source

Basic Usage

<!-- Rich text content from CMS -->
<div class="rich-content" dbind_html="content"></div>
 
<!-- Formatted description -->
<div class="product-description" dbind_html="descriptionHtml"></div>

Data:

{
  "content": "<p>This is a <strong>rich text</strong> paragraph with <a href='/about'>a link</a>.</p>",
  "descriptionHtml": "<ul><li>Feature 1</li><li>Feature 2</li></ul>"
}

Result:

<div class="rich-content">
  <p>This is a <strong>rich text</strong> paragraph with <a href="/about">a link</a>.</p>
</div>

Use Cases

1. CMS Rich Text

<article>
  <h1 dbind_data="title"></h1>
  <div class="post-content" dbind_html="bodyHtml"></div>
</article>

2. Formatted Features List

<div class="features" dbind_html="featuresHtml"></div>

3. Marketing Content

<section class="hero">
  <div class="hero-content" dbind_html="heroContent"></div>
</section>

Security Warning

<!-- DANGEROUS: User-generated content -->
<div dbind_html="userComment"></div>
<!-- If userComment contains <script>malicious()</script>, it WILL execute! -->
 
<!-- SAFE: Use dbind_data instead -->
<div dbind_data="userComment"></div>
<!-- Script tags are escaped and displayed as text -->

Comparison: dbind_data vs dbind_html

Aspectdbind_datadbind_html
OutputText onlyRaw HTML
SecurityXSS-safe (escaped)XSS-vulnerable
Use forAny contentTrusted content only
HTML entitiesEscapedRendered
PerformanceFasterSlightly slower

dbind_default

Purpose: Specify a fallback value when the data field is missing, null, or empty.

Syntax:

<element dbind_data="fieldName" dbind_default="fallback value"></element>

Basic Usage

<!-- Show "Anonymous" if name is missing -->
<span dbind_data="authorName" dbind_default="Anonymous"></span>
 
<!-- Show placeholder for missing image -->
<span dbind_data="avatarUrl" dbind_default="/images/default-avatar.png"></span>
 
<!-- Show "N/A" for missing data -->
<span dbind_data="phoneNumber" dbind_default="N/A"></span>

When Defaults Apply

dbind_default is used when the field is:

  • Missing from the data object
  • Explicitly null
  • Explicitly undefined
  • An empty string ""
<span dbind_data="title" dbind_default="Untitled"></span>

Data scenarios:

// Missing field - shows "Untitled"
{ "description": "Some text" }
 
// Null value - shows "Untitled"
{ "title": null }
 
// Empty string - shows "Untitled"
{ "title": "" }
 
// Has value - shows "My Title"
{ "title": "My Title" }
 
// Zero is NOT empty - shows "0"
{ "title": 0 }
 
// False is NOT empty - shows "false"
{ "title": false }

Use Cases

1. User Profiles

<div class="profile">
  <h3 dbind_data="displayName" dbind_default="Anonymous User"></h3>
  <p dbind_data="bio" dbind_default="No bio provided"></p>
  <img dbind_src="avatar" dbind_default="/images/default-avatar.png">
  <span dbind_data="location" dbind_default="Location not set"></span>
</div>

2. Product Information

<div class="product">
  <span class="brand" dbind_data="brand" dbind_default="Generic"></span>
  <span class="warranty" dbind_data="warrantyYears" dbind_default="No warranty"></span>
  <span class="shipping" dbind_data="shippingInfo" dbind_default="Contact for shipping"></span>
</div>

3. Contact Information

<div class="contact">
  <a dbind_href="website" dbind_default="#">
    <span dbind_data="website" dbind_default="No website"></span>
  </a>
  <span dbind_data="phone" dbind_default="Phone not available"></span>
  <span dbind_data="address" dbind_default="Address not provided"></span>
</div>

4. Article Metadata

<article>
  <img dbind_src="featuredImage" dbind_default="/images/placeholder.jpg">
  <span dbind_data="author.name" dbind_default="Staff Writer"></span>
  <span dbind_data="readingTime" dbind_default="5 min read"></span>
</article>

Combining with Other Attributes

<!-- Default with formatting -->
<span
  dbind_data="lastLogin"
  dbind_format="date:relative"
  dbind_default="Never logged in"
></span>
 
<!-- Default with visibility -->
<div dbind_show="hasContact">
  <span dbind_data="email" dbind_default="Email hidden"></span>
</div>

Numeric Zero Handling

Remember that 0 is a valid value, not empty:

<!-- This shows "0", not the default -->
<span dbind_data="quantity" dbind_default="Out of stock"></span>
<!-- When quantity is 0, shows "0" -->
 
<!-- To handle zero specially, use dbind_if -->
<span dbind_if="quantity==0">Out of stock</span>
<span dbind_if="quantity>0" dbind_data="quantity"></span>

Template Syntax in dbind_data

DBindly supports inline template syntax for advanced text composition.

String Interpolation

Use double curly braces within text content:

<p>Hello, {{name}}! Welcome to {{company}}.</p>

Data:

{
  "name": "John",
  "company": "TechCorp"
}

Result:

<p>Hello, John! Welcome to TechCorp.</p>

Concatenation

Combine multiple fields:

<span>{{firstName + ' ' + lastName}}</span>
<span>{{city + ', ' + state + ' ' + zip}}</span>

Inline Filters

Apply filters within templates:

<span>{{price|currency:USD}}</span>
<span>{{createdAt|date:relative}}</span>
<span>{{name|uppercase}}</span>

Special Variables in Loops

Inside dbind_repeat, access special variables:

<div dbind_repeat="items">
  <span>{{_index}}</span>  <!-- 0, 1, 2, ... -->
  <span>{{_number}}</span> <!-- 1, 2, 3, ... -->
</div>

Best Practices

1. Use Semantic HTML

<!-- Good: Semantic elements -->
<h1 dbind_data="title"></h1>
<p dbind_data="description"></p>
<time dbind_data="publishedAt"></time>
 
<!-- Avoid: Generic divs for text -->
<div dbind_data="title"></div>

2. Always Provide Defaults for Optional Fields

<!-- Good: Fallback for missing data -->
<span dbind_data="nickname" dbind_default="No nickname"></span>
 
<!-- Risk: Empty element if data missing -->
<span dbind_data="nickname"></span>

3. Use dbind_data for User Content

<!-- Safe: User content escaped -->
<p dbind_data="userReview"></p>
 
<!-- Dangerous: User content as HTML -->
<p dbind_html="userReview"></p>

4. Structure Data for Easy Access

// Good: Clear hierarchy
{
  "author": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}
 
// Avoid: Flat with prefixes
{
  "author_name": "John Doe",
  "author_email": "john@example.com"
}

Next Steps