mirrors/django-components
1
0
Fork 0
mirror of https://github.com/django-components/django-components.git synced 2025-08-09 00:37:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
django-components/docs/overview/installation.md

5.5 KiB
Raw Blame History

title weight
Installation 3

  1. Install django_components into your environment:

    pip install django_components

  2. Load django_components into Django by adding it into INSTALLED_APPS in in your settings file:

    INSTALLED_APPS = [
    ...,
    'django_components',
]

  3. BASE_DIR setting is required. Ensure that it is defined:

    from pathlib import Path

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

  4. Set 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`](../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs)
 is the same as for `STATICFILES_DIRS`, and the paths must be full paths.
 [See Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#staticfiles-dirs).

  5. Next, modify TEMPLATES section of settings.py as follows:

    This allows Django load component HTML files as Django templates.

    TEMPLATES = [
    {
        ...,
        'OPTIONS': {
            '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:

  1. Add "django_components.finders.ComponentsFileSystemFinder" to STATICFILES_FINDERS in your settings file.

    This allows Django to serve component JS and CSS as static files.

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

  2. 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.

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

    from django.urls import include, path

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

  4. 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': {
            'builtins': [
                'django_components.templatetags.component_tags',
            ]
        },
    },
]

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