django-components/docs/overview/installation.md at dfd4187192726b02bf41059c8a4cb1adc559adcd

mirror of https://github.com/django-components/django-components.git synced 2025-11-22 07:27:24 +00:00

* Move docs-folder form src to root

* Avoid mkdocs package / module name clash

* Update location of docs & add Windows compatibility

* Update requirements-docs

* Update generated file to current state

2024-12-03 12:32:21 +01:00

5 KiB

Raw Blame History

title	weight
Installation	3

Install django_components into your environment:
```
pip install django_components
```
Load django_components into Django by adding it into INSTALLED_APPS in settings.py:
```
INSTALLED_APPS = [
    ...,
    'django_components',
]
```

BASE_DIR setting is required. Ensure that it is defined in settings.py:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

Add / modify COMPONENTS.dirs and / or COMPONENTS.app_dirs so django_components knows where to find component HTML, JS and CSS files:
```
from django_components import ComponentsSettings

COMPONENTS = ComponentsSettings(
    dirs=[
            ...,
            Path(BASE_DIR) / "components",
        ],
)
```
If COMPONENTS.dirs is omitted, django-components will by default look for a top-level /components directory, {BASE_DIR}/components.

In addition to COMPONENTS.dirs, django_components will also load components from app-level directories, such as my-app/components/. The directories within apps are configured with COMPONENTS.app_dirs, and the default is [app]/components.

NOTE: The input to COMPONENTS.dirs is the same as for STATICFILES_DIRS, and the paths must be full paths. See Django docs.

Next, to make Django load component HTML files as Django templates, modify TEMPLATES section of settings.py as follows:

Remove 'APP_DIRS': True,
- NOTE: Instead of APP_DIRS, for the same effect, we will use django.template.loaders.app_directories.Loader
Add loaders to OPTIONS list and set it to following value:

TEMPLATES = [
    {
        ...,
        'OPTIONS': {
            'context_processors': [
                ...
            ],
            'loaders':[(
                'django.template.loaders.cached.Loader', [
                    # Default Django loader
                    'django.template.loaders.filesystem.Loader',
                    # Inluding this is the same as APP_DIRS=True
                    'django.template.loaders.app_directories.Loader',
                    # Components loader
                    'django_components.template_loader.Loader',
                ]
            )],
        },
    },
]

Adding support for JS and CSS

If you want to use JS or CSS with components, you will need to:

Modify STATICFILES_FINDERS section of settings.py as follows to be able to serve the component JS and CSS files as static files:

STATICFILES_FINDERS = [
    # Default finders
    "django.contrib.staticfiles.finders.FileSystemFinder",
    "django.contrib.staticfiles.finders.AppDirectoriesFinder",
    # Django components
    "django_components.finders.ComponentsFileSystemFinder",
]

Add ComponentDependencyMiddleware to MIDDLEWARE setting.

The middleware searches the outgoing HTML for all components that were rendered to generate the HTML, and adds the JS and CSS associated with those components.
```
MIDDLEWARE = [
    ...
    "django_components.middleware.ComponentDependencyMiddleware",
]
```
Read more in Rendering JS/CSS dependencies.

Add django-component's URL paths to your urlpatterns:

from django.urls import include, path

urlpatterns = [
    ...
    path("", include("django_components.urls")),
]

Optional. If you want to change where the JS and CSS is rendered, use {% component_js_dependencies %} and {% component_css_dependencies %}.

By default, the JS <script> and CSS <link> tags are automatically inserted into the HTML (See JS and CSS output locations).
```
<!doctype html>
<html>
  <head>
    ...
    {% component_css_dependencies %}
  </head>
  <body>
    ...
    {% component_js_dependencies %}
  </body>
</html>
```

Optional

To avoid loading the app in each template using {% load component_tags %}, you can add the tag as a 'builtin' in settings.py

TEMPLATES = [
    {
        ...,
        'OPTIONS': {
            'context_processors': [
                ...
            ],
            'builtins': [
                'django_components.templatetags.component_tags',
            ]
        },
    },
]

Read on to find out how to build your first component!

5 KiB Raw Blame History

Adding support for JS and CSS

Optional

5 KiB

Raw Blame History