-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
c557a83
commit 1bc9d2b
Showing
5 changed files
with
151 additions
and
47 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| # Configuration | ||
|
|
||
| Configuration of django-bird is done through a `DJANGO_BIRD` dictionary in your Django settings. | ||
|
|
||
| All settings are optional. Here is an example configuration with the types and default values shown: | ||
|
|
||
| ```{code-block} python | ||
| :caption: settings.py | ||
| from pathlib import Path | ||
| DJANGO_BIRD = { | ||
| "COMPONENT_DIRS": list[Path | str] = [], | ||
| "ENABLE_AUTO_CONFIG": bool = True, | ||
| } | ||
| ``` | ||
|
|
||
| ## `COMPONENT_DIRS` | ||
|
|
||
| Additional directories to scan for components. Takes a list of paths relative to the base directory of your project's templates directory. A path can either be a `str` or `Path`. | ||
|
|
||
| By default, django-bird will look for components in a `bird` directory. Any directories specified here will take precedence and take priority when performing template resolution for components. | ||
|
|
||
| ### Example | ||
|
|
||
| Suppose you want to store your components in a `components` directory, you're using a third-party library that provides its own bird components, and you have an alternate templates directory. | ||
|
|
||
| You can configure django-bird to look in all these locations: | ||
|
|
||
| ```{code-block} python | ||
| :caption: settings.py | ||
| from pathlib import Path | ||
| BASE_DIR = Path(__file__).resolve(strict=True).parent | ||
| DJANGO_BIRD = { | ||
| "COMPONENT_DIRS": [ | ||
| "components", | ||
| Path("third_party_library/components"), | ||
| BASE_DIR / "alternate_templates" / "bird", | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| In this configuration: | ||
|
|
||
| - `"components"` is a string path relative to your project's templates directory. | ||
| - `Path("third_party_library/components")` uses the `Path` object for the third-party library's components. | ||
| - `BASE_DIR / "alternate_templates" / "bird"` constructs a path using Django's `BASE_DIR` setting, similar to how other Django settings can be configured. | ||
|
|
||
| With this setup, django-bird will search for components in the following order: | ||
|
|
||
| 1. `components` | ||
| 2. `third_party_library/components` | ||
| 3. `alternate_templates/bird` | ||
| 4. The default `bird` directory | ||
|
|
||
| The default `bird` directory will always be checked last, ensuring that your custom directories take precedence in template resolution. | ||
|
|
||
| ## `ENABLE_AUTO_CONFIG` | ||
|
|
||
| django-bird requires a few settings to be setup in your project's `DJANGO_SETTINGS_MODULE` before it will work properly. django-bird will automatically take care of this, during the app's initialization in `django_bird.apps.AppConfig.ready`. | ||
|
|
||
| If you would like to disable this behavior and perform the setup manually, setting `ENABLE_AUTO_CONFIG` to `False` will allow you to do so. | ||
|
|
||
| ### Manual Setup | ||
|
|
||
| When `ENABLE_AUTO_CONFIG` is set to `False`, you need to manually configure the following: | ||
|
|
||
| 1. Add django-bird's template tags to Django's built-ins. | ||
| 2. Include django-bird's loader in your template loaders, ensuring it comes before Django's default filesystem and app directories loaders. | ||
|
|
||
| The complete setup in your settings file should look like this: | ||
|
|
||
| ```{code-block} python | ||
| :caption: settings.py | ||
| from pathlib import Path | ||
| BASE_DIR = Path(__file__).resolve(strict=True).parent | ||
| DJANGO_BIRD = { | ||
| "ENABLE_AUTO_CONFIG": False, | ||
| } | ||
| TEMPLATES = [ | ||
| { | ||
| "BACKEND": "django.template.backends.django.DjangoTemplates", | ||
| "DIRS": [ | ||
| BASE_DIR / "templates", | ||
| ], | ||
| "OPTIONS": { | ||
| "builtins": [ | ||
| "django_bird.templatetags.django_bird", | ||
| ], | ||
| "loaders": [ | ||
| ( | ||
| "django.template.loaders.cached.Loader", | ||
| [ | ||
| "django_bird.loader.BirdLoader", | ||
| "django.template.loaders.filesystem.Loader", | ||
| "django.template.loaders.app_directories.Loader", | ||
| ], | ||
| ), | ||
| ], | ||
| }, | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| This configuration ensures that django-bird's templatetags are available globally and that its loader is used to compile bird component templates before the standard Django loaders. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters