djblets.conditions.values¶
Base support and standard value field wrappers for conditions.
- class BaseConditionValueField¶
Bases:
object
Base class for a field for editing and representing condition values.
This is used to provide a field in the UI that can be used for editing a condition value. It’s responsible for rendering the field, preparing data for the field, retrieving the data from the HTML form data, and handling JSON-safe serialization/deserialization of values.
Subclasses can specify custom logic for all these operations, and can specify the JavaScript counterparts for the class used to edit the values.
- js_model_class = 'Djblets.Forms.ConditionValueField'¶
The JavaScript model class for representing field state.
This is instantiated on the web UI and is used to store any model data provided by
get_js_model_data()
.The default is a simple model that just stores the model data as attributes.
- js_view_class = None¶
The JavaScript view class for editing fields.
This is instantiated on the web UI and is used to provide an editor for the condition’s value.
It’s passed any options that are returned from
get_js_model_data()
.
- serialize_value(value)¶
Serialize a Python object into a JSON-compatible serialized form.
This is responsible for taking a Python value/object of some sort (string, list, or anything more complex) and returning a JSON-compatible form for serialization.
By default, this returns the value as-is.
- deserialize_value(serialized_value)¶
Deserialize a value back into a Python object.
This is responsible for taking a value serialized by
serialize_value()
and returning a suitable Python object/value.By default, this returns the value as-is.
- Parameters:
serialized_value (
object
) – The serialized value to deserialize.- Returns:
The deserialized value.
- Return type:
- Raises:
djblets.conditions.errors.InvalidConditionValueError – Error deserializing or validating the data.
- get_from_form_data(data, files, name)¶
Return a value from a form data dictionary.
This attempts to return the value for a condition from Django form data. It’s passed a dictionary of data, uploaded files, and the name of the appropriate value field.
Subclasses can override this to normalize the value before returning.
- prepare_value_for_widget(value)¶
Return a value suitable for use in the widget.
The value will be passed to the widget’s JavaScript UI. It can be used in special cases where a Python object needs to be converted to another form in order to work properly client-side.
By default, the value is returned as-is.
- get_js_model_data()¶
Return data for the JavaScript model for this field.
The returned data will be set as attributes on the Backbone model pointed to by
js_model_class
.By default, this includes the rendered HTML as
fieldHTML
, which should generally be provided (but is not required, depending on the field).- Returns:
The model data. This must be serializable as JSON.
- Return type:
- get_js_view_data()¶
Return data for the JavaScript view for this field.
The returned data will be set as options on the Backbone view pointed to by
js_view_class
.This is empty by default.
- Returns:
The view data. This must be serializable as JSON.
- Return type:
- render_html()¶
Return rendered HTML for the field.
The rendered HTML will be inserted dynamically by the JavaScript UI.
This must be implemented by subclasses.
- Returns:
The rendered HTML for the field. This does not need to be marked as safe (but can be), as it will be passed in as an escaped JavaScript string.
- Return type:
- class ConditionValueFormField(field)¶
Bases:
BaseConditionValueField
Condition value wrapper for HTML form fields.
This allows the usage of standard HTML form fields (through Django’s
django.forms
module) for rendering and accepting condition values.Callers simply need to instantiate the class along with a form field.
The rendered field must support setting and getting a
value
attribute on the DOM element, like a standard HTML form field.Example
- value_field = ConditionValueFormField(
forms.ModelMultipleChoiceField(queryset=MyModel.objects.all()))
- js_model_class = 'Djblets.Forms.ConditionValueField'¶
The JavaScript model class for representing field state.
This is instantiated on the web UI and is used to store any model data provided by
get_js_model_data()
.The default is a simple model that just stores the model data as attributes.
- js_view_class = 'Djblets.Forms.ConditionValueFormFieldView'¶
The JavaScript view class for editing fields.
This is instantiated on the web UI and is used to provide an editor for the condition’s value.
It’s passed any options that are returned from
get_js_model_data()
.
- __init__(field)¶
Initialize the value field.
- Parameters:
field (
django.forms.fields.Field
) – The Django form field instance for the value. This may also be a callable that returns a field.
- property field¶
The form field to use for the value.
This will always return a
Field
, but can be given a callable that returns a field when set.
- serialize_value(value)¶
Serialize a Python object into a JSON-compatible serialized form.
This is responsible for taking a Python value/object of some sort (string, list, or anything more complex) and returning a JSON-compatible form for serialization. It will use the form field to do this (through
Field.prepare_value()
).
- deserialize_value(value_data)¶
Deserialize a value back into a Python object.
This is responsible for taking a value serialized by
serialize_value()
and returning a suitable Python object/value. It will use the form field to do this (throughField.clean()
).By default, this returns the value as-is.
- Parameters:
serialized_value (
object
) – The serialized value to deserialize.- Returns:
The deserialized value.
- Return type:
- Raises:
djblets.conditions.errors.InvalidConditionValueError – Error deserializing or validating the data.
- get_from_form_data(data, files, name)¶
Return a value from a form data dictionary.
This attempts to return the value for a condition from Django form data. It’s passed a dictionary of data, uploaded files, and the name of the appropriate value field. It will use the form field’s widget to do this (through
Widget.value_from_datadict
).
- render_html()¶
Return rendered HTML for the field.
The rendered HTML will be generated by the widget for the field, and will be dynamically inserted by the JavaScript UI.
- Returns:
The rendered HTML for the field.
- Return type:
- __annotations__ = {}¶
- class ConditionValueBooleanField(**field_kwargs)¶
Bases:
ConditionValueFormField
Condition value wrapper for boolean form fields.
This is a convenience for condition values that want to use a
BooleanField
. It accepts the same keyword arguments in the constructor that the field itself accepts.It also specially serializes the value to a string for use in the JavaScript widget.
Example
value_field = ConditionValueBooleanField(initial=True)
- __init__(**field_kwargs)¶
Initialize the value field.
- Parameters:
**field_kwargs (
dict
) – Keyword arguments to pass to theBooleanField
constructor.
- prepare_value_for_widget(value)¶
Return a value suitable for use in the widget.
This will convert a boolean value to a string, so that it can be properly matched against the string choices for the select box.
- __annotations__ = {}¶
- class ConditionValueCharField(**field_kwargs)¶
Bases:
ConditionValueFormField
Condition value wrapper for single-line text form fields.
This is a convenience for condition values that want to use a
CharField
. It accepts the same keyword arguments in the constructor that the field itself accepts.Example
value_field = ConditionValueCharField(max_length=100)
- __init__(**field_kwargs)¶
Initialize the value field.
- Parameters:
**field_kwargs (
dict
) – Keyword arguments to pass to theCharField
constructor.
- __annotations__ = {}¶
- class ConditionValueIntegerField(**field_kwargs)¶
Bases:
ConditionValueFormField
Condition value wrapper for integer form fields.
This is a convenience for condition values that want to use a
IntegerField
. It accepts the same keyword arguments in the constructor that the field itself accepts.Example
value_field = ConditionValueIntegerField(min_value=0, max_value=100)
- __init__(**field_kwargs)¶
Initialize the value field.
- Parameters:
**field_kwargs (
dict
) – Keyword arguments to pass to theIntegerField
constructor.
- __annotations__ = {}¶
- class ConditionValueMultipleChoiceField(**field_kwargs)¶
Bases:
ConditionValueFormField
Condition value wrapper for multiple choice fields.
This is a convenience for condition values that want to use a
MultipleChoiceField
. It accepts the same keyword arguments in the constructor that the field itself accepts.New in version 3.0.
Example
value_field = ConditionValueMultipleChoiceField( choices=[ ('value1', 'Value 1'), ('value2', 'Value 2'), ])
- __init__(**field_kwargs)¶
Initialize the value field.
- Parameters:
**field_kwargs (
dict
) – Keyword arguments to pass to theMultipleChoiceField
constructor.
- __annotations__ = {}¶
- class ConditionValueModelField(queryset, **field_kwargs)¶
Bases:
ConditionValueFormField
Condition value wrapper for single model form fields.
This is a convenience for condition values that want to use a
ModelChoiceField
. It accepts the same keyword arguments in the constructor that the field itself accepts.Unlike the standard field, the provided queryset can be a callable that returns a queryset.
Example
value_field = ConditionValueModelField(queryset=MyObject.objects.all())
- __init__(queryset, **field_kwargs)¶
Initialize the value field.
- Parameters:
queryset (
django.db.models.query.QuerySet
) – The queryset used for the field. This may also be a callable that returns a queryset.**field_kwargs (
dict
) – Keyword arguments to pass to theModelChoiceField
constructor.
- __annotations__ = {}¶
- class ConditionValueMultipleModelField(queryset, **field_kwargs)¶
Bases:
ConditionValueFormField
Condition value wrapper for multiple model form fields.
This is a convenience for condition values that want to use a
ModelMutipleChoiceField
. It accepts the same keyword arguments in the constructor that the field itself accepts.Unlike the standard field, the provided queryset can be a callable that returns a queryset.
Example
- value_field = ConditionValueMultipleModelField(
queryset=MyObject.objects.all())
- __init__(queryset, **field_kwargs)¶
Initialize the value field.
- Parameters:
queryset (
django.db.models.query.QuerySet
) – The queryset used for the field. This may also be a callable that returns a queryset.**field_kwargs (
dict
) – Keyword arguments to pass to theModelChoiceField
constructor.
- __annotations__ = {}¶
- class ConditionValueRegexField(**field_kwargs)¶
Bases:
ConditionValueCharField
Condition value for fields that accept regexes.
This value accepts and validates regex patterns entered into the field.
Example
value_field = ConditionValueRegexField()
- __annotations__ = {}¶
- serialize_value(value)¶
Serialize a compiled regex into a string.
- deserialize_value(value_data)¶
Deserialize a regex pattern string into a compiled regex.
- Parameters:
value_data (
unicode
) – The serialized regex pattern to compile.- Returns:
The deserialized value.
- Return type:
- Raises:
djblets.conditions.errors.InvalidConditionValueError – The regex could not be compiled.