Hello sparQ

Build your first sparQ app in 10 minutes.

In this tutorial, you'll create a simple app from scratch. By the end, you'll have a working sparQ app that displays a welcome message and responds to user input.

Prerequisites: Make sure you have sparQ installed and running. If not, follow the Quick Start guide first.

What You'll Build

A simple "Hello sparQ" app that:

Shows a welcome page with your app name
Has a form where users can enter their name
Displays a personalized greeting

Image: Preview of the finished Hello sparQ app

Step 1: Create the App

Open your terminal and navigate to your sparQ installation directory. Run the scaffold command:

cd sdk
make app name=hello

This creates a new app in data/modules/apps/hello/ with the basic structure:

hello/ ├── controllers/ │ └── main.py ├── views/ │ ├── templates/ │ │ └── hello/ │ │ ├── desktop/ │ │ │ └── index.html │ │ └── mobile/ │ │ └── index.html │ └── assets/ │ └── css/ ├── __manifest__.py └── module.py

Step 2: Configure the Manifest

Open hello/__manifest__.py. This file tells sparQ about your app:

# hello/__manifest__.py
manifest = {
    # Required fields
    "name": "Hello",           # Display name (PascalCase)
    "version": "1.0",          # Semantic version
    "mappid": "a1b2c3",        # Marketplace app ID (auto-generated)
    "main_route": "/hello",    # URL slug (used in /m/{mappid}/{main_route})
    "type": "App",             # "App" (visible) or "System" (hidden)
    "depends": ["core"],       # Module dependencies
    # Display fields
    "icon_class": "fa-solid fa-hand",  # FontAwesome icon class
    "color": "#10B981",                # Theme color (green)
    "description": "My first sparQ app",
    "long_description": "A simple hello world app to learn sparQ development.",
}

The mappid is a unique 6-character identifier auto-generated by the SDK. Your app will be accessible at /m/{mappid}/hello.

The main_route is your app's URL slug. The depends array lists modules your app requires (almost all apps need core).

Step 3: Create the Controller

Controllers handle HTTP requests and return responses. Open hello/controllers/main.py:

# hello/controllers/main.py
from flask import Blueprint, request
from system.device.template import render_device_template

bp = Blueprint('main', __name__, url_prefix='/hello')

@bp.route('/')
def index():
    name = request.args.get('name', '')
    return render_device_template('hello/desktop/index.html', name=name)

This creates a route at /hello/ that:

Checks if a name parameter was passed in the URL
Renders the index.html template with that name

We use render_device_template instead of Flask's render_template. This function automatically serves the mobile version of a template when viewed on a mobile device, falling back to the desktop version if no mobile template exists. Templates go in the desktop/ subfolder; mobile templates are optional.

Step 4: Build the View

Views are Jinja2 templates that define what users see. Open hello/views/templates/hello/desktop/index.html:

{% extends "core/desktop/base.html" %}

{% block content %}
<div class="container py-4">
    <div class="card">
        <div class="card-body text-center">
            <h1 class="mb-4">
                {% if name %}
                    Hello, {{ name }}!
                {% else %}
                    Hello, sparQ!
                {% endif %}
            </h1>

            <p class="text-muted mb-4">Welcome to your first sparQ app.</p>

            <form method="GET" class="d-inline-flex gap-2">
                <input type="text" name="name" class="form-control"
                       placeholder="Enter your name" value="{{ name }}">
                <button type="submit" class="btn btn-primary">
                    Say Hello
                </button>
            </form>
        </div>
    </div>
</div>
{% endblock %}

The template extends core/desktop/base.html (sparQ's main layout) and:

Shows "Hello, [name]!" if a name was provided, otherwise "Hello, sparQ!"
Includes a form to enter a name
Uses Bootstrap classes for styling

Step 5: Run Your App

Restart sparQ to load your new app:

make run

Open your browser and navigate to http://localhost:8000. You should see your new "Hello" app in the sidebar. Click it!

Image: The Hello app appearing in sparQ's sidebar

Step 6: Test It Out

Try entering your name in the form and clicking "Say Hello". The page should greet you personally!

Image: The personalized greeting after entering a name

What You Learned

Congratulations! You just built your first sparQ app. Here's what you accomplished:

Scaffolded an app using cd sdk && make app
Configured the manifest with mappid and app metadata
Created a controller to handle HTTP requests
Built a view using Jinja2 templates
Used Bootstrap for styling

Next Steps

Ready to learn more? Continue to the Core Concepts to understand how sparQ works under the hood: