urls_to_js¶

Utilities, functions and classes for generating JavaScript from Django’s url configuration files.

class render_static.transpilers.urls_to_js.URLTreeVisitor[source]¶

Bases: BaseURLTranspiler

An abstract base class for JavaScript generators of url reversal code. This class defines a visitation design pattern that deriving classes may extend.

Most of the difficult work of walking the URL tree is handled by this base class. Deriving classes are free to focus on generating Javascript, but may override the tree walking and url reversal logic if they so desire.

To use this class derive from it and implement its abstract visitation methods. Visitor methods should yield lines of JavaScript code and set the indentation levels by calling indent() and outdent(). Each yielded line is written by the base class using the configured indentation/newline options. When None is yielded or returned, nothing will be written. To write a newline and nothing else, simply yield or return an empty string.

__init__(include=None, exclude=None, **kwargs)[source]¶

Parameters:

include (Iterable[str] | None) – A list of path names to include, namespaces without path names will be treated as every path under the namespace. Default: include everything
exclude (Iterable[str] | None) – A list of path names to exclude, namespaces without path names will be treated as every path under the namespace. Default: exclude nothing
kwargs – Set of configuration parameters, see Transpiler params

classmethod __new__(*args, **kwargs)¶

property URLTreeVisitor.context: Dict[str, Any]¶

The template render context passed to overrides. In addition to render_static.transpilers.Transpiler.context. This includes:

include: The list of include pattern strings

exclude: The list of exclude pattern strings

class render_static.transpilers.urls_to_js.SimpleURLWriter[source]¶

Bases: URLTreeVisitor

A URLTreeVisitor that produces a JavaScript object where the keys are the path namespaces and names and the values are functions that accept positional and named arguments and return paths.

This visitor accepts several additional parameters on top of the base parameters. To use this visitor you may call it like so:

const urls = {
    {% urls_to_js raise_on_not_found=False %}
};

This will produce JavaScript you may invoke like so:

..code-block:

urls.namespace.path_name({'arg1': 1, 'arg2': 'a'});

In addition to the base parameters the configuration parameters that control the JavaScript output include:

raise_on_not_found
Raise a TypeError if no reversal for a url pattern is found, default: True

__init__(**kwargs)[source]¶

Parameters:: kwargs – Set of configuration parameters, see also URLTreeVisitor params
Return type:: None

classmethod __new__(*args, **kwargs)¶

property SimpleURLWriter.context: Dict[str, Any]¶

The template render context passed to overrides. In addition to render_static.transpilers.urls_to_js.URLTreeVisitor.context. This includes:

raise_on_not_found: Boolean, True if an exception should be raised when no reversal is found, default: True

class render_static.transpilers.urls_to_js.ClassURLWriter[source]¶

Bases: URLTreeVisitor

A visitor that produces a JavaScript class with a reverse() function directly analogous to Django’s url django.urls.reverse() function.

This is not the default visitor for the urls_to_js tag, but its probably the one you want. It accepts several additional parameters on top of the base parameters. To use this visitor you may call it like so:

{% urls_to_js
    visitor="render_static.transpilers.ClassURLWriter"
    class_name='URLResolver'
    indent=' '
%}

This will produce JavaScript you may invoke like so:

const urls = new URLResolver();
urls.reverse('namespace:path_name', {'arg1': 1, 'arg2': 'a'});

In addition to the base parameters the configuration parameters that control the JavaScript output include:

class_name
The name of the JavaScript class to use: default: URLResolver

raise_on_not_found
Raise a TypeError if no reversal for a url pattern is found, default: True

export
The generated JavaScript file will include an export statement for the generated class. default: False

__init__(**kwargs)[source]¶

Parameters:: kwargs – Set of configuration parameters, see also URLTreeVisitor.__init__() params
Return type:: None

classmethod __new__(*args, **kwargs)¶

property ClassURLWriter.context¶

The template render context passed to overrides. In addition to render_static.transpilers.urls_to_js.URLTreeVisitor.context. This includes:

class_name: The name of the JavaScript class

raise_on_not_found: Boolean, True if an exception should be raised when no reversal is found, default: True

class render_static.transpilers.urls_to_js.Substitute[source]¶

Bases: object

A placeholder representing a substitution, either by a positional argument or a named argument in a url path string.

__init__(arg_or_kwarg)[source]¶

Parameters:: arg_or_kwarg (str | int) – Either an integer index corresponding to the argument to substitute for this placeholder or the string name of the argument to substitute at this placeholder.
Return type:: None

classmethod __new__(*args, **kwargs)¶

render_static.transpilers.urls_to_js.normalize_ns(namespaces)[source]¶

Normalizes url names by collapsing multiple : characters. :param namespaces: The namespace string to normalize :return: The normalized version of the url path name

Parameters:: namespaces (str)
Return type:: str

render_static.transpilers.urls_to_js.build_tree(patterns, include=None, exclude=None, app_name=None)[source]¶

Generate a tree from the url configuration where the branches are namespaces and the leaves are collections of URLs registered against fully qualified reversible names.

The tree structure will look like this:

[
    { # first dict contains child branches
        'namespace1': [{...}, {...}, 'incl_app_name1', route],
        # no app_name specified for this include
        'namespace2': [{...}, {...}, None, route]
    },
    {
        # URLPatterns for this qname
        'url_name1': [URLPattern, URLPattern, ...]
        'url_name2': [URLPattern, ...]
    },
    None, # no root app_name
    RegexPattern or RoutePattern # if one exists
]

Parameters:

patterns (Iterable[URLPattern]) – The list of URLPatterns to transpile into a javascript resolver
include (Iterable[str] | None) – A list of path names to include, namespaces without path names will be treated as every path under the namespace. Default: include everything
exclude (Iterable[str] | None) – A list of path names to exclude, namespaces without path names will be treated as every path under the namespace. Default: exclude nothing
app_name (str | None) – The app name (if any) of the provided patterns.

Returns:

A tree structure containing the configured URLs

Return type:

Tuple[Tuple[Dict, Dict, str | None, RegexPattern | RoutePattern | None], int]