Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs #7

Merged
merged 37 commits into from
Feb 10, 2024
Merged
Changes from 1 commit
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
19012f7
Simplify first example use of get_context_data
tbrlpld Jan 5, 2024
400dc3a
Add sections about constructor arguments and dataclasses
tbrlpld Jan 7, 2024
e5373e5
Rework the intro section
tbrlpld Jan 7, 2024
5d64fba
Restructure the README
tbrlpld Jan 7, 2024
a9f62a2
Add example for parent context use
tbrlpld Jan 7, 2024
1f75d34
Update parent context explanations
tbrlpld Jan 7, 2024
9b2c351
Refine section on extra features of the component template tag
tbrlpld Jan 7, 2024
5685708
Fix sentence beginning
tbrlpld Jan 7, 2024
9b2cf2a
Move installation into a "getting started" section
tbrlpld Jan 13, 2024
13e3d23
Fix typo
tbrlpld Jan 13, 2024
0becf6c
Reduce repetition in sentence
tbrlpld Jan 13, 2024
74c7b5f
Simplify the first media example
tbrlpld Jan 13, 2024
fff12b7
Reorder example components
tbrlpld Jan 13, 2024
9ec7272
Test usage of media defining component
tbrlpld Jan 13, 2024
c61a8d3
Add more background on how to output media in templates
tbrlpld Jan 13, 2024
25e49f4
Add section about `MediaContainer`
tbrlpld Jan 13, 2024
953231d
Simplify sentence
tbrlpld Jan 13, 2024
aa80421
Add example for media container usage
tbrlpld Jan 14, 2024
7718660
Don't use title case
tbrlpld Jan 14, 2024
ca730b8
Expand dataclasses section a little
tbrlpld Jan 14, 2024
f7b1c62
Add section on custom constructor methods
tbrlpld Jan 15, 2024
6be0425
Add section on nested components
tbrlpld Jan 15, 2024
de07eae
Mention testing
tbrlpld Jan 15, 2024
486d68e
Add sections on nested groups and container components
tbrlpld Jan 18, 2024
891ed84
Rework the intro paragraph
tbrlpld Jan 18, 2024
4ce9f7b
Add name explainer
tbrlpld Jan 18, 2024
781f94c
Extra paragraph split in intro
tbrlpld Jan 18, 2024
26f28f6
Improve Slippers reference
tbrlpld Jan 18, 2024
25325f2
Move "supported version down
tbrlpld Jan 18, 2024
93a329e
Turn links more into TOC
tbrlpld Jan 18, 2024
ecbc798
Fix markup assertion for Django 3.2
tbrlpld Jan 22, 2024
a205093
Update changelog
tbrlpld Feb 1, 2024
57a3339
Unify changelog verbiage
tbrlpld Feb 1, 2024
8cecfc8
Blacken the docs
tbrlpld Feb 2, 2024
453ae4f
Add type hints to functions
tbrlpld Feb 10, 2024
dfd4529
Add type hints and better assertion to tests
tbrlpld Feb 10, 2024
9a83501
Move media assertion mixin to utils module
tbrlpld Feb 10, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Expand dataclasses section a little
tbrlpld committed Feb 10, 2024
commit ca730b845266f9f1ee39a6c6a89ffc318431c503
17 changes: 12 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -443,12 +443,15 @@ It can be used to combine the `media` properties of any kind of objects that hav

## Patterns for using components

Below, we want so show a few more examples of how components can be used that were not covered in the ["Getting started" section](#getting-started) above.

### Using dataclasses

The above example is neat already, but is may become a little verbose when we have more than one or two arguments to pass to the component.
You would have to list them all manually in the constructor and then assign them to the context.
Above, we showed how to [use class properties](#using-class-properties) to add data to the component's context.
This is a very useful and common pattern.
However, it is a bit verbose, especially when you have many properties directly pass the properties to the template context.

To make this a little easier, we can use dataclasses.
To make this a little more convenient, we can use [`dataclasses`](https://docs.python.org/3.12/library/dataclasses.html#module-dataclasses).

```python
# my_app/components.py
@@ -469,8 +472,12 @@ class WelcomePanel(Component):
```

With dataclasses we define the name and type of the properties we want to pass to the component in the class definition.
Then, we can use the `asdict` function to convert the dataclass instance to a dictionary that can be passed to the template context.
The `asdict` function only contains the properties defined in the dataclass, so we don't have to worry about accidentally passing other properties to the template.
Then, we can use the `asdict` function to convert the dataclass instance to a dictionary that can be directly as the template context.

The `asdict` function only adds keys to the dictionary that were defined as the properties defined in the dataclass.
In the above example, the dictionary returned by `asdict` would only contain the `name` key.
It would not contain the `template_name` key, because that is set on the class with a value but without a type annotation.
If you were to add the type annotation, then the `template_name` key would also be included in the dictionary returned by `asdict`.

### Special constructor methods