CLI commands

These are the Django management commands that installing django_components adds. All of them live under the components command.

components

usage: python manage.py components [-h] {create,upgrade,ext,list} ...

See source code

The entrypoint for the 'components' commands.

Options

-h, --help – show this help message and exit

Subcommands

create – Create a new django component.
upgrade – Upgrade django components syntax from '{% component_block ... %}' to '{% component ... %}'.
ext – Run extension commands.
list – List all components created in this project.

The entrypoint for the "components" commands.

python manage.py components list
python manage.py components create <name>
python manage.py components upgrade
python manage.py components ext list
python manage.py components ext run <extension> <command>

components create

usage: python manage.py components create [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE]
              [--force] [--verbose] [--dry-run]
              name

See source code

Create a new django component.

Positional Arguments

name – The name of the component to create. This is a required argument.

Options

-h, --help – show this help message and exit
--path PATH – The path to the component's directory. This is an optional argument. If not provided, the command will use the `COMPONENTS.dirs` setting from your Django settings.
--js JS – The name of the JavaScript file. This is an optional argument. The default value is `script.js`.
--css CSS – The name of the CSS file. This is an optional argument. The default value is `style.css`.
--template TEMPLATE – The name of the template file. This is an optional argument. The default value is `template.html`.
--force – This option allows you to overwrite existing files if they exist. This is an optional argument.
--verbose – This option allows the command to print additional information during component creation. This is an optional argument.
--dry-run – This option allows you to simulate component creation without actually creating any files. This is an optional argument. The default value is `False`.

Usage

To use the command, run the following command in your terminal:

python manage.py components create <name> --path <path> --js <js_filename> --css <css_filename> --template <template_filename> --force --verbose --dry-run

Replace <name>, <path>, <js_filename>, <css_filename>, and <template_filename> with your desired values.

Examples

Here are some examples of how you can use the command:

Creating a Component with Default Settings

To create a component with the default settings, you only need to provide the name of the component:

python manage.py components create my_component

This will create a new component named my_component in the components directory of your Django project. The JavaScript, CSS, and template files will be named script.js, style.css, and template.html, respectively.

Creating a Component with Custom Settings

You can also create a component with custom settings by providing additional arguments:

python manage.py components create new_component --path my_components --js my_script.js --css my_style.css --template my_template.html

This will create a new component named new_component in the my_components directory. The JavaScript, CSS, and template files will be named my_script.js, my_style.css, and my_template.html, respectively.

Overwriting an Existing Component

If you want to overwrite an existing component, you can use the --force option:

python manage.py components create my_component --force

This will overwrite the existing my_component if it exists.

Simulating Component Creation

If you want to simulate the creation of a component without actually creating any files, you can use the --dry-run option:

python manage.py components create my_component --dry-run

This will simulate the creation of my_component without creating any files.

components upgrade

usage: python manage.py components upgrade [-h] [--path PATH]

See source code

Upgrade django components syntax from '{% component_block ... %}' to '{% component ... %}'.

Options

-h, --help – show this help message and exit
--path PATH – Path to search for components

components ext

usage: python manage.py components ext [-h] {list,run} ...

See source code

Run extension commands.

Options

-h, --help – show this help message and exit

Subcommands

list – List all extensions.
run – Run a command added by an extension.

Run extension commands.

python manage.py components ext list
python manage.py components ext run <extension> <command>

components ext list

usage: python manage.py components ext list [-h] [--all] [--columns COLUMNS] [-s]

See source code

List all extensions.

Options

-h, --help – show this help message and exit
--all – Show all columns. Same as `--columns name`.
--columns COLUMNS – Comma-separated list of columns to show. Available columns: name. Defaults to `--columns name`.
-s, --simple – Only show table data, without headers. Use this option for generating machine-readable output.

List all extensions.

python manage.py components ext list

Prints the list of installed extensions:

name
==============
view
my_extension

To specify which columns to show, use the --columns flag:

python manage.py components ext list --columns name

Which prints:

name
==============
view
my_extension

To print out all columns, use the --all flag:

python manage.py components ext list --all

If you need to omit the title in order to programmatically post-process the output, you can use the --simple (or -s) flag:

python manage.py components ext list --simple

Which prints just:

view
my_extension

components ext run

usage: python manage.py components ext run [-h]

See source code

Run a command added by an extension.

Options

-h, --help – show this help message and exit

Run a command added by an extension.

Each extension can add its own commands, which will be available to run with this command.

For example, if you define and install the following extension:

from django_components import ComponentCommand, ComponentExtension

class HelloCommand(ComponentCommand):
    name = "hello"
    help = "Say hello"
    def handle(self, *args, **kwargs):
        print("Hello, world!")

class MyExt(ComponentExtension):
    name = "my_ext"
    commands = [HelloCommand]

You can run the hello command with:

python manage.py components ext run my_ext hello

You can also define arguments for the command, which will be passed to the command's handle method.

from django_components import CommandArg, ComponentCommand, ComponentExtension

class HelloCommand(ComponentCommand):
    name = "hello"
    help = "Say hello"
    arguments = [
        CommandArg(name="name", help="The name to say hello to"),
        CommandArg(name=["--shout", "-s"], action="store_true"),
    ]

    def handle(self, name: str, *args, **kwargs):
        shout = kwargs.get("shout", False)
        msg = f"Hello, {name}!"
        if shout:
            msg = msg.upper()
        print(msg)

You can run the command with:

python manage.py components ext run my_ext hello --name John --shout

Note

Command arguments and options are based on Python's argparse module.

For more information, see the argparse documentation.

components list

usage: python manage.py components list [-h] [--all] [--columns COLUMNS] [-s]

See source code

List all components created in this project.

Options

-h, --help – show this help message and exit
--all – Show all columns. Same as `--columns name,full_name,path`.
--columns COLUMNS – Comma-separated list of columns to show. Available columns: name, full_name, path. Defaults to `--columns full_name,path`.
-s, --simple – Only show table data, without headers. Use this option for generating machine-readable output.

List all components.

python manage.py components list

Prints the list of available components:

full_name                                                     path
==================================================================================================
project.pages.project.ProjectPage                             ./project/pages/project
project.components.dashboard.ProjectDashboard                 ./project/components/dashboard
project.components.dashboard_action.ProjectDashboardAction    ./project/components/dashboard_action

To specify which columns to show, use the --columns flag:

python manage.py components list --columns name,full_name,path

Which prints:

name                      full_name                                                     path
==================================================================================================
ProjectPage               project.pages.project.ProjectPage                             ./project/pages/project
ProjectDashboard          project.components.dashboard.ProjectDashboard                 ./project/components/dashboard
ProjectDashboardAction    project.components.dashboard_action.ProjectDashboardAction    ./project/components/dashboard_action

To print out all columns, use the --all flag:

python manage.py components list --all

If you need to omit the title in order to programmatically post-process the output, you can use the --simple (or -s) flag:

python manage.py components list --simple

Which prints just:

ProjectPage               project.pages.project.ProjectPage                             ./project/pages/project
ProjectDashboard          project.components.dashboard.ProjectDashboard                 ./project/components/dashboard
ProjectDashboardAction    project.components.dashboard_action.ProjectDashboardAction    ./project/components/dashboard_action