Welcome to the C4A-Script Interactive Tutorial! This hands-on tutorial teaches you how to write web automation scripts using C4A-Script, a domain-specific language for Crawl4AI.

🚀 Quick Start

1. Start the Tutorial Server

cd docs/examples/c4a_script/tutorial
python server.py

Then open your browser to: http://localhost:8080

2. Try Your First Script

# Basic interaction
GO playground/
WAIT `body` 2
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
CLICK `#start-tutorial`

📚 What You'll Learn

Basic Commands

Navigation: GO url
Waiting: WAIT selector timeout or WAIT seconds
Clicking: CLICK selector
Typing: TYPE "text"
Scrolling: SCROLL DOWN/UP amount

Control Flow

Conditionals: IF (condition) THEN action
Loops: REPEAT (action, condition)
Procedures: Define reusable command sequences

Advanced Features

JavaScript evaluation: EVAL code
Variables: SET name = "value"
Complex selectors: CSS selectors in backticks

🎮 Interactive Playground Features

The tutorial includes a fully interactive web app with:

1. Authentication System

Login form with validation
Session management
Protected content

2. Dynamic Content

Infinite scroll products
Pagination controls
Load more buttons

3. Complex Forms

Multi-step wizards
Dynamic field visibility
Form validation

4. Interactive Elements

Tabs and accordions
Modals and popups
Expandable content

5. Data Tables

Sortable columns
Search functionality
Export options

🛠️ Tutorial Features

Live Code Editor

Syntax highlighting
Real-time compilation
Error messages with suggestions

JavaScript Output Viewer

See generated JavaScript code
Edit and test JS directly
Understand the compilation

Visual Execution

Step-by-step progress
Element highlighting
Console output

Example Scripts

Load pre-written examples demonstrating:

Cookie banner handling
Login workflows
Infinite scroll automation
Multi-step form completion
Complex interaction sequences

📖 Tutorial Sections

1. Getting Started

Learn basic commands and syntax:

GO https://example.com
WAIT `.content` 5
CLICK `.button`

2. Handling Dynamic Content

Master waiting strategies and conditionals:

IF (EXISTS `.popup`) THEN CLICK `.close`
WAIT `.results` 10

3. Form Automation

Fill and submit forms:

CLICK `#email`
TYPE "user@example.com"
CLICK `button[type="submit"]`

4. Advanced Workflows

Build complex automation flows:

PROC login
  CLICK `#username`
  TYPE $username
  CLICK `#password`
  TYPE $password
  CLICK `#login-btn`
ENDPROC

SET username = "demo"
SET password = "pass123"
login

🎯 Practice Challenges

Handle the cookie banner and newsletter popup that appear on page load.

Successfully log into the application using the demo credentials.

Challenge 3: Load All Products

Use infinite scroll to load all 100 products in the catalog.

Challenge 4: Multi-step Survey

Complete the entire multi-step survey form.

Challenge 5: Full Workflow

Create a script that logs in, browses products, and exports data.

💡 Tips & Tricks

1. Use Specific Selectors

# Good - specific
CLICK `button.submit-order`

# Bad - too generic
CLICK `button`

2. Always Handle Popups

# Check for common popups
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
IF (EXISTS `.newsletter-modal`) THEN CLICK `.close`

3. Add Appropriate Waits

# Wait for elements before interacting
WAIT `.form` 5
CLICK `#submit`

4. Use Procedures for Reusability

PROC handle_popups
  IF (EXISTS `.popup`) THEN CLICK `.close`
  IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
ENDPROC

# Use anywhere
handle_popups

🔧 Troubleshooting

Common Issues

"Element not found"
- Add a WAIT before clicking
- Check selector specificity
- Verify element exists with IF
"Timeout waiting for selector"
- Increase timeout value
- Check if element is dynamically loaded
- Verify selector is correct
"Missing THEN keyword"
- All IF statements need THEN
- Format: IF (condition) THEN action

🚀 Using with Crawl4AI

Once you've mastered C4A-Script in the tutorial, use it with Crawl4AI:

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig

config = CrawlerRunConfig(
    url="https://example.com",
    c4a_script="""
    WAIT `.content` 5
    IF (EXISTS `.load-more`) THEN CLICK `.load-more`
    WAIT `.new-content` 3
    """
)

async with AsyncWebCrawler() as crawler:
    result = await crawler.arun(config=config)

📝 Example Scripts

Check the scripts/ folder for complete examples:

01-basic-interaction.c4a - Getting started
02-login-flow.c4a - Authentication
03-infinite-scroll.c4a - Dynamic content
04-multi-step-form.c4a - Complex forms
05-complex-workflow.c4a - Full automation

🤝 Contributing

Found a bug or have a suggestion? Please open an issue on GitHub!

Happy automating with C4A-Script! 🎉

README.md

C4A-Script Interactive Tutorial