https://github.com/deathbeds/urljsf
Build declarative, interactive HTML forms with JSON Schema
https://github.com/deathbeds/urljsf
Last synced: 9 months ago
JSON representation
Build declarative, interactive HTML forms with JSON Schema
- Host: GitHub
- URL: https://github.com/deathbeds/urljsf
- Owner: deathbeds
- License: bsd-3-clause
- Created: 2024-11-09T20:02:21.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-21T18:39:20.000Z (about 1 year ago)
- Last Synced: 2025-03-25T10:06:12.434Z (10 months ago)
- Language: Python
- Homepage: https://urljsf.rtfd.org
- Size: 1.19 MB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# `urljsf`
| docs | install | build |
| :-------------------------: | :----------------------------------------------------------------------------------------: | :----------------------------------: |
| [![docs][docs-badge]][docs] | [![install from pypi][pypi-badge]][pypi] [![install from conda-forge][conda-badge]][conda] | [![build][workflow-badge]][workflow] |
> Build statically-hostable, interactive HTML forms for making web requests
>
> _Powered by [`react-json-schema-form`][rjsf] and
> [`react-`][react-bootstrap][`bootstrap`][bootstrap]._
[bootstrap]: https://github.com/twbs/bootstrap
[json-schema]: https://json-schema.org
[rjsf]: https://github.com/rjsf-team/react-jsonschema-form
[react-bootstrap]: https://github.com/react-bootstrap/react-bootstrap
[ui-schema]:
https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema/
[docs]: https://urljsf.rtfd.org
[docs-badge]: https://readthedocs.org/projects/urljsf/badge/?version=latest
[conda-badge]: https://img.shields.io/conda/vn/conda-forge/urljsf
[conda]: https://anaconda.org/conda-forge/urljsf
[pypi-badge]: https://img.shields.io/pypi/v/urljsf
[pypi]: https://pypi.org/project/urljsf
[workflow-badge]:
https://github.com/deathbeds/urljsf/actions/workflows/ci.yml/badge.svg?branch=main
[workflow]:
https://github.com/deathbeds/urljsf/actions/workflows/ci.yml?query=branch%3Amain
**Visitors** to a `urljsf`-built page see:
- one or more interactive HTML forms...
- defined by and validated against a JSON [Schema][json-schema], optionally with...
- deep customizable [user interface][ui-schema]
- pre-filled data
- custom validation checks
Once the data is _validated_, the user sees a button which gets a URL, which can be:
- downloaded as a file (including `.zip` archives)
- opened in a new browser window
- copy and pasted
- submitted to an HTTP endpoint, either by opening a new window, or directly.
- opened in registered native applications like email
`urljsf` **doesn't** ship a server, so that part is up to you!
**Builders** write TOML, JSON, YAML, or python, then can use `urljsf` as:
- a drop-in-and-pray [`script`](#js-script)
- a standalone [CLI tool](#command-line)
- a [`sphinx`](#sphinx) or [`mkdocs`](#mkdocs) extension
... to create JavaScript/HTML forms that help **visitors** provide good data for:
- pull requests
- issues
- galleries
- surveys
- on-demand build services
- precise test descriptions
- linter rules
## Install
[contrib]: https://github.com/deathbeds/urljsf/blob/main/CONTRIBUTING.md
### From PyPI
`urljsf` is distributed on [PyPI][pypi], with several optional extras to help ensure
tested versions are available:
```bash
pip install urljsf
# ... or urljsf[sphinx] for sphinx
# ... or urljsf[mkdocs] for mkdocs and pymdown-extensions
# ... or urljsf[yaml] for build time YAML parsing
# or...
uv install urljsf
# etc.
```
### From conda-forge
`urljsf` is also distributed on [`conda-forge`][conda], with similar extras:
```bash
pixi add urljsf
# ... or urljsf-with-sphinx
# ... or urljsf-with-mkdocs
# ... or urljsf-with-yaml
# or...
micromamba install -c conda-forge urljsf
# or...
mamba install -c conda-forge urljsf
# or...
conda install -c conda-forge urljsf
# etc.
```
### Development
See the [contributing guide][contrib] for a development install.
## Usage
`urljsf` work with some [JSON schema](#json-schema) constrained files as a:
- (not-recommended) hot-linked [`script`](#js-script)
- a standalone [site generator](#command-line) for simple sites
- a plugin for the [`sphinx`](#sphinx) and [`mkdocs`](#mkdocs) documentation systems
### JSON Schema
A `urljsf` is built from a number of JSON schema-constrained files. Writing these in
plain JSON is tedious, so TOML and YAML are also supported inputs for any of the methods
below. Learn more on the [schema documentation][schema-docs].
[schema-docs]: https://urljsf.rtfd.org/en/latest/use/schema.html
### JS Script
A very simple, but limited, usage is an `.html` file that links to `urljsf` and
`bootstrap` resources on the internet.
```html
[forms.url.schema]
title = "pick an xkcd"
description = "this will redirect to `xkcd.com`"
type = "object"
required = ["xkcd"]
properties.xkcd = {type="integer", minimum=1, maximum=2997}
[forms.url.ui_schema.xkcd."ui:options"]
widget = "range"
[templates]
url = "https://xkcd.com/{{ data.url.xkcd }}"
submit_button = "see xkcd #{{ data.url.xkcd }}"
```
This technique has _many_ limitations, and is **not recommended**.
Some ways to improve:
- download a GitHub release and unpack it, serving the files next to it
- ensure bootstrap is loaded _before_ the script, with a `link` tag in a `head`.
- on the `script` element, use a `src` to point to a valid `urljsf` definition
- use the [CLI](#command-line) or a documentation extension for [`sphinx`](#sphinx) or
[`mkdocs`](#mkdocs)
### Command Line
The `urljsf` command line generates a ready-to-serve, standalone site with all required
static assets. Written in `python`, it can reuse the extensive JSON schema support in
the python ecosystem, such as `msgspec` or `pydantic`.
```bash
prsf --help
```
`urljsf` requires at least a definition file, but offers many command line options: see
the [documentation][cli-docs] for more.
[cli-docs]: https://urljsf.rtfd.org/en/latest/use/cli.html
### Sphinx
After [installing](#install) with the `[sphinx]` extra, add `urljsf.sphinxext` to
`conf.py`:
```py
# conf.py
extensions = [
# ... other extensions
"urljsf.sphinxext",
]
```
Then use the `urljsf` directive in source files:
```rst
.. urljsf: # a relative path to a description as a TOML, YAML, or JSON file or python
:toml:
# a form definition in TOML
```
See the [documentation][sphinx-docs] for more about configuring `urljsf.sphinxext`, the
`urljsf` directive, and more advanced use cases.
[sphinx-docs]: https://urljsf.rtfd.org/en/latest/use/sphinx.html
### Mkdocs
After [installing](#install) with the `[mkdocs]` extra, add `urljsf` to `mkdocs.yml`:
```yaml
# mkdocs.yml
plugins:
- urljsf
```
Then use the `urljsf` fenced code block in source files:
````markdown
```urljsf {path=path/to/defnition.toml}
```
````
See the [documentation][mkdocs-docs] for more about configuring `urljsf`, the `urljsf`
fence, and more advanced use cases.
[mkdocs-docs]: https://urljsf.rtfd.org/en/latest/use/mkdocs.html
## Limitations
- `react-json-schema-form` cannot represent all possible data structures, such as
writing a _new_ JSON schema _in_ JSON schema, or many features added after Draft 7
- the generated scripts _won't_ work when served from `file://` due to browser CORS
headers requirements for `type="module"` scripts
- the [`sphinx`](#sphinx) integration is only tested with the `html` builder, the basic
`alabaster` theme, and [`pydata-sphinx-theme`][pdst] (by way of `urljsf`'s own
[documentation][sphinx-docs])
- the [`mkdocs`](#mkdocs) integration is only tested with the default theme
[pdst]: https://github.com/pydata/pydata-sphinx-theme
## Open Source
`urljsf` itself is licensed under the `BSD-3-Clause` license. You can do whatever you
want with it, but if you change it a lot, it's not the maintainers' problem.
`urljsf` distributes third-party JavaScript and CSS in various forms, licensed under the
`MIT`, `BSD-3-Clause`, and `ISC` licenses.