Blocks

Check you have labb installed

Blocks require a labb.yaml in the project root. If your project does not have one, start with Installation.

labb init --defaults   # only if labb.yaml does not exist

--defaults creates labb.yaml and the CSS starter files without asking configuration questions.

Find a block

Browse the block gallery or search from the command line. Block references follow vendor/category/slug; the official collection uses lb.

labb block list
labb block search "table"

Each result includes its reference and type.

Create a collection

A collection is a Django app that holds the blocks you install. labb block add creates the default collection automatically when one does not exist, so run this step only when you want to choose its name or path.

labb block init --name blocks

This command adds the collection and the official source to labb.yaml.

blocks:
  collections:
    - default: true
      name: blocks
      path: blocks
  sources:
    - name: labbhq
      url: https://github.com/labbhq/labb
      subdir: extras/blocks

A source is a git repository containing blocks.yaml and index.yaml. When the collection lives inside a larger repository, subdir points at it. The official collection ships from extras/blocks in the labb monorepo.

Add the block

labb block add lb/data-table/customers

labb block add creates the default blocks collection and adds the official source when they are missing. Otherwise it copies the block files into the existing collection.

See what changed

After installation, the collection contains the copied block files.

myproject/                      myproject/
  manage.py                       manage.py
  labb.yaml                       labb.yaml
  myapp/                          myapp/
  templates/                      templates/
                                  blocks/                   <- the collection
                                    apps.py
                                    migrations/
                                    fixtures/lb.json        <- seed data
                                    models/__init__.py      <- imports the vendor models
                                    lb/
                                      models/               <- shared vendor models
                                      data-table/customers/
                                        block.yaml
                                        views.py
                                        urls.py
                                        tour.yaml
                                    templates/
                                      cotton/customers/     <- components, resolve everywhere
                                      lb/data-table/customers/pages/index.html

For a fullstack block, models/__init__.py imports the vendor models so Django discovers them. fixtures/lb.json uses your collection’s app label.

Wire it up

Add the collection to INSTALLED_APPS:

INSTALLED_APPS = [
    # ... other apps
    'labb',
    'blocks',
]

Use include_blocks to include the block routes.

from labb.contrib.blocks import include_blocks
import blocks

urlpatterns = [
    path("", include_blocks(blocks)),
]

For a fullstack block, create the tables and load the seed data:

python manage.py makemigrations blocks
python manage.py migrate
python manage.py loaddata lb

Run it

labb dev                    # CSS watcher
python manage.py runserver

Open the block’s page. A fullstack block now runs against your database, including its search, sorting, and pagination.