tpl.py

Various formatting functions, primarily to be used in:

Since version 0.8.0, the significant part of the module is implemented via djk_ui package.

Renderer

Since version 0.8.0, Renderer class is implemented which is internally used to render formsets / forms / fields of Django modelforms. See Renderers and Forms base module for more detail. It’s usage is not limited to forms as it supports rendering of any object with the related context data and template with possible nesting of renderers.

Contenttypes framework helpers

  • ContentTypeLinker - class to simplify generation of contenttypes framework object links:

    {% set ctl = tpl.ContentTypeLinker(request.user, object, 'content_type', 'object_id') %}
{% if ctl.url is not none %}
    <a href="{{ ctl.url }}" title="{{ str(ctl.obj_type) }}" target="_blank">
{% endif %}
    {{ ctl.desc }}
{% if ctl.url is not none %}
    </a>
{% endif %}

Manipulation with css classes

  • escape_css_selector() - can be used with server-generated AJAX viewmodels or in Selenium tests.
  • add_css_classes() - similar to client-side jQuery .addClass();
  • has_css_classes() - similar to client-side jQuery .hasClass();
  • remove_css_classes() - similar to client-side jQuery .removeClass();

Optimized for usage as argument of Django flatatt():

  • add_css_classes_to_dict() - adds CSS classes to the end of the string
  • has_css_classes_in_dict()
  • prepend_css_classes_to_dict() - adds CSS classes to the begin of the string
  • remove_css_classes_from_dict()

Objects rendering

  • Str - string with may have extra attributes. It’s used with get_absolute_url() Django model method. See get_absolute_url() documentation and get_absolute_url() sample:

    class Manufacturer(models.Model):

    # ... skipped ...

    title = models.CharField(max_length=64, unique=True, verbose_name='Title')

    def get_absolute_url(self):
        url = Str(reverse('club_detail', kwargs={'club_id': self.pk}))
        url.text = str(self.title)
        return url

  • ModelLinker - render Model links with descriptions which supports get_absolute_url() and get_str_fields model formatting / serialization. Since v2.1.0, optional request_user argument can be defined for custom get_absolute_url() Django model method which then may be used to hide part of url.text per user permissions. In such case ModelLinker / ContentTypeLinker instance should be initialized with request_user value, when available:

    from django_jinja_knockout import tpl

obj = Model.objects.get(pk=1)
ctl = tpl.ContentTypeLinker(request.user, obj.content, 'content_type', 'object_id')
content_type_str = ctl.get_str_obj_type()
# nested serialization of generic relation optional check of request.user permissions
# see serializers.py
content_tree = ctl.get_nested_data()
# render nested serialization to str
content_tree_str = tpl.print_list(content_tree)
# get url / description text of content_object, when available
content_url = obj.content.content_object.get_absolute_url(request_user)
content_desc = ctl.desc if content_url is none else content_url.text

  • PrintList class supports custom formatting of nested Python structures, including the mix of dicts and lists. There are some already setup function helpers which convert nested content to various (HTML) string representations, using PrintList class instances:

    • print_list() - print nested HTML list. Used to format HTML in JSON responses and in custom DisplayText widgets.
    • print_brackets() - print nested brackets list.
    • print_table() - print uniform 2D table (no colspan / rowspan yet).
    • print_bs_labels() - print HTML list as Bootstrap labels.
    • reverseq() - construct url with query parameters from url name. When request instance is supplied, absolute url will be returned.

  • str_dict() - Django models could define get_str_fields model formatting / serialization method which maps model instance field values to their formatted string values, similar to Model __str()__ method, but for each or to some selected separate fields. If these models have foreign keys pointing to another models which also have get_str_fields model formatting / serialization defined, str_dict() can be used to convert nested dict get_str_fields model formatting / serialization values to flat strings in __str__() method:

    class Member(models.Model):

    # ... skipped ...

    def get_str_fields(self):
        parts = OrderedDict([
            ('profile', self.profile.get_str_fields()),
            ('club', self.club.get_str_fields()),
            ('last_visit', format_local_date(timezone.localtime(self.last_visit))),
            ('plays', self.get_plays_display()),
            ('role', self.get_role_display()),
            ('is_endorsed', 'endorsed' if self.is_endorsed else 'unofficial')
        ])
        return parts

    def __str__(self):
        # Will flatten 'profile' and 'club' str_fields dict keys values
        # and convert the whole str_fields dict values into str.
        str_fields = self.get_str_fields()
        return str_dict(str_fields)

Internally str_dict() uses lower level flatten_dict() function which is defined in the same module.

String manipulation

  • limitstr() - cut string after specified length.
  • repeat_insert() - separate string every nth character with specified separator characters.

String formatting

  • json_flatatt() - similar to Django flatatt(), but converts dict / list / tuple / bool HTML attribute values to JSON string. Used in Jinja2 macros.
  • format_html_attrs() - similar to Django format_html(), but converts dict / list / tuple / bool HTML attribute values to JSON string. Used to generate Components.
  • format_local_date() - output localized Date / DateTime.
  • html_to_text() - convert HTML fragment with anchor links into plain text with text links. It’s used in utils/mail.py SendmailQueue to convert HTML body of email message to text-only body.
  • to_json() - converts Python structures to JSON utf-8 string.

URL resolution

  • get_formatted_url() converts url with supplied url_name from regex named parameters eg. (?P<arg>\w+) to sprintf() named formatters eg. %(arg)s. Such urls are injected into client-side as Client-side routes and then are resolved via the bundled sprintf.js library.

  • resolve_cbv() takes url_name and it’s kwargs and returns a function view or a class-based view for these arguments, when available:

    tpl.resolve_cbv(url_name, view_kwargs)

Current request’s url_name can be obtained from the request .resolver_match .url_name, or .view_name for namespaced urls.