diff --git a/README.md b/README.md index 3fb6657a..86aba7d8 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,11 @@ -# django-components -Show test status -Show download stats +# django-components [![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 - ## Features @@ -43,7 +39,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified): - [Release notes](#release-notes) - [Security notes 🚨](#security-notes-) - [Installation](#installation) -- [Compatiblity](#compatiblity) +- [Compatibility](#compatibility) - [Create your first component](#create-your-first-component) - [Using single-file components](#using-single-file-components) - [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. -## 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. @@ -281,7 +277,7 @@ TEMPLATES = [ 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). @@ -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. -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 */ .calendar-component { 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. -```js +```js title="[project root]/components/calendar/script.js" /* In a file called [project root]/components/calendar/script.js */ (function () { 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. -```htmldjango +```htmldjango title="[project root]/components/calendar/calendar.html" {# In a file called [project root]/components/calendar/template.html #}
Today's date is {{ date }}
``` @@ -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. -```python +```python title="[project root]/components/calendar/calendar.py" # In a file called [project root]/components/calendar/calendar.py 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 -- [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) \ No newline at end of file