-
-
Notifications
You must be signed in to change notification settings - Fork 23
v1.0.0 #73
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
Merged
Merged
v1.0.0 #73
Changes from 50 commits
Commits
Show all changes
53 commits
Select commit
Hold shift + click to select a range
4d272fc
change required versions
Archmonger 2f4bc41
bump version number
Archmonger fcb1f8c
add changelog entry
Archmonger 98b795a
use contextlib suppress
Archmonger f03b0cb
use f-strings
Archmonger 0d1acba
dispatch_single_view -> serve_json_patch
Archmonger 9b13b6a
sort imports
Archmonger 036c4ad
new hooks
Archmonger 2db9b1d
formatting
Archmonger c4e8b4a
update changelog to add hooks
Archmonger 9de275a
Python 3.8 fixes
Archmonger 2fe1208
more python 3.8 fixes
Archmonger eda71b9
new docs source
Archmonger 2965ceb
publish docs workflow
Archmonger dedaf7e
rename idom_component to component
Archmonger 465092d
better docs statement in changelog
Archmonger d1c4637
formatting and cleanup
Archmonger d31cad0
more everything
Archmonger 96a1605
cleanup
Archmonger c937fcf
cleanup gen2
Archmonger 9d83b00
templatetags -> templatetag
Archmonger 9fcc082
quick start -> at a glance
Archmonger 87a900a
collapsible everything!
Archmonger 30b8f5c
0.0.6 -> 1.0.0
Archmonger ad9b672
note cleanup
Archmonger f931f9b
better component regex
Archmonger a4abe01
add logging to test app
Archmonger ddbf68c
fix spacing
Archmonger 5d924d3
more smithing
Archmonger a772359
ELI5
Archmonger 45159b6
better examples
Archmonger 1f1a2b1
fix example
Archmonger f1d6afe
highlight body tag
Archmonger 9d98425
add more guidance
Archmonger a142bfb
smithy
Archmonger c2104ca
english tweaks
Archmonger 1d072dc
minor rework
Archmonger bb35d0d
rename component to HelloWorld
Archmonger c9646f0
warning if no components are found
Archmonger 059ae0e
fix spacing in templatetag.md
Archmonger 1ea9e80
fix multiline strings
Archmonger 34ae18c
clean changelong
Archmonger 9e3c035
fix unreleased link
Archmonger f22d60e
Add link to django only features
Archmonger 5095588
disable prose wrap formatting
Archmonger dbc2ace
how to use -> getting started
Archmonger 12cfc99
django-only -> exclusive
Archmonger b1c41f8
color error/warning log messages
Archmonger 7e8ace8
remove duplicate log message
Archmonger 4a4e51d
add newline
Archmonger 52f335a
minor readme revision
Archmonger 8f64511
change contribute section names
Archmonger d758ec8
IDOM Core tip
Archmonger File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or 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,15 @@ | ||
name: Publish Docs | ||
on: | ||
push: | ||
branches: | ||
- main | ||
jobs: | ||
deploy: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: actions/checkout@v2 | ||
- uses: actions/setup-python@v2 | ||
with: | ||
python-version: 3.x | ||
- run: pip install requirements/build-docs.txt | ||
- run: mkdocs gh-deploy --force |
This file contains hidden or 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 hidden or 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 |
---|---|---|
@@ -1,184 +1,79 @@ | ||
# Django IDOM · [](https://github.com/idom-team/django-idom/actions?query=workflow%3ATest) [](https://pypi.python.org/pypi/django-idom) [](https://github.com/idom-team/django-idom/blob/main/LICENSE) | ||
|
||
`django-idom` allows Django to integrate with [IDOM](https://github.com/idom-team/idom), a reactive Python web framework for building **interactive websites without needing a single line of Javascript**. | ||
|
||
**You can try IDOM now in a Jupyter Notebook:** | ||
<a | ||
target="_blank" | ||
href="https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?filepath=notebooks%2Fintroduction.ipynb"> | ||
<img | ||
alt="Binder" | ||
valign="bottom" | ||
height="21px" | ||
src="https://mybinder.org/badge_logo.svg"/> | ||
</a> | ||
|
||
# Quick Example | ||
|
||
## `example_app/components.py` | ||
|
||
This is where you'll define your [IDOM](https://github.com/idom-team/idom) components. Ultimately though, you should | ||
feel free to organize your component modules as you wish. Any components created will ultimately be referenced | ||
by Python dotted path in `your-template.html`. | ||
|
||
```python | ||
from idom import component, html | ||
from django_idom import IdomWebsocket | ||
|
||
# Components are CamelCase by ReactJS convention | ||
@component | ||
def Hello(websocket: IdomWebsocket, greeting_recipient: str): | ||
return html.h1(f"Hello {greeting_recipient}!") | ||
``` | ||
|
||
## [`example_app/templates/your-template.html`](https://docs.djangoproject.com/en/dev/topics/templates/) | ||
|
||
In your templates, you may add IDOM components into your HTML by using the `idom_component` | ||
template tag. This tag requires the dotted path to the component function. | ||
|
||
Additonally, you can pass in keyworded arguments into your component function. | ||
|
||
In context this will look a bit like the following... | ||
|
||
```jinja | ||
{% load idom %} | ||
|
||
<!DOCTYPE html> | ||
<html> | ||
<head> | ||
<title>Example Project</title> | ||
</head> | ||
|
||
<body> | ||
{% idom_component "my_django_project.example_app.components.Hello" greeting_recipient="World" %} | ||
</body> | ||
</html> | ||
``` | ||
|
||
# Installation | ||
|
||
Install `django-idom` via pip. | ||
<!--header-start--> | ||
|
||
```bash | ||
pip install django-idom | ||
``` | ||
|
||
You'll also need to modify a few files in your Django project. | ||
|
||
## [`settings.py`](https://docs.djangoproject.com/en/dev/topics/settings/) | ||
|
||
In your settings you'll need to add `channels` and `django_idom` to [`INSTALLED_APPS`](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-INSTALLED_APPS). | ||
|
||
```python | ||
INSTALLED_APPS = [ | ||
..., | ||
"channels", | ||
"django_idom", | ||
] | ||
|
||
# Ensure ASGI_APPLICATION is set properly based on your project name! | ||
ASGI_APPLICATION = "my_django_project.asgi.application" | ||
``` | ||
|
||
**Optional:** You can also configure IDOM settings. | ||
# Django IDOM · [](https://github.com/idom-team/django-idom/actions?query=workflow%3ATest) [](https://pypi.python.org/pypi/django-idom) [](https://github.com/idom-team/django-idom/blob/main/LICENSE) | ||
|
||
```python | ||
# If "idom" cache is not configured, then we'll use "default" instead | ||
CACHES = { | ||
"idom": {"BACKEND": ...}, | ||
} | ||
<!--header-end--> | ||
<!--intro-start--> | ||
|
||
# Maximum seconds between two reconnection attempts that would cause the client give up. | ||
# 0 will disable reconnection. | ||
IDOM_WS_MAX_RECONNECT_TIMEOUT: int = 604800 | ||
IDOM connects your Python web framework of choice to a ReactJS frontend, allowing you to create **interactive websites without needing JavaScript!** | ||
|
||
# The URL for IDOM to serve websockets | ||
IDOM_WEBSOCKET_URL: str = "idom/" | ||
``` | ||
Following ReactJS styling, web elements are combined into [reusable "components"](https://idom-docs.herokuapp.com/docs/guides/creating-interfaces/your-first-components/index.html#parametrizing-components). These components can utilize [hooks](https://idom-docs.herokuapp.com/docs/reference/hooks-api.html) and [events](https://idom-docs.herokuapp.com/docs/guides/adding-interactivity/responding-to-events/index.html#async-event-handlers) to create infinitely complex web pages. | ||
|
||
## [`urls.py`](https://docs.djangoproject.com/en/dev/topics/http/urls/) | ||
When needed, IDOM can [use components directly from NPM](https://idom-docs.herokuapp.com/docs/guides/escape-hatches/javascript-components.html#dynamically-loaded-components). For additional flexibility, components can also be [fully developed in JavaScript](https://idom-docs.herokuapp.com/docs/guides/escape-hatches/javascript-components.html#custom-javascript-components). | ||
|
||
Add IDOM HTTP paths to your `urlpatterns`. | ||
Any Python web framework with Websockets can support IDOM. See below for what frameworks are supported out of the box. | ||
|
||
```python | ||
from django.urls import include, path | ||
| Supported Frameworks | Supported Frameworks (External) | | ||
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| [`Flask`, `FastAPI`, `Sanic`, `Tornado`](https://idom-docs.herokuapp.com/docs/guides/getting-started/installing-idom.html#officially-supported-servers) | [`Django`](https://github.com/idom-team/django-idom), [`Plotly-Dash`](https://github.com/idom-team/idom-dash), [`Jupyter`](https://github.com/idom-team/idom-jupyter) | | ||
|
||
urlpatterns = [ | ||
path("idom/", include("django_idom.http.urls")), | ||
... | ||
] | ||
``` | ||
<!--intro-end--> | ||
|
||
## [`asgi.py`](https://docs.djangoproject.com/en/dev/howto/deployment/asgi/) | ||
--- | ||
|
||
Register IDOM's websocket using `IDOM_WEBSOCKET_PATH`. | ||
# At a Glance | ||
|
||
_Note: If you do not have an `asgi.py`, follow the [`channels` installation guide](https://channels.readthedocs.io/en/stable/installation.html)._ | ||
## `my_app/components.py` | ||
|
||
```python | ||
<!--py-header-start--> | ||
|
||
import os | ||
from django.core.asgi import get_asgi_application | ||
You'll need a file to define your [IDOM](https://github.com/idom-team/idom) components. We recommend creating a `components.py` file within your chosen **Django app** to start out. | ||
|
||
# Ensure DJANGO_SETTINGS_MODULE is set properly based on your project name! | ||
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my_django_project.settings") | ||
django_asgi_app = get_asgi_application() | ||
<!--py-header-end--> | ||
<!--py-code-start--> | ||
|
||
from channels.auth import AuthMiddlewareStack | ||
from channels.routing import ProtocolTypeRouter, URLRouter | ||
from channels.sessions import SessionMiddlewareStack | ||
from django_idom import IDOM_WEBSOCKET_PATH | ||
```python title="components.py" | ||
from idom import component, html | ||
|
||
application = ProtocolTypeRouter( | ||
{ | ||
"http": django_asgi_app, | ||
"websocket": SessionMiddlewareStack( | ||
AuthMiddlewareStack(URLRouter([IDOM_WEBSOCKET_PATH])) | ||
), | ||
} | ||
) | ||
@component | ||
def HelloWorld(recipient: str): | ||
return html.h1(f"Hello {recipient}!") | ||
``` | ||
|
||
# Developer Guide | ||
<!--py-code-end--> | ||
|
||
If you plan to make code changes to this repository, you'll need to install the | ||
following dependencies first: | ||
## [`my_app/templates/my-template.html`](https://docs.djangoproject.com/en/dev/topics/templates/) | ||
|
||
- [NPM](https://docs.npmjs.com/try-the-latest-stable-version-of-npm) for | ||
installing and managing Javascript | ||
- [ChromeDriver](https://chromedriver.chromium.org/downloads) for testing with | ||
[Selenium](https://www.seleniumhq.org/) | ||
<!--html-header-start--> | ||
|
||
Once done, you should clone this repository: | ||
In your **Django app**'s HTML located within your `templates` folder, you can now embed your IDOM component using the `component` template tag. Within this tag, you will need to type in your dotted path to the component function as the first argument. | ||
|
||
```bash | ||
git clone https://github.com/idom-team/django-idom.git | ||
cd django-idom | ||
``` | ||
|
||
Then, by running the command below you can: | ||
Additonally, you can pass in keyword arguments into your component function. For example, after reading the code below, pay attention to how the function definition for `HelloWorld` (_in the previous example_) accepts a `recipient` argument. | ||
|
||
- Install an editable version of the Python code | ||
<!--html-header-end--> | ||
<!--html-code-start--> | ||
|
||
- Download, build, and install Javascript dependencies | ||
|
||
```bash | ||
pip install -e . -r requirements.txt | ||
```jinja title="my-template.html" | ||
{% load idom %} | ||
<!DOCTYPE html> | ||
<html> | ||
<body> | ||
{% component "example_project.my_app.components.HelloWorld" recipient="World" %} | ||
</body> | ||
</html> | ||
``` | ||
|
||
Finally, to verify that everything is working properly, you'll want to run the test suite. | ||
<!--html-code-end--> | ||
|
||
## Running The Tests | ||
--- | ||
|
||
This repo uses [Nox](https://nox.thea.codes/en/stable/) to run scripts which can | ||
be found in `noxfile.py`. For a full test of available scripts run `nox -l`. To run the full test suite simple execute: | ||
# Resources | ||
|
||
``` | ||
nox -s test | ||
``` | ||
<!--resources-start--> | ||
|
||
To run the tests using a headless browser: | ||
Follow the links below to find out more about this project. | ||
|
||
``` | ||
nox -s test -- --headless | ||
``` | ||
- [Try it Now](https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?urlpath=lab/tree/notebooks/introduction.ipynb) - Check out IDOM in a Jupyter Notebook. | ||
- [Documentation](https://idom-team.github.io/django-idom) - Learn how to install, run, and use IDOM. | ||
- [Community Forum](https://github.com/idom-team/idom/discussions) - Ask questions, share ideas, and show off projects. | ||
<!--resources-end--> |
This file contains hidden or 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,11 @@ | ||
--- | ||
hide: | ||
- navigation | ||
- toc | ||
--- | ||
|
||
!!! note "Attribution" | ||
|
||
{% include-markdown "../../CHANGELOG.md" start="<!--attr-start-->" end="<!--attr-end-->" %} | ||
|
||
{% include-markdown "../../CHANGELOG.md" start="<!--changelog-start-->" %} |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.