placeholders

The urls_to_js tag avoids error prone string processing by using Django’s django.urls.reverse() mechanism to generate the URLs to embed in the javascript. To do the reversal it needs temporary placeholder values to feed in as kwargs or args. There aren’t reliable or license friendly libraries available to generate the placeholders directly from the regular expressions so users are relied upon to supply them. This module provides facilities for registering and resolving those placeholders. It also contains some predefined placeholders for the admin module.

Users are strongly encouraged to use paths instead of re_paths and to supply custom converters when needed to avoid the need for re_paths. This should make the placeholder registration process as painless as possible. All of the builtin converters already have placeholders registered for them. Custom converters can simply add a placeholder class attribute that will be used without requiring an explicit registration.

Note

Many placeholders may be registered for a variable name/app_name. They’ll be tried until one is found to work, and prioritized in the order of most specific registration. This means a placeholder registered against app1 and variable name var1 will be tried before the placeholder registered against var1. Converters are the most specific registration info.

render_static.placeholders.register_converter_placeholder(converter_type, placeholder)

Register a placeholder for the given converter type. This registry function is intended to allow placeholders to be registered for converters outside the control of the calling code base. For converters under your control you should add a placeholder attribute to the converter class instead.

Parameters:

• converter_type (Type) – The type of the converter

• placeholder (Any) – A valid placeholder to use for the converter

Return type:

None

render_static.placeholders.register_variable_placeholder(var_name, placeholder, app_name=None)

Register a placeholder for a specific variable name and also optionally an app_name.

Parameters:

• var_name (str) – The variable name to use this placeholder for

• placeholder (Any) – The placeholder to use

• app_name (str | None) – The optional app_name.

Returns:

Return type:

None

render_static.placeholders.register_unnamed_placeholders(url_name, placeholders, app_name=None)

Register a list of placeholders for a url_name and optionally an app_name that takes unnamed arguments. The list indices should correspond to the argument order as passed to reverse.

Parameters:

• url_name (str) – The name of the url path to register the placeholders for

• placeholders (List) – The list of placeholders to use

• app_name (str | None) – The optional app_name

Return type:

None

render_static.placeholders.resolve_placeholders(var_name, app_name=None, converter=None)

Resolve placeholders for named variables that match the given lookup parameters.

Parameters:

• var_name (str) – The variable name to search for

• app_name (str | None) – The optional app_name to search for

• converter (Type | None) – The optional converter type to search for

Returns:

A list of placeholders to try

Return type:

Iterable

render_static.placeholders.resolve_unnamed_placeholders(url_name, nargs, app_name=None)

Resolve placeholders to use for a url with unnamed parameters based on the url name and optionally the app_name.

Parameters:

• url_name (str) – The name of the URL to search for

• nargs (int) – The number of arguments for this url

• app_name (str | None) – The optional app_name to search for

Returns:

A list of lists of placeholders to try, where the outer list is indexed by argument index

Return type:

Iterable