reviewboard.reviews.fields¶
Definitions for review request fields.
- class FieldSetRegistry[source]¶
Bases:
OrderedRegistry
A registry for field sets.
This keeps the fieldsets in the registered order, so iterating through them will do so in the same order.
- lookup_attrs: Sequence[str] = ('fieldset_id',)[source]¶
A list of attributes that items can be looked up by.
- errors: RegistryErrorsDict = {'already_registered': '"%(item)s" is already a registered review request fieldset.', 'not_registered': '%(attr_value)s is not a registered review request fieldset.'}[source]¶
Error formatting strings for exceptions.
Entries here override the global
DEFAULT_ERRORS
dictionary for error messages.- Type:
- register(fieldset)[source]¶
Register the fieldset.
This will also register all field classes registered on the fieldset on the field registry.
- Parameters:
fieldset (
type
) – The fieldset to register, as aBaseReviewRequestFieldSet
subclass.
- unregister(fieldset)[source]¶
Unregister the fieldset.
This will unregister all field classes on the fieldset from the field registry.
- Parameters:
fieldset (
type
) – The field to remove, as aBaseReviewRequestFieldSet
subclass.
- get_defaults()[source]¶
Return the list of built-in fieldsets.
- Returns:
A list of the built-in
BaseReviewRequestFieldSet
subclasses.- Return type:
- __annotations__ = {'_by_id': 'Dict[int, RegistryItemType]', '_items': 'Set[RegistryItemType]', '_key_order': 'List[int]', '_populated': 'bool', '_registry': 'Dict[str, Dict[object, RegistryItemType]]', 'already_registered_error_class': 'Type[AlreadyRegisteredError]', 'default_errors': 'RegistryErrorsDict', 'errors': 'RegistryErrorsDict', 'item_name': 'Optional[str]', 'lookup_attrs': 'Sequence[str]', 'lookup_error_class': 'Type[ItemLookupError]'}¶
- __parameters__ = ()¶
- class FieldRegistry[source]¶
Bases:
Registry
A registry for review request fields.
- lookup_attrs: Sequence[str] = ['field_id'][source]¶
A list of attributes that items can be looked up by.
- errors: RegistryErrorsDict = {'already_registered': '"%(item)s" is already a registered review request field. Field IDs must be unique across all fieldsets.', 'not_registered': '"%(attr_value)s is not a registered review request fieldset.'}[source]¶
Error formatting strings for exceptions.
Entries here override the global
DEFAULT_ERRORS
dictionary for error messages.- Type:
- __annotations__ = {'_items': 'Set[RegistryItemType]', '_populated': 'bool', '_registry': 'Dict[str, Dict[object, RegistryItemType]]', 'already_registered_error_class': 'Type[AlreadyRegisteredError]', 'default_errors': 'RegistryErrorsDict', 'errors': 'RegistryErrorsDict', 'item_name': 'Optional[str]', 'lookup_attrs': 'Sequence[str]', 'lookup_error_class': 'Type[ItemLookupError]'}¶
- __parameters__ = ()¶
- class BaseReviewRequestFieldSet(review_request_details, request=None)[source]¶
Bases:
object
Base class for sets of review request fields.
A fieldset stores a list of fields that are rendered on the review request page. They may contain default fields, and new fields can be added or removed.
Review Board provides three main fieldsets: “main”, “info”, and “reviewers”. Others can be added by subclassing and registering through
fieldset_registry
.Changed in version 4.0.7: Subclasses can now dynamically instantiate fields without registering their classes by overriding
build_fields()
.- fieldset_id = None[source]¶
The ID of the fieldset.
This must be unique within the
field_registry
.- Type:
- show_required = False[source]¶
Whether to show this fieldset as required.
If set, the fieldset will show as required if the user is able to modify the review request.
- Type:
- field_classes = None[source]¶
A list of fields that will by default be instantiated for the fieldset.
These would be set by subclasses to a list of
BaseReviewRequestField
subclasses.
- __init__(review_request_details, request=None)[source]¶
Initialize the field set.
- Parameters:
review_request_details (
reviewboard.reviews.models.base_review_request_details.BaseReviewRequestDetails
) – The review request or draft.request (
django.http.HttpRequest
, optional) –The HTTP request that resulted in building this fieldset.
New in version 4.0.7.
- classmethod is_empty()[source]¶
Return whether the fieldset is empty.
A fieldset is empty if there are no field classes registered. An empty fieldset will not be displayed on the page.
- classmethod add_field(field_cls)[source]¶
Add a field class to this fieldset.
The field will be rendered inside this fieldset on the page.
A given field class can only be in one fieldset. Its
field_id
must be unique.- Parameters:
field_cls (
class
) – The field class to add.
- classmethod remove_field(field_cls)[source]¶
Remove a field class from this fieldset.
The field class must have been previously added to this fieldset.
- Parameters:
field_cls (
class
) – The field class to remove.
- should_render[source]¶
Whether the fieldset should render.
By default, fieldsets should render if any contained fields should render. Subclasses can override this if they need different behavior.
New in version 4.0.7.
- Type:
- fields[source]¶
A list of all field instances in this fieldset.
Fields are instantiated through
build_fields()
the first time this is accessed.New in version 4.0.7.
- Type:
- build_fields()[source]¶
Return new fields for use in this fieldset instance.
By default, this will loop through
field_classes
and instantiate each field, returning the final list.Subclasses can override this to provide custom logic, including returning field instances that aren’t registered as field classes. This can be used to build fields tailored to a particular review request.
New in version 4.0.7.
- Returns:
The list of new field instances.
- Return type:
- __str__()[source]¶
Represent the field set as a unicode string.
- Returns:
The field set’s ID as a unicode string.
- Return type:
- __annotations__ = {}¶
- class BaseReviewRequestField(review_request_details, request=None)[source]¶
Bases:
object
Base class for a field on a review request.
A field is responsible for displaying data from a review request, handling any editing requirements if necessary, recording changes in the ChangeDescription, and rendering those changes.
Each field must have its own unique
field_id
. This ID will be used when looking up or storing the field’s value.It is recommended that fields provided by extensions prefix their field ID with some sort of identifier for the extension or the vendor.
Creating a new field requires subclassing BaseReviewRequestField and overriding any fields or functions necessary. Its class must then be added to a fieldset.
A field will be instantiated with either a ReviewRequest or a ReviewRequestDraft, depending on what is being edited. This is stored in
review_request_details
. Functions should optimistically fetch values from that, if possible. They can callget_review_request()
onreview_request_details
to fetch the actual ReviewRequest.If the function takes a
review_request_details
parameter, it must use that instead.- __init__(review_request_details, request=None)[source]¶
Initialize the field.
- Parameters:
review_request_details (
reviewboard.reviews.models.base_review_request_details.BaseReviewRequestDetails
) – The review request or draft.request (
django.http.HttpRequest
, optional) – The current HTTP request (used to check display preferences for the logged-in user).
- property value[source]¶
Return the value loaded from the database.
This will fetch the value with the associated ReviewRequest or ReviewRequestDraft, and then cache it for future lookups.
- Returns:
The value of the field.
- Return type:
- has_value_changed(old_value, new_value)[source]¶
Return whether the value has changed.
By default, it performs an inequality check on the values. This can be overridden to perform more specialized checks.
- record_change_entry(changedesc, old_value, new_value)[source]¶
Record information on the changed values in a ChangeDescription.
By default, the values are stored as-is along with the field ID. This can be overridden to perform more specialized storage.
- Parameters:
changedesc (
reviewboard.changedescs.models.ChangeDescription
) – The change description to record the entry in.old_value (
object
) – The old value of the field.new_value (
object
) – The new value of the field.
- serialize_change_entry(changedesc)[source]¶
Serialize a change entry for public consumption.
This will output a version of the change entry for use in the API. It can be the same content stored in the
ChangeDescription
, but does not need to be.- Parameters:
changedesc (
reviewboard.changedescs.models.ChangeDescription
) – The change description whose field is to be serialized.- Returns:
An appropriate serialization for the field.
- Return type:
- serialize_change_entry_for_model_list(field_info)[source]¶
Return the change entry for a list of models.
- serialize_change_entry_for_singleton(field_info)[source]¶
Return the change entry for a singleton.
Singleton fields (e.g., summaries) are stored in
ChangeDescription
as a list with a single element.
- serialize_change_entry_for_list(field_info)[source]¶
Return the change entry for a list of plain data.
- get_change_entry_sections_html(info)[source]¶
Return sections of change entries with titles and rendered HTML.
By default, this just returns a single section for the field, with the field’s title and rendered change HTML.
Subclasses can override this to provide more information.
- render_change_entry_html(info)[source]¶
Render a change entry to HTML.
By default, this returns a simple “changed from X to Y” using the old and new values. This can be overridden to generate more specialized output.
This function is expected to return safe, valid HTML. Any values coming from a field or any other form of user input must be properly escaped.
Subclasses can override
render_change_entry_value_html
to change how the value itself will be rendered in the string.
- render_change_entry_added_value_html(info, value)[source]¶
Render the change entry for an added value to HTML.
- render_change_entry_removed_value_html(info, value)[source]¶
Render the change entry for a removed value to HTML.
- render_change_entry_value_html(info, value)[source]¶
Render the value for a change description string to HTML.
By default, this just converts the value to text and escapes it. This can be overridden to customize how the value is displayed.
- load_value(review_request_details)[source]¶
Load a value from the review request or draft.
By default, this loads the value as-is from the extra_data field. This can be overridden if you need to deserialize the value in some way.
This must use
review_request_details
instead ofself.review_request_details
.- Parameters:
review_request_details (
reviewboard.reviews.models.base_review_request_details.BaseReviewRequestDetails
) – The review request or draft.
- save_value(value)[source]¶
Save the value in the review request or draft.
By default, this saves the value as-is in the extra_data field. This can be overridden if you need to serialize the value in some way.
- Parameters:
value (
object
) – The new value for the field.
- propagate_data(review_request_details)[source]¶
Propagate data in from source review request or draft.
By default, this loads only the field’s value from a source review request or draft and saves it as-is into the review request or draft associated with the field. This can be overridden if you need to propagate additional data elements.
This method is preferable to explicitly calling
load_value()
andsave_value()
in series to propagate data from a source into a field, because it allows for copying additional data elements beyond only the field’s value.This function must use the
review_request_details
parameter instead of thereview_request_details
attribute on the field.- Parameters:
review_request_details (
reviewboard.reviews.models.base_review_request_details.BaseReviewRequestDetails
) – The source review request or draft whose data is to be propagated.
- render_value(value)[source]¶
Render the value in the field.
By default, this converts to text and escapes it. This can be overridden if you need to render it in a more specific way.
This must use
value
instead ofself.value
.
- get_css_classes()[source]¶
Return the set of CSS classes to apply to the element.
By default, this will include the contents of
default_css_classes
, andrequired
if it’s a required field.This can be overridden to provide additional CSS classes, if they’re not appropriate for
default_css_classes
.
- get_dom_attributes()[source]¶
Return any additional attributes to include in the element.
By default, this returns nothing.
- Returns:
Additional key/value pairs for attributes to include in the rendered HTML element.
- Return type:
- get_data_attributes()[source]¶
Return any data attributes to include in the element.
By default, this returns nothing.
- Returns:
The data attributes to include in the element.
- Return type:
- as_html()[source]¶
Return the field rendered to HTML.
- Returns:
The rendered field.
- Return type:
django.utils.safetext.SafeString
- value_as_html()[source]¶
Return the field rendered as HTML.
By default, this just calls
render_value
with the value from the database.- Returns:
The rendered field.
- Return type:
- __str__()[source]¶
Represent the field as a unicode string.
- Returns:
The field’s ID as a unicode string.
- Return type:
- __annotations__ = {}¶
- class BaseEditableField(review_request_details, request=None)[source]¶
Bases:
BaseReviewRequestField
Base class for an editable field.
This simply marks the field as editable.
- js_view_class = 'RB.ReviewRequestFields.TextFieldView'[source]¶
The class name for the JavaScript view representing this field.
- __annotations__ = {}¶
- class BaseCommaEditableField(review_request_details, request=None)[source]¶
Bases:
BaseEditableField
Base class for an editable comma-separated list of values.
This is used for dealing with lists of items that appear comma-separated in the UI. It works with stored lists of content on the review request or draft, and on the ChangeDescription.
Subclasses can override this to provide specialized rendering on a per-item-basis. That’s useful for showing links to items, for example.
- js_view_class = 'RB.ReviewRequestFields.CommaSeparatedValuesTextFieldView'[source]¶
The class name for the JavaScript view representing this field.
- has_value_changed(old_value, new_value)[source]¶
Return whether two values have changed.
If
order_matters
is set toTrue
, this will do a strict list comparison. Otherwise, it will compare the items in both lists without caring about the ordering.
- serialize_change_entry(changedesc)[source]¶
Serialize a change entry for public consumption.
This will output a version of the change entry for use in the API. It can be the same content stored in the
ChangeDescription
, but does not need to be.- Parameters:
changedesc (
reviewboard.changedescs.models.ChangeDescription
) – The change description whose field is to be serialized.- Returns:
An appropriate serialization for the field.
- Return type:
- render_value(values)[source]¶
Render the list of items.
This will call out to
render_item
for every item. The list of rendered items will be separated by a comma and a space.
- render_item(item)[source]¶
Render an item from the list.
By default, this will convert the item to text and then escape it.
- render_change_entry_html(info)[source]¶
Render a change entry to HTML.
By default, this returns HTML containing a list of removed items, and a list of added items. This can be overridden to generate more specialized output.
This function is expected to return safe, valid HTML. Any values coming from a field or any other form of user input must be properly escaped.
- render_change_entry_value_html(info, values)[source]¶
Render a list of items for change description HTML.
By default, this will call
render_change_entry_item_html
for every item in the list. The list of rendered items will be separated by a comma and a space.
- render_change_entry_item_html(info, item)[source]¶
Render an item for change description HTML.
By default, this just converts the value to text and escapes it. This can be overridden to customize how the value is displayed.
- __annotations__ = {}¶
- class BaseTextAreaField(review_request_details, request=None)[source]¶
Bases:
BaseEditableField
Base class for a multi-line text area field.
The text area can take either plain text or Markdown text. By default, Markdown is supported, but this can be changed by setting
enable_markdown
toFalse
.- js_view_class = 'RB.ReviewRequestFields.MultilineTextFieldView'[source]¶
The class name for the JavaScript view representing this field.
- text_type_key[source]¶
Return the text type key for the
extra_data
dictionary.- Returns:
The key which stores the text type for the field.
- Return type:
- is_text_markdown(value)[source]¶
Return whether the text is in Markdown format.
This can be overridden if the field needs to check something else to determine if the text is in Markdown format.
- propagate_data(review_request_details)[source]¶
Propagate data in from source review request or draft.
In addition to the value propagation handled by the base class, this copies the text type details from a source review request or draft and saves it as-is into the review request or draft associated with the field.
- Parameters:
review_request_details (
reviewboard.reviews.models.base_review_request_details.BaseReviewRequestDetails
) – The source review request or draft whose data is to be propagated.
- get_css_classes()[source]¶
Return the list of CSS classes.
If Markdown is enabled, and the text is in Markdown format, this will add a “rich-text” field.
- get_data_attributes()[source]¶
Return any data attributes to include in the element.
By default, this returns nothing.
- Returns:
The data attributes to include in the element.
- Return type:
- render_value(text)[source]¶
Return the value of the field.
If Markdown is enabled, and the text is not in Markdown format, the text will be escaped.
- should_render_as_markdown(value)[source]¶
Return whether the text should be rendered as Markdown.
By default, this checks if the field is set to always render any text as Markdown, or if the given text is in Markdown format.
- render_change_entry_html(info)[source]¶
Render a change entry to HTML.
This will render a diff of the changed text.
This function is expected to return safe, valid HTML. Any values coming from a field or any other form of user input must be properly escaped.
- __annotations__ = {}¶
- class BaseCheckboxField(review_request_details, request=None)[source]¶
Bases:
BaseReviewRequestField
Base class for a checkbox.
The field’s value will be either True or False.
- js_view_class = 'RB.ReviewRequestFields.CheckboxFieldView'[source]¶
The class name for the JavaScript view representing this field.
- load_value(review_request_details)[source]¶
Load a value from the review request or draft.
- Parameters:
review_request_details (
reviewboard.reviews.models.base_review_request_details.BaseReviewRequestDetails
) – The review request or draft.- Returns:
The loaded value.
- Return type:
- render_change_entry_html(info)[source]¶
Render a change entry to HTML.
This function is expected to return safe, valid HTML. Any values coming from a field or any other form of user input must be properly escaped.
- render_change_entry_value_html(info, value)[source]¶
Render the value for a change description string to HTML.
- get_dom_attributes()[source]¶
Return any additional attributes to include in the element.
By default, this returns nothing.
- Returns:
Additional key/value pairs for attributes to include in the rendered HTML element.
- Return type:
- value_as_html()[source]¶
Return the field rendered as HTML.
Because the value is included as a boolean attribute on the checkbox element, this just returns the empty string.
- Returns:
The rendered field.
- Return type:
- __annotations__ = {}¶
- class BaseDropdownField(review_request_details, request=None)[source]¶
Bases:
BaseReviewRequestField
Base class for a drop-down field.
- js_view_class = 'RB.ReviewRequestFields.DropdownFieldView'[source]¶
The class name for the JavaScript view representing this field.
- options = [][source]¶
A list of the available options for the dropdown.
Each entry in the list should be a 2-tuple of (value, label). The values must be unique. Both values and labels should be unicode.
- load_value(review_request_details)[source]¶
Load a value from the review request or draft.
- Parameters:
review_request_details (
reviewboard.reviews.models.base_review_request_details.BaseReviewRequestDetails
) – The review request or draft.- Returns:
The loaded value.
- Return type:
- render_change_entry_value_html(info, value)[source]¶
Render the value for a change description string to HTML.
- value_as_html()[source]¶
Return the field rendered as HTML.
Select tags are funny kinds of inputs, and need a bunch of
<option>
elements inside them. This renders the “value” of the field as those options, to fit in with the base field’s template.- Returns:
The rendered field.
- Return type:
django.utils.safestring.SafeText
- __annotations__ = {}¶
- class BaseDateField(review_request_details, request=None)[source]¶
Bases:
BaseEditableField
Base class for a date field.
- js_view_class = 'RB.ReviewRequestFields.DateFieldView'[source]¶
The class name for the JavaScript view representing this field.
- load_value(review_request_details)[source]¶
Load a value from the review request or draft.
- Parameters:
review_request_details (
reviewboard.reviews.models.base_review_request_details.BaseReviewRequestDetails
) – The review request or draft.- Returns:
The loaded value.
- Return type:
- __annotations__ = {}¶
- get_review_request_fields()[source]¶
Yield all registered field classes.
- Yields:
type
– The field classes, as subclasses ofBaseReviewRequestField
- get_review_request_fieldsets(include_change_entries_only=False)[source]¶
Return a list of all registered fieldset classes.
As an internal optimization, the “main” fieldset can be filtered out, to help with rendering the side of the review request page.
- get_review_request_fieldset(fieldset_id)[source]¶
Return the fieldset with the specified ID.
- Parameters:
fieldset_id (
unicode
) – The fieldset’s ID.- Returns:
The requested fieldset, or
None
if it could not be found.- Return type:
- get_review_request_field(field_id)[source]¶
Return the field with the specified ID.
- Parameters:
field_id (
unicode
) – The field’s ID.- Returns:
The requested field, or
None
if it could not be found.- Return type:
- register_review_request_fieldset(fieldset)[source]¶
Register a custom review request fieldset.
The fieldset must have a
fieldset_id
attribute. This ID must be unique across all registered fieldsets, or an exception will be thrown.- Parameters:
fieldset (
type
) – TheBaseReviewRequestFieldSet
subclass.- Raises:
djblets.registries.errors.ItemLookupError – This will be thrown if a fieldset is already registered with the same ID.
- unregister_review_request_fieldset(fieldset)[source]¶
Unregister a previously registered review request fieldset.
- Parameters:
fieldset (
type
) – TheBaseReviewRequestFieldSet
subclass.- Raises:
djblets.registries.errors.ItemLookupError – This will be thrown if the fieldset is not already registered.