urljsf#

docs

install

build

docs

install from pypi install from conda-forge

build

Build statically-hostable, interactive HTML forms for making web requests

Powered by react-json-schema-form and react-bootstrap.

Visitors to a urljsf-built page see:

  • one or more interactive HTML forms…

    • defined by and validated against a JSON Schema, optionally with…

    • deep customizable user interface

    • 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:

… 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#

From PyPI#

urljsf is distributed on PyPI, with several optional extras to help ensure tested versions are available:

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, with similar extras:

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 for a development install.

Usage#

urljsf work with some JSON schema constrained files as a:

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.

JS Script#

A very simple, but limited, usage is an .html file that links to urljsf and bootstrap resources on the internet.

<script type="application/vnd.deathbeds.urljsf.v0+toml">
  [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 }}"
</script>
<script
  type="module"
  src="https://deathbeds.github.io/urljsf/_static/index.js"
></script>

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 or a documentation extension for sphinx or 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.

prsf --help

urljsf requires at least a definition file, but offers many command line options: see the documentation for more.

Sphinx#

After installing with the [sphinx] extra, add urljsf.sphinxext to conf.py:

# conf.py
extensions = [
  # ... other extensions
  "urljsf.sphinxext",
]

Then use the urljsf directive in source files:

.. 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 for more about configuring urljsf.sphinxext, the urljsf directive, and more advanced use cases.

Mkdocs#

After installing with the [mkdocs] extra, add urljsf to mkdocs.yml:

# mkdocs.yml
plugins:
  - urljsf

Then use the urljsf fenced code block in source files:

```urljsf {path=path/to/defnition.toml}

```

See the documentation for more about configuring urljsf, the urljsf fence, and more advanced use cases.

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 integration is only tested with the html builder, the basic alabaster theme, and pydata-sphinx-theme (by way of urljsf’s own documentation)

  • the mkdocs integration is only tested with the default 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.

Documentation Contents#