Welcome to django-gollum¶

In Form Classes¶

gollum gives you the ability to specify HTML attributes easily on a form class. You can specify HTML attributes on any number of fields on your form by using an Attrs inner class within your form:

from gollum import forms

class MyGollumForm(forms.Form):
    foo = forms.IntegerField()
    bar = forms.IntegerField()

    class Attrs:
        foo = { 'disabled': 'true' }

The above code will cause the form, when rendered, to add a disabled="true" HTML attribute to the foo field (but do nothing to the bar field).

A common use-case for this, if you’re using HTML5 forms, is to set a placeholder attribute. This causes the browser to display default text in the input field until it gains focus:

from gollum import forms

class UserForm(forms.Form):
    first_name = forms.CharField(max_length=30)
    last_name = forms.CharField(max_length=30)
    email = forms.EmailField(max_length=75)
    phone = forms.CharField(max_length=15, required=False)

    class Attrs:
        phone = { 'placeholder': 'Optional' }

This code would cause the phone widget to look like this:

<input name="phone" id="id_phone" type="text" placeholder="optional">

In Templates¶

Even though the Django documentation only exposes a way to set attributes in form widgets themselves, one could argue that a better place for HTML attribute information to live is in the template itself, especially since a form could be used in different templates and need different attributes set.

gollum does not expose a special mechanism to do this (yet). However, this can be accomplished by directly calling the as_widget method of a bound field in Django.

The problem: as_widget takes arguments, so you’ll either need to write a template tag to send the necessary arguments to it, or use a template language that supports arguments (such as Jinja).

Here’s a quick sample of the latter option:

{% for field in user_form %}
    {{ field.as_widget(attrs={ 'placeholder': field.label }) }}
{% endfor %}

This method allows you not to specify HTML attributes on your form class at all, and may be preferable, especially if the HTML attributes change depending on where the form is rendered.

CSS¶

It would be possible to specify CSS classes in this way, by writing directly to the class HTML attribute. But don’t; gollum also exposes a way to specify CSS classes.

In Form Classes¶

In order to specify a CSS class on a form, declare a CSS inner class in your Form class, and specify any classes to apply:

from gollum import forms

class MyForm(forms.Form):
    foo = models.CharField(max_length=50)
    bar = models.IntegerField()

    class CSS:
        foo = {'spam', 'eggs'}

The above code, when rendered in an template, will cause the <input> tag for the foo field to have two CSS classes: spam and eggs.

You can specify CSS classes here using a list, set, or tuple. You can also use a string if you have only one CSS class, or you can even use a space-separated string like you would in actual HTML markup.

The following CSS inner-class is identical to the one in the example above:

class CSS:
    foo = 'spam eggs'

Order of class specification doesn’t matter; it’ll be normalized to a Python set, which is unordered. Duplicate classes don’t matter either, for the same reason.

In Templates¶

It may be preferable for your use case to specify CSS classes in templates rather than in the form itself. (This does seem like where such information naturally belongs.)

Again, like in HTML Attributes, the solution is the as_widget method. The story’s a little different this time, though: Django doesn’t provide a clean way to specify CSS classes, so gollum actually subclasses BoundField to provide one.

That mechanism is the css_classes keyword argument:

{% for field in form %}
    {{ field.as_widget(css_classes='myclass') }}
{% endfor %}

Much like the specification above, you can send a list (or other, similar iterable) or a string, and gollum will do the right thing.

FORM_REQUIRED_CSS_CLASS¶

• Default: (not set)
• Type: str

If specified, the given CSS class will be added to every required field on every gollum form.

FORM_ERROR_CSS_CLASS¶

• Default: (not set)
• Type: str

If specified, the given CSS class will be added to every field that is in an error state on every gollum form.

FORM_GLOBAL_CSS_CLASS¶

• Default: (not set)
• Type: str

If specified, the given CSS class will be added to every field, period, the end.

FORM_REQUIRED_ATTRS¶

• Default: (not set)
• Type: dict

If specified, the given HTML attributes will be applied to every required field on every gollum form.

Example:

FORM_REQUIRED_ATTRS = { 'required': 'true' }

FORM_OPTIONAL_ATTRS¶

• Default: (not set)
• Type: dict

If specified, the given HTML attributes will be applied to every field that is not required on any gollum form.

Example:

FORM_OPTIONAL_ATTRS = { 'placeholder': 'Optional' }

FORM_GLOBAL_ATTRS¶

• Default: (not set)
• Type: dict

If specified, the given HTML attributes will be applied to every form field on every gollum form.