Repository files navigation

This project is an opinionated implementation of JSONField for arbitrary HTMLelement attributes.

It aims to provide a sensible means of storing and managingarbitrary HTML element attributes for later emitting them into templates.

There are a wide variety of types of attributes and using the "normal" Djangomethod of adding ModelFields for each on a business model is cumbersome atbest and moreover may require related tables to allow cases where any numberof the same type of attribute should be supported (i.e., data-attributes).This can contribute to performance problems.

To avoid these pitfalls, this package allows all of these attributes to bestored together in a single text field in the database as a JSON blob, butprovides a nice widget to provide an intuitive, key/value pair interfaceand provide sensible validation of the keys used.

Because this is a an open-source project, we welcome everyone toget involved in the project andreceive a reward for their contribution.Become part of a fantastic community and help us make django CMS the best CMS in the world.

We'll be delighted to receive yourfeedback in the form of issues and pull requests. Before submitting yourpull request, please review ourcontribution guidelines.

We're grateful to all contributors who have helped create and maintain this package.Contributors are listed at thecontributorssection.

SeeREQUIREMENTS in thesetup.pyfile for additional dependencies:

For a manual install:

• runpip install djangocms-attributes-field
• adddjangocms_attributes_field to yourINSTALLED_APPS (at least for CSP support)
• runpython manage.py migrate djangocms_attributes_field

To use this field in your Models.model:

# models.py...from django.db import modelsfrom djangocms_attributes_field.fields import AttributesField...MyCoolModel(models.Model):    ...    attributes = AttributesField()

That's it!

There is an optional parameter that can be used when declaring the field:

``excluded_keys`` : This is a list of strings that will not be accepted as                    valid keys

Since version 4, the following keys are always excluded (seedjangocms_attributes_fields.fields.default_excluded_keys) to avoidunwanted execution of #"src", "href", "data", "action", "on*"]

'on*' represents any key that starts with'on'.

AttributeField will also provide a handy property[field_name]_strthat will emit the stored key/value pairs as a string suitable for inclusionin your template for the target HTML element in question. You can use itlike this:

# models.py...MyCoolModel(models.Model):    ...    html_attributes = AttributesField()# templates/my_cool_project/template.html...<a href="..." {{ object.html_attributes_str }}>click me</a>...

(Assuming thatobject is a context variable containing aMyCoolModel instance.)

In addition to nicely encapsulating the boring task of converting key/valuepairs into a string with proper escaping and marking-safe, this property alsoensures thatexisting key/value pairs with keys that have since been addedto the field'sexcluded_keys are also not included in the output string.

TheAttributesWidget is already used by default by theAttributesField,but there may be cases where you'd like to override its usage.

The widget supports two additional parameters:

``key_attrs`` : A dict of HTML attributes to apply to the key input field``val_attrs`` : A dict of HTML attributes to apply to the value input field

These can be useful, for example, if it is necessary to alter the appearanceof the widget's rendered appearance. Again, for example, let's say we neededto make the key and value inputs have specific widths. We could do this likeso in ourModelForm:

# forms.pyfrom django import formsfrom djangocms_attributes_field.widgets import AttributesWidgetMyCoolForm(forms.ModelForm):    class Meta:        fields = ['attributes', ...]    def __init__(self, *args, **kwargs):        super().__init__(*args, **kwargs)        self.fields['attributes'].widget = AttributesWidget(key_attrs={'style': 'width:250px'},                                                            val_attrs={'style': 'width:500px'})

You can run tests by executing:

virtualenv envsource env/bin/activatepip install -r tests/requirements.txtpython tests/settings.py