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

chore: update README

Browse source
This commit is contained in:
Gabriel Dugny 2024-08-02 22:30:52 +02:00 • committed by Emil Stenström
parent 19ee26a811
commit ab0b5c6266
1 changed files with 11 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

26
README.md
View file

@ -1,15 +1,11 @@
# <img src="https://github.com/EmilStenstrom/django-components/blob/master/logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;"> # <img src="https://raw.githubusercontent.com/EmilStenstrom/django-components/master/logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
<a href="https://github.com/EmilStenstrom/django-components/actions?query=workflow%3A%22Run+tests%22"><img align="right" src="https://github.com/EmilStenstrom/django-components/workflows/Run%20tests/badge.svg" alt="Show test status"></a>
<a href="https://pepy.tech/project/django-components"><img align="right" src="https://pepy.tech/badge/django-components" alt="Show download stats"></a>
[![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://EmilStenstrom.github.io/django-components/latest/license/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/EmilStenstrom/django-components/tests.yml)](https://github.com/EmilStenstrom/django-components/actions/workflows/tests.yml) [![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://EmilStenstrom.github.io/django-components/latest/license/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/EmilStenstrom/django-components/tests.yml)](https://github.com/EmilStenstrom/django-components/actions/workflows/tests.yml)
[**Docs**](https://EmilStenstrom.github.io/django-components/latest/) [**Docs (Work in progress)**](https://EmilStenstrom.github.io/django-components/latest/)
Create simple reusable template components in Django Create simple reusable template components in Django
## Features ## Features
<!-- FIXME Links --> <!-- FIXME Links -->
@ -43,7 +39,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
- [Release notes](#release-notes) - [Release notes](#release-notes)
- [Security notes 🚨](#security-notes-) - [Security notes 🚨](#security-notes-)
- [Installation](#installation) - [Installation](#installation)
- [Compatiblity](#compatiblity) - [Compatibility](#compatibility)
- [Create your first component](#create-your-first-component) - [Create your first component](#create-your-first-component)
- [Using single-file components](#using-single-file-components) - [Using single-file components](#using-single-file-components)
- [Use components in templates](#use-components-in-templates) - [Use components in templates](#use-components-in-templates)
@ -140,7 +136,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
🚨📢 **Version 0.5** CHANGES THE SYNTAX for components. `component_block` is now `component`, and `component` blocks need an ending `endcomponent` tag. The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use --path argument to point to each dir) of templates that use components to the new syntax automatically. 🚨📢 **Version 0.5** CHANGES THE SYNTAX for components. `component_block` is now `component`, and `component` blocks need an ending `endcomponent` tag. The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use --path argument to point to each dir) of templates that use components to the new syntax automatically.
## Getting started This change is done to simplify the API in anticipation of a 1.0 release of django_components. After 1.0 we intend to be stricter with big changes like this in point releases.
**Version 0.34** adds components as views, which allows you to handle requests and render responses from within a component. See the [documentation](#use-components-as-views) for more details. **Version 0.34** adds components as views, which allows you to handle requests and render responses from within a component. See the [documentation](#use-components-as-views) for more details.
@ -281,7 +277,7 @@ TEMPLATES = [
Read on to find out how to build your first component! Read on to find out how to build your first component!
## Compatiblity ## Compatibility
Django-components supports all supported combinations versions of [Django](https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django) and [Python](https://devguide.python.org/versions/#versions). Django-components supports all supported combinations versions of [Django](https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django) and [Python](https://devguide.python.org/versions/#versions).
@ -313,9 +309,9 @@ A component in django-components is the combination of four things: CSS, Javascr
Start by creating empty files in the structure above. Start by creating empty files in the structure above.
First you need a CSS file. Be sure to prefix all rules with a unique class so they don't clash with other rules. First, you need a CSS file. Be sure to prefix all rules with a unique class so they don't clash with other rules.
```css ```css title="[project root]/components/calendar/style.css"
/* In a file called [project root]/components/calendar/style.css */ /* In a file called [project root]/components/calendar/style.css */
.calendar-component { .calendar-component {
width: 200px; width: 200px;
@ -328,7 +324,7 @@ First you need a CSS file. Be sure to prefix all rules with a unique class so th
Then you need a javascript file that specifies how you interact with this component. You are free to use any javascript framework you want. A good way to make sure this component doesn't clash with other components is to define all code inside an anonymous function that calls itself. This makes all variables defined only be defined inside this component and not affect other components. Then you need a javascript file that specifies how you interact with this component. You are free to use any javascript framework you want. A good way to make sure this component doesn't clash with other components is to define all code inside an anonymous function that calls itself. This makes all variables defined only be defined inside this component and not affect other components.
```js ```js title="[project root]/components/calendar/script.js"
/* In a file called [project root]/components/calendar/script.js */ /* In a file called [project root]/components/calendar/script.js */
(function () { (function () {
if (document.querySelector(".calendar-component")) { if (document.querySelector(".calendar-component")) {
@ -341,7 +337,7 @@ Then you need a javascript file that specifies how you interact with this compon
Now you need a Django template for your component. Feel free to define more variables like `date` in this example. When creating an instance of this component we will send in the values for these variables. The template will be rendered with whatever template backend you've specified in your Django settings file. Now you need a Django template for your component. Feel free to define more variables like `date` in this example. When creating an instance of this component we will send in the values for these variables. The template will be rendered with whatever template backend you've specified in your Django settings file.
```htmldjango ```htmldjango title="[project root]/components/calendar/calendar.html"
{# In a file called [project root]/components/calendar/template.html #} {# In a file called [project root]/components/calendar/template.html #}
<div class="calendar-component">Today's date is <span>{{ date }}</span></div> <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
``` ```
@ -350,7 +346,7 @@ Finally, we use django-components to tie this together. Start by creating a file
Inside this file we create a Component by inheriting from the Component class and specifying the context method. We also register the global component registry so that we easily can render it anywhere in our templates. Inside this file we create a Component by inheriting from the Component class and specifying the context method. We also register the global component registry so that we easily can render it anywhere in our templates.
```python ```python title="[project root]/components/calendar/calendar.py"
# In a file called [project root]/components/calendar/calendar.py # In a file called [project root]/components/calendar/calendar.py
from django_components import Component, register from django_components import Component, register
@ -2861,4 +2857,4 @@ To display individual components, add them to the `urls.py`, like in the case of
## Development guides ## Development guides
- [Slot rendering flot](https://github.com/EmilStenstrom/django-components/blob/master/docs/slot_rendering.md) - [Slot rendering flot](https://github.com/EmilStenstrom/django-components/blob/master/docs/slot_rendering.md)