Components¶

Components are reusable UI building blocks for creating landing pages and templates. They contain HTML templates with Django templating syntax and can be created as either standard components or widgets. Component creation is simplified to just the essential fields: name, description, version, and template HTML.

Basic Component Management¶

Creating Components¶

Create a basic component:

import konigle

# Initialize client
client = konigle.Client(api_key="your-api-key")

# Create a simple component
component_data = konigle.models.ComponentCreate(
    name="Hero Section",
    description="A responsive hero section component",
    version="1.0.0",
    template_html="<div class='hero'>{{config.title}}</div>",
)

component = client.components.create(component_data)
print(f"Created component: {component.id}")

The template_html can be a plain HTML or a Django template. The HTML must use Tailwind CSS classes for styling if the website does not include its own CSS. The HTML should be a partial snippet without <html>, <head>, or <body> tags.

Retrieve Components¶

Get a specific component:

import konigle

client = konigle.Client(api_key="your-api-key")

# Get component by ID
component = client.components.get("comp_123456789")
print(f"Component: {component.name}")
print(f"Type: {component.type}")
print(f"Version: {component.version}")
print(f"Description: {component.description}")

component.load_details()  # Load detail-only fields

print(f"Template HTML: {component.template_html}")

List and Filter Components¶

List components with filtering:

import konigle
from konigle.filters.website import ComponentFilters

client = konigle.Client(api_key="your-api-key")

# List all components
components = client.components.list()
print(f"Found {len(components.payload)} components")

# Filter by component type
filters = ComponentFilters(type="component,widget")
filtered_components = client.components.list(filters=filters)
print(f"Found {len(filtered_components.payload)} components")

# Search components by name
filters = ComponentFilters(q="hero")
hero_components = client.components.list(filters=filters)

# Combine filters with pagination
filters = ComponentFilters(
    q="card",
    ordering="-created_at"  # Most recent first
)
recent_cards = client.components.list(page=1, page_size=5, filters=filters)
print(f"Page {recent_cards.current_page} of {recent_cards.num_pages}")

Component Types and Use Cases¶

Standard Components¶

Standard components are flexible building blocks with configurable content:

import konigle

client = konigle.Client(api_key="your-api-key")

# Create a testimonial component
testimonial_data = konigle.models.ComponentCreate(
    name="Customer Testimonial",
    description="Customer testimonial card with star rating",
    template_html="""
    <div class="testimonial">
        <div class="testimonial-content">
            <p>"{{config.testimonial}}"</p>
            <div class="rating-stars">
                {% for i in range(config.rating) %}
                    <span class="star">★</span>
                {% endfor %}
            </div>
        </div>
        <div class="customer-info">
            <img src="{{config.avatar_url}}" alt="{{config.customer_name}}" class="avatar">
            <div>
                <h4>{{config.customer_name}}</h4>
                <p>{{config.customer_title}}</p>
            </div>
        </div>
    </div>
    """,
)

testimonial = client.components.create(testimonial_data)

Widget components are self-contained interactive elements:

import konigle

client = konigle.Client(api_key="your-api-key")

# Create a contact form widget
contact_form_data = konigle.models.ComponentCreate(
    name="Contact Form",
    description="Contact form with email validation",
    template_html="""
    <form class="contact-form" action="/contact" method="post">
        <div class="form-group">
            <label for="name">Name:</label>
            <input type="text" id="name" name="name" required>
        </div>
        <div class="form-group">
            <label for="email">Email:</label>
            <input type="email" id="email" name="email" required>
        </div>
        <div class="form-group">
            <label for="message">Message:</label>
            <textarea id="message" name="message" rows="5" required></textarea>
        </div>
        <button type="submit" class="submit-btn">Send Message</button>
    </form>
    """,
)

# Create as widget type
widget = client.components.create(contact_form_data, type_="widget")
print(f"Created widget: {widget.name}")

Advanced Component Features¶

Update Component Content¶

Update an existing component:

import konigle

client = konigle.Client(api_key="your-api-key")

# Update component with new template and description
update_data = konigle.models.ComponentUpdate(
    description="Updated product card with enhanced styling",
    template_html="""
    <div class="product-card featured">
        <div class="featured-badge">Featured</div>
        <h3 class="product-title">{{config.title}}</h3>
        <p class="product-description">{{config.description}}</p>
        <div class="product-price">${{config.price}}</div>
        <button class="product-cta btn-primary">{{config.cta_text}}</button>
    </div>
    """,
    version="1.3.0",
)

updated_component = client.components.update("comp_123456789", update_data)
print(f"Updated component to version: {updated_component.version}")

Advanced Template HTML¶

Create components with complex template structures:

import konigle

client = konigle.Client(api_key="your-api-key")

# Create feature card component
card_data = konigle.models.ComponentCreate(
    name="Feature Card",
    description="Feature highlight card with icon and description",
    template_html="""
    <div class="feature-card{% if config.highlighted %} feature-card--highlighted{% endif %}">
        <div class="feature-card__icon">
            <i class="{{config.icon_class}} icon-large"></i>
        </div>
        <h3 class="feature-card__title">{{config.title}}</h3>
        <p class="feature-card__description">{{config.description}}</p>
        <a href="#" class="feature-card__cta btn btn--primary">{{config.cta_text}}</a>
    </div>
    """,
)

feature_card = client.components.create(card_data)

Component Management Operations¶

Delete Components¶

Remove components that are no longer needed:

import konigle

client = konigle.Client(api_key="your-api-key")

# Delete a specific component
try:
    client.components.delete("comp_123456789")
    print("Component deleted successfully")
except Exception as e:
    print(f"Error deleting component: {e}")

# Bulk cleanup of test components
from konigle.filters.website import ComponentFilters

# Find test components
test_filters = ComponentFilters(q="test", ordering="created_at")
test_components = client.components.list(test_filters)

# Delete test components
for component in test_components.payload:
    if "test" in component.name.lower():
        client.components.delete(component.id)
        print(f"Deleted test component: {component.name}")

Async Usage¶

All component operations support async usage:

import asyncio
import konigle

async def manage_components():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Create component asynchronously
        component_data = konigle.models.ComponentCreate(
            name="Async Hero",
            description="Hero section created asynchronously",
            template_html="<div class='hero'>{{config.title}}</div>"
        )

        component = await client.components.create(component_data)
        print(f"Created async component: {component.id}")

        # List components asynchronously
        components = await client.components.list()
        print(f"Found {len(components.payload)} total components")

        # Update asynchronously
        update_data = konigle.models.ComponentUpdate(
            description="Updated async hero section"
        )
        updated = await client.components.update(component.id, update_data)

        return updated

# Run async function
asyncio.run(manage_components())

CLI Usage¶

Use the CLI for quick component management:

# Create a component with inline HTML
konigle components create \
  --name "CTA Button" \
  --description "Call to action button component" \
  --type widget \
  --version 1.0.0 \
  --template-html '<button class="btn btn-primary">{{config.text}}</button>'

# Create component from HTML file
konigle components create \
  --name "Hero Section" \
  --description "Hero banner with background" \
  --template-file ./templates/hero.html

# List components with pagination
konigle components list --type component --query hero --page 1 --page-size 10

# Get component details
konigle components get comp_123456789

# Update component with new template file
konigle components update comp_123456789 \
  --name "Updated CTA Button" \
  --version 1.1.0 \
  --template-file ./templates/updated-cta.html

# Delete component
konigle components delete comp_123456789 --confirm

Components provide the foundation for building dynamic, reusable landing pages and website templates in the Konigle platform.