Components

Declaring and Using Components ¶

Components are simple text files that look like regular Jinja templates, with three requirements:

First, components must be placed inside a folder registered in the catalog or a subfolder of it.

catalog.add_folder("myapp/components")

You can name that folder whatever you want (not just "components"). You can also add more than one folder:

catalog.add_folder("myapp/layouts")
catalog.add_folder("myapp/components")

If you end up having more than one component with the same name, the one in the first folder will take priority.

Second, they must have a ".jinja" extension. This also helps code editors automatically select the correct language syntax for highlighting. However, you can configure this extension in the catalog.

Third, the filename must be either PascalCased (like Python classes) or "kebab-cased" (lowercase with words separated by dashes).

The PascalCased name of the file (minus the extension) is always how you call the component (even if the filename is kebab-cased). This is how JinjaX differentiates a component from a regular HTML tag when using it.

For example, if the file is "components/PersonForm.jinja":

└ myapp/
  ├── app.py
  ├── components/
        └─ PersonForm.jinja

The name of the component is "PersonForm" and can be called like this:

From Python code or a non-component template:

• catalog.render("PersonForm")

From another component:

• <PersonForm> some content </PersonForm>, or
• <PersonForm />

If you prefer you can also choose to use kebab-cased filenames:

└ myapp/
  ├── app.py
  ├── components/
        └─ person-form.jinja

The name of the component will still be "PersonForm" and you will use it in the same way as before.

If the component is in a subfolder, the name of that folder becomes part of its name too:

└ myapp/
  ├── app.py
  ├── components/
        └─ person
            └─ PersonForm.jinja

A "components/person/PersonForm.jinja" component is named "person.PersonForm", meaning the name of the subfolder and the name of the file separated by a dot. This is the full name you use to call it:

From Python code or a non-component template:

• catalog.render("person.PersonForm")

From another component:

• <person.PersonForm> some content </person.PersonForm>, or
• <person.PersonForm />

Notice that the folder name doesn't need to follow any naming convention if you don't want it to.