mirrors/django-components
1
0
Fork 0
mirror of https://github.com/django-components/django-components.git synced 2025-08-03 22:08:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'master' of https://github.com/EmilStenstrom/django-components

Browse source
This commit is contained in:
Emil Stenström 2023-12-09 11:32:10 +01:00
commit 8a7dd1a53c
3 changed files with 94 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.pre-commit-config.yaml
View file

@ -4,7 +4,7 @@ repos:
hooks:
- id: isort
- repo: https://github.com/psf/black
rev: 23.9.1
rev: 23.11.0
hooks:
- id: black
- repo: https://github.com/pycqa/flake8

102
README.md
View file

@ -20,9 +20,9 @@ Read on to learn about the details!
## Release notes
*Version 0.28* introduces 'implicit' slot filling and the `default` option for `slot` tags.
*Version 0.28* introduces 'implicit' slot filling and the `default` option for `slot` tags.
*Version 0.27* adds a second installable app: *django_components.safer_staticfiles*. It provides the same behavior as *django.contrib.staticfiles* but with extra security guarantees (more info below in Security Notes).
*Version 0.27* adds a second installable app: *django_components.safer_staticfiles*. It provides the same behavior as *django.contrib.staticfiles* but with extra security guarantees (more info below in Security Notes).
*Version 0.26* changes the syntax for `{% slot %}` tags. From now on, we separate defining a slot (`{% slot %}`) from filling a slot with content (`{% fill %}`). This means you will likely need to change a lot of slot tags to fill. We understand this is annoying, but it's the only way we can get support for nested slots that fill in other slots, which is a very nice feature to have access to. Hoping that this will feel worth it!
@ -51,14 +51,14 @@ To use it, add it to INSTALLED_APPS and remove _django.contrib.staticfiles_.
```python
INSTALLED_APPS = [
# django.contrib.staticfiles # <-- REMOVE
"django_components",
"django_components.safer_staticfiles" # <-- ADD
# 'django.contrib.staticfiles', # <-- REMOVE
'django_components',
'django_components.safer_staticfiles' # <-- ADD
]
```
If you are on an older version of django-components, your alternatives are a) passing `--ignore <pattern>` options to the _collecstatic_ CLI command, or b) defining a subclass of StaticFilesConfig.
Both routes are described in the official [docs of the _staticfiles_ app](https://docs.djangoproject.com/en/4.2/ref/contrib/staticfiles/#customizing-the-ignored-pattern-list).
Both routes are described in the official [docs of the _staticfiles_ app](https://docs.djangoproject.com/en/4.2/ref/contrib/staticfiles/#customizing-the-ignored-pattern-list).
## Installation
@ -71,7 +71,7 @@ Then add the app into INSTALLED_APPS in settings.py
```python
INSTALLED_APPS = [
...,
"django_components",
'django_components',
]
```
@ -197,8 +197,8 @@ class Calendar(component.Component):
}
class Media:
css = "calendar/calendar.css"
js = "calendar/calendar.js"
css = "calendar/style.css"
js = "calendar/script.js"
```
And voilá!! We've created our first component.
@ -251,7 +251,7 @@ _New in version 0.26_:
---
Components support something called 'slots'.
Components support something called 'slots'.
When a component is used inside another template, slots allow the parent template to override specific parts of the child component by passing in different content.
This mechanism makes components more reusable and composable.
@ -260,7 +260,7 @@ In the example below we introduce two block tags that work hand in hand to make
- `{% slot <name> %}`/`{% endslot %}`: Declares a new slot in the component template.
- `{% fill <name> %}`/`{% endfill %}`: (Used inside a `component_block` tag pair.) Fills a declared slot with the specified content.
Let's update our calendar component to support more customization. We'll add `slot` tag pairs to its template, _calendar.html_.
Let's update our calendar component to support more customization. We'll add `slot` tag pairs to its template, _calendar.html_.
```htmldjango
<div class="calendar-component">
@ -302,7 +302,7 @@ Here's the same example as before, except with default slots and implicit fillin
The template:
```htmldjango
```htmldjango
<div class="calendar-component">
<div class="header">
{% slot "header" %}Calendar header{% endslot %}
@ -398,7 +398,7 @@ Produces:
_Added in version 0.26._
In certain circumstances, you may want the behavior of slot filling to depend on
whether or not a particular slot is filled.
whether or not a particular slot is filled.
For example, suppose we have the following component template:
@ -430,7 +430,7 @@ This may not be what you want. What if instead the outer 'subtitle' div should o
be included when the inner slot is in fact filled?
The answer is to use the `{% if_filled <name> %}` tag. Together with `{% endif_filled %}`,
these define a block whose contents will be rendered only if the component slot with
these define a block whose contents will be rendered only if the component slot with
the corresponding 'name' is filled.
This is what our example looks like with an 'if_filled' tag.
@ -535,6 +535,80 @@ COMPONENTS = {
}
```
## Management Command
You can use the built-in management command `startcomponent` to create a django component. The command accepts the following arguments and options:
- `name`: The name of the component to create. This is a required argument.
- `--path`: The path to the components directory. This is an optional argument. If not provided, the command will use the `BASE_DIR` setting from your Django settings.
- `--js`: The name of the JavaScript file. This is an optional argument. The default value is `script.js`.
- `--css`: The name of the CSS file. This is an optional argument. The default value is `style.css`.
- `--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`.
### Management Command Usage
To use the command, run the following command in your terminal:
```bash
python manage.py startcomponent <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.
### Management Command 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:
```bash
python manage.py startcomponent 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:
```bash
python manage.py startcomponent 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:
```bash
python manage.py startcomponent 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:
```bash
python manage.py startcomponent my_component --dry-run
```
This will simulate the creation of `my_component` without creating any files.
## Install locally and run the tests
Start by forking the project by clicking the **Fork button** up in the right corner in the GitHub . This makes a copy of the repository in your own name. Now you can clone this repository locally and start adding features:

10
requirements-dev.txt
View file

@ -4,7 +4,7 @@
#
# pip-compile requirements-dev.in
#
asgiref==3.6.0
asgiref==3.7.2
# via django
cachetools==5.3.1
# via tox
@ -16,7 +16,7 @@ colorama==0.4.6
# via tox
distlib==0.3.7
# via virtualenv
django==4.2.6
django==5.0
# via -r requirements-dev.in
filelock==3.12.3
# via
@ -47,7 +47,7 @@ pluggy==1.3.0
# via
# pytest
# tox
pre-commit==3.4.0
pre-commit==3.5.0
# via -r requirements-dev.in
pycodestyle==2.11.0
# via flake8
@ -55,13 +55,13 @@ pyflakes==3.1.0
# via flake8
pyproject-api==1.6.1
# via tox
pytest==7.4.2
pytest==7.4.3
# via -r requirements-dev.in
pyyaml==6.0
# via pre-commit
sqlparse==0.4.4
# via django
tox==4.11.3
tox==4.11.4
# via -r requirements-dev.in
virtualenv==20.24.3
# via