Folders¶

The Konigle SDK provides comprehensive folder management for organizing your website content hierarchically. Folders help organize pages, create navigation structures, and manage content categories.

Creating Folders¶

Basic Folder Creation¶

import konigle
from konigle.models.website import FolderCreate, FolderType

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

# Create a simple folder for organizing pages
folder_data = FolderCreate(
    name="Company Info",
    folder_type=FolderType.PAGES
)

folder = client.folders.create(folder_data)
print(f"Created folder: {folder.id}")
print(f"Folder handle: {folder.handle}")  # Auto-generated: "company-info"
print(f"Published: {folder.published}")

Folder with Custom Handle¶

# Create folder with specific handle
folder_data = FolderCreate(
    name="Product Documentation",
    handle="docs",  # Custom short handle
    folder_type=FolderType.PAGES
)

folder = client.folders.create(folder_data)
print(f"Custom handle: {folder.handle}")  # "docs"

Creating Nested Folders¶

# Create parent folder first
parent_folder = client.folders.create(FolderCreate(
    name="Resources",
    folder_type=FolderType.PAGES
))

# Create child folder
child_folder_data = FolderCreate(
    name="Downloads",
    parent=parent_folder.id,  # Reference parent folder
    folder_type=FolderType.PAGES
)

child_folder = client.folders.create(child_folder_data)
print(f"Child folder '{child_folder.name}' created under '{parent_folder.name}'")

Folder with SEO Metadata¶

from konigle.models import SEOMeta

# Create folder with complete SEO metadata
folder_data = FolderCreate(
    name="Customer Support",
    handle="support",
    folder_type=FolderType.PAGES,
    seo_meta=SEOMeta(
        title="Customer Support - Help Center",
        description="Find answers to common questions and get help with our products",
        keywords="support,help,faq,customer service",
        og_title="Customer Support Center",
        og_description="Get the help you need with our comprehensive support resources",
        og_image="https://example.com/support-banner.jpg"
    ),
    json_ld={
        "@context": "https://schema.org",
        "@type": "WebPage",
        "name": "Customer Support",
        "description": "Customer support and help resources"
    },
    tags=["support", "help", "customer-service"],
    language="en",
    country_code="US",
    exclude_from_sitemap=False
)

folder = client.folders.create(folder_data)
print(f"SEO-optimized folder created: {folder.name}")

Different Folder Types¶

# Pages folder for static content
pages_folder = client.folders.create(FolderCreate(
    name="About Us",
    folder_type=FolderType.PAGES
))

# Glossary folder for terms
glossary_folder = client.folders.create(FolderCreate(
    name="Technical Terms",
    folder_type=FolderType.GLOSSARY
))

# Custom folder for mixed content
custom_folder = client.folders.create(FolderCreate(
    name="Resources",
    folder_type=FolderType.CUSTOM
))

# Collection folder for product categories
collection_folder = client.folders.create(FolderCreate(
    name="Product Categories",
    folder_type=FolderType.COLLECTION
))

Listing Folders¶

Basic Folder Listing¶

# List all folders with pagination
folders = client.folders.list(page=1, page_size=20)

print(f"Total folders: {folders.count}")
print(f"Current page: {folders.current_page}")
print(f"Total pages: {folders.num_pages}")

for folder in folders.payload:
    print(f"- {folder.name} ({folder.folder_type})")
    print(f"  Handle: {folder.handle}")
    print(f"  Published: {folder.published}")

Filtering Folders¶

from konigle.filters.website import FolderFilters

# Using filter object (type-safe)
folder_filters = FolderFilters(
    q="support",  # Search in name and handle
    folder_type="pages",
    parent="folder_123",  # Filter by parent folder
    ordering="name"  # Sort by name
)

filtered_folders = client.folders.list(
    page=1,
    page_size=10,
    filters=folder_filters
)

# Using filter kwargs (more concise)
pages_folders = client.folders.list(
    folder_type="pages",
    q="company",
    ordering="-created_at"  # Sort by newest first
)

# Filter by parent folder (get all child folders)
child_folders = client.folders.list(parent="parent_folder_id")

# Search folders by text
search_results = client.folders.list(q="documentation")

Getting Root Folders¶

# Get all root-level folders (no parent)
root_folders = client.folders.list(parent=None)

for folder in root_folders.payload:
    print(f"Root folder: {folder.name}")

Getting a Specific Folder¶

# Get folder by ID
folder = client.folders.get("folder_123456789")
print(f"Folder: {folder.name}")
print(f"Type: {folder.folder_type}")
print(f"Handle: {folder.handle}")
print(f"Language: {folder.language}")
print(f"Tags: {folder.tags}")

Updating Folders¶

from konigle.models.website import FolderUpdate

# Update folder metadata
update_data = FolderUpdate(
    name="Updated Support Center",
    handle="help-center",
    tags=["support", "help", "updated"]
)

updated_folder = client.folders.update("folder_123456789", update_data)
print(f"Updated folder: {updated_folder.name}")

# Update SEO metadata
seo_update = FolderUpdate(
    seo_meta=SEOMeta(
        title="New Support Center Title",
        description="Updated description for better SEO",
        keywords="support,help,customer,service"
    )
)

folder_with_seo = client.folders.update("folder_123456789", seo_update)

Deleting Folders¶

# Delete a folder
success = client.folders.delete("folder_123456789")
if success:
    print("Folder deleted successfully")
else:
    print("Failed to delete folder")

# Note: Check if folder contains content before deleting
# Deleting parent folders may affect navigation structure

Folder Actions¶

Publishing and Unpublishing Folders¶

# Publish a folder to make it visible on your website
folder = client.folders.get("folder_123456789")
published_folder = folder.publish()
print(f"Folder published: {published_folder.published}")

# Or use the manager directly
published_folder = client.folders.publish("folder_123456789")

# Unpublish a folder to hide it from the website
unpublished_folder = folder.unpublish()
print(f"Folder unpublished: {unpublished_folder.published}")

# Or use the manager directly
unpublished_folder = client.folders.unpublish("folder_123456789")

Changing Folder Handles¶

# Change a folder's URL handle
folder = client.folders.get("folder_123456789")

# Change handle without redirect
updated_folder = folder.change_handle("new-folder-handle")
print(f"New handle: {updated_folder.handle}")

# Change handle with redirect from old URL
updated_folder = folder.change_handle("better-handle", redirect=True)
print(f"Handle changed to: {updated_folder.handle}")
print("Redirect created from old handle")

# Get all child folders of a parent
def print_folder_tree(parent_id=None, level=0):
    folders = client.folders.list(parent=parent_id, page_size=100)

    for folder in folders.payload:
        indent = "  " * level
        print(f"{indent}- {folder.name} ({folder.folder_type})")

        # Recursively get child folders
        print_folder_tree(folder.id, level + 1)

# Print entire folder hierarchy
print("Website Structure:")
print_folder_tree()

Iterating All Folders¶

# Memory-efficient iteration over all folders
for folder in client.folders.iter_all(page_size=50):
    print(f"Processing folder: {folder.name}")

# With filtering - get all pages folders
for folder in client.folders.iter_all(page_size=50, folder_type="pages"):
    print(f"Processing pages folder: {folder.name}")

Async Operations¶

import asyncio
import konigle

async def manage_folders():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Create folder
        folder_data = FolderCreate(
            name="Async Support",
            folder_type=FolderType.PAGES
        )
        folder = await client.folders.create(folder_data)

        # List folders with filtering
        folders = await client.folders.list(
            page_size=10,
            folder_type="pages",
            q="support"
        )

        # Update folder
        update_data = FolderUpdate(name="Updated Support Center")
        updated_folder = await client.folders.update(folder.id, update_data)

        # Delete folder
        await client.folders.delete(folder.id)

asyncio.run(manage_folders())

Common Website Folder Structures¶

Company Website Structure¶

# Create typical company website folders
company_folders = [
    ("About Us", "about"),
    ("Services", "services"),
    ("Products", "products"),
    ("Support", "support"),
    ("Resources", "resources")
]

created_folders = []

with konigle.Client(api_key="your-api-key") as client:
    for name, handle in company_folders:
        folder_data = FolderCreate(
            name=name,
            handle=handle,
            folder_type=FolderType.PAGES
        )
        folder = client.folders.create(folder_data)
        created_folders.append(folder)
        print(f"Created: {folder.name}")

Documentation Site Structure¶

# Create documentation folder hierarchy
docs_root = client.folders.create(FolderCreate(
    name="Documentation",
    handle="docs",
    folder_type=FolderType.PAGES
))

# Create subsections
doc_sections = [
    "Getting Started",
    "API Reference",
    "Tutorials",
    "Examples"
]

for section_name in doc_sections:
    section_folder = client.folders.create(FolderCreate(
        name=section_name,
        parent=docs_root.id,
        folder_type=FolderType.PAGES
    ))
    print(f"Created docs section: {section_folder.name}")

Validation Examples¶

# Handle validation - handles must be URL-safe
try:
    # This will raise a validation error
    invalid_folder = FolderCreate(
        name="Invalid Folder",
        handle="invalid handle with spaces"  # Spaces not allowed
    )
except ValueError as e:
    print(f"Validation error: {e}")

# Language code validation
try:
    # This will raise a validation error
    invalid_language = FolderCreate(
        name="Test Folder",
        language="invalid"  # Must be valid ISO language code
    )
except ValueError as e:
    print(f"Language validation error: {e}")

# Valid examples
valid_folder = FolderCreate(
    name="Valid Folder",
    handle="valid-folder-handle",  # URL-safe handle
    language="en",  # Valid ISO language code
    country_code="US"  # Valid ISO country code
)

Error Handling¶

from konigle.exceptions import ValidationError

def create_folder_safely(folder_data: FolderCreate) -> bool:
    try:
        with konigle.Client(api_key="your-api-key") as client:
            folder = client.folders.create(folder_data)
            print(f"Successfully created folder: {folder.id}")
            return True

    except ValidationError as e:
        print(f"Validation failed: {e}")
        return False
    except Exception as e:
        print(f"Unexpected error: {e}")
        return False

# Test folder creation
folder_data = FolderCreate(
    name="Test Folder",
    folder_type=FolderType.PAGES
)

success = create_folder_safely(folder_data)

Best Practices¶

SEO-Optimized Folder Creation¶

def create_seo_folder(name: str, handle: str, description: str, keywords: str):
    """Create a folder with SEO optimization."""
    return FolderCreate(
        name=name,
        handle=handle,
        folder_type=FolderType.PAGES,
        seo_meta=SEOMeta(
            title=f"{name} | Your Company",
            description=description,
            keywords=keywords,
            og_title=name,
            og_description=description
        ),
        exclude_from_sitemap=False,
        language="en",
        country_code="US"
    )

# Usage
support_folder = create_seo_folder(
    name="Customer Support",
    handle="support",
    description="Get help and support for our products and services",
    keywords="support,help,customer service,faq"
)

Folder Hierarchy Planning¶

# Plan your folder structure before creation
def create_site_structure():
    """Create a complete site folder structure."""

    # Main navigation folders
    main_folders = {
        "About": {"handle": "about", "description": "Learn about our company"},
        "Services": {"handle": "services", "description": "Our professional services"},
        "Resources": {"handle": "resources", "description": "Helpful resources and tools"}
    }

    with konigle.Client(api_key="your-api-key") as client:
        created = {}

        # Create main folders
        for name, config in main_folders.items():
            folder = client.folders.create(FolderCreate(
                name=name,
                handle=config["handle"],
                folder_type=FolderType.PAGES,
                seo_meta=SEOMeta(
                    description=config["description"]
                )
            ))
            created[name] = folder
            print(f"Created main folder: {name}")

        # Create subfolders under Resources
        resources_subfolders = ["Downloads", "Guides", "FAQ"]
        for subfolder_name in resources_subfolders:
            subfolder = client.folders.create(FolderCreate(
                name=subfolder_name,
                parent=created["Resources"].id,
                folder_type=FolderType.PAGES
            ))
            print(f"Created subfolder: {subfolder_name} under Resources")

    return created

# Execute structure creation
site_folders = create_site_structure()

Folders¶

Creating Folders¶

Basic Folder Creation¶

Folder with Custom Handle¶

Creating Nested Folders¶

Folder with SEO Metadata¶

Different Folder Types¶

Listing Folders¶

Basic Folder Listing¶

Filtering Folders¶

Getting Root Folders¶

Getting a Specific Folder¶

Updating Folders¶

Deleting Folders¶

Folder Actions¶

Publishing and Unpublishing Folders¶

Changing Folder Handles¶

Folder Hierarchy Navigation¶

Iterating All Folders¶

Async Operations¶

Common Website Folder Structures¶

Company Website Structure¶

Documentation Site Structure¶

Validation Examples¶

Error Handling¶

Best Practices¶

SEO-Optimized Folder Creation¶

Folder Hierarchy Planning¶