reviewboard.actions.base¶

Base classes for actions.

class AttachmentPoint[source]¶

Bases: object

Attachment points for actions.

New in version 6.0.

NON_UI = 'non-ui'[source]¶

Attachment for actions which do not want to render in the UI.

This can be used for actions which want to be JavaScript-only, and may be used in the future for things like keyboard shortcuts or a command-K bar.

ADMIN_NAV = 'admin-nav'[source]¶

Administration navigation.

New in version 8.0.

HEADER = 'header'[source]¶

Attachment for actions in the page header.

REVIEW_REQUEST_LEFT = 'review-request-left'[source]¶

Attachment for actions on the left side of the review request header.

REVIEW_REQUEST = 'review-request'[source]¶

Attachment for actions on the right side of the review request header.

UNIFIED_BANNER = 'unified-banner'[source]¶

Attachment for actions in the unified draft banner.

QUICK_ACCESS = 'quick-access'[source]¶

Attachment for actions in the quick access area.

New in version 8.0.

class ActionAttachmentPoint(attachment_point_id: str | None = None, *, actions: Sequence[str] | None = None, actions_registry: ActionsRegistry | None = None, default_action_group_renderer_cls: type[BaseActionGroupRenderer] | None = None, default_action_renderer_cls: type[BaseActionRenderer] | None = None)[source]¶

Bases: object

An attachment point for a list of actions.

Attachment points manage the display and registration of the UI side of actions. They may contain any number of pre-defined actions, and will automatically contain any actions dynamically registered to the attachment point.

Actions rendered in an attachment point will use their own default renderer if specified, and fall back to the attachment point’s default renderer. This order ensures that an attachment point may, for instance, default to buttons but that a menu button can still be added and rendered correctly.

An attachment point can be registered in a central registry so that it can be referred to by name. It may also be unregistered and passed directly to any templates that want to render the actions.

To include an attachment point on a page, use the {% actions_html %} template tag.

New in version 8.0.

__init__(attachment_point_id: str | None = None, *, actions: Sequence[str] | None = None, actions_registry: ActionsRegistry | None = None, default_action_group_renderer_cls: type[BaseActionGroupRenderer] | None = None, default_action_renderer_cls: type[BaseActionRenderer] | None = None) → None[source]¶

Initialize the attachment point.

Parameters:

• attachment_point_id (str, optional) –

  The unique ID for this attachment point.

  This must be provided if attachment_point_id is not already set.

• actions (list of str, optional) –

  An explicit list of action IDs to include in this attachment point.

  Any actions listed here will be listed first in the specified order. Any additional actions registered to this attachment point will be added after these actions.

• actions_registry (reviewboard.actions.registry.ActionsRegistry, optional) –

  The registry managing actions for this attachment point.

  This is primarily for unit test purposes.

• default_action_group_renderer_cls (type, optional) –

  The default action renderer used for child action groups.

  This will be used for any actions that don’t already have a default action renderer set. The action’s default takes precedence in order to allow actions such as menus to manage their own display.

• default_action_renderer_cls (type, optional) –

  The default action renderer used for child actions.

  This will be used for any actions that don’t already have a default action renderer set. The action’s default takes precedence in order to allow actions such as buttons to manage their own display.

attachment_point_id: str¶

The unique ID for this attachment point.

This may be set on the class or passed when initializing an instance.

actions: Sequence[str] | None = None¶

A pre-defined list of action IDs to include on the attachment point.

This may be set on the class or passed when initializing an instance.

Any actions listed here will be listed first in the specified order. Any additional actions registered to this attachment point will be added after these actions.

default_action_renderer_cls¶

The default action renderer used for child actions.

This may be set on the class or passed when initializing an instance.

This will be used for any non-group actions that don’t already have a default action renderer set. The action’s default takes precedence in order to allow actions such as buttons to manage their own display.

alias of DefaultActionRenderer

default_action_group_renderer_cls¶

The default action renderer used for child action groups.

This may be set on the class or passed when initializing an instance.

This will be used for any group actions that don’t already have a default action renderer set. The action’s default takes precedence in order to allow actions such as menus to manage their own display.

alias of DefaultActionGroupRenderer

actions_registry: ActionsRegistry¶

The registry managing actions for this attachment point.

This is primarily for unit test purposes.

iter_actions(*, include_children: bool = False) → Iterator[BaseAction][source]¶

Yield actions for this attachment point.

Parameters:

include_children (bool, optional) –

Whether to also include children of menus.

If False (default), this will only yield the top-level items.

Yields:

reviewboard.actions.base.BaseAction – The actions for the given attachment point.

get_js_view_data(*, context: Context) → SerializableDjangoJSONDict[source]¶

Return additional data to be passed to the JavaScript view.

This will be merged along with the data provided by the renderer. Any data in the renderer will take precedence over data returned by this method.

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

A dictionary of attributes to pass to the model instance.

Return type:

dict

render(*, request: HttpRequest, context: Context) → SafeString[source]¶

Render all actions in the attachment point.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• context (django.template.Context) – The current rendering context.

Returns:

The rendered action HTML.

Return type:

django.utils.safestring.SafeString

render_js(*, request: HttpRequest, context: Context) → SafeString[source]¶

Render the JavaScript for loading each action view in this point.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• context (django.template.Context) – The current rendering context.

Returns:

The rendered action JavaScript.

Return type:

django.utils.safestring.SafeString

class ActionPlacement(attachment: str, *, default_renderer_cls: type[reviewboard.actions.renderers.BaseActionRenderer] | None = None, dom_element_id: str | None = None, parent_id: str | None = None)[source]¶

Bases: object

Placement information for an action.

This is used to specify where and how an action may be placed. This is mapped to a key specifying an attachment point ID, and can specify the parent action within the attachment point and a default renderer to use.

New in version 8.0.

__init__(attachment: str, *, default_renderer_cls: type[reviewboard.actions.renderers.BaseActionRenderer] | None = None, dom_element_id: str | None = None, parent_id: str | None = None) → None[source]¶

Initialize the placement.

Parameters:

• attachment (str) – The attachment point ID to place the action in.

• default_renderer_cls (type, optional) – The default renderer to use when rendering in this attachment point.

• dom_element_id (str, optional) – A custom DOM element ID for the action in this attachment point.

• parent_id (str, optional) – The parent ID of an action in this attachment point in which to place this action.

attachment: str¶

The attachment point for the action.

default_renderer_cls: type[BaseActionRenderer] | None¶

The default renderer used for this action.

By default, actions inherit their default renderer from a previous group or attachment point.

Default renderers can always be overridden when rendering the action.

dom_element_id: str | None = None¶

The DOM element ID for this element on the page.

If not provided, an ID in the form of action-attachment-action_id will be used.

parent_id: str | None¶

The ID of the parent action within the attachment point, if needed.

This is used to build menus or groups of actions in part of the UI.

child_actions: list[BaseAction]¶

The list of child actions, if this is a grouped action.

parent_action: BaseGroupAction | None¶

The parent of this action, if this is an item in a group.

property depth: int[source]¶

The depth of the action in this placement.

Type:

int

clone() → ActionPlacement[source]¶

Return a clone of action placement.

This is used to produce a copy of a central action that can be attached to an action instance, to avoid sharing of state.

Returns:

The cloned instance.

Return type:

ActionPlacement

__final__ = True¶

class BaseAction[source]¶

Bases: object

Base class for actions.

Changed in version 8.0:

• A single action now can be placed in multiple attachment points via placements.

• Actions now make use of renderer classes for rendering, instead of including rendering logic built-in.

• Deprecated the attributes attachment, js_view_class, parent_action, parent_id, and template_name.

• Deprecated the methods get_js_view_data() and is_custom_rendered().

New in version 6.0.

action_id: str¶

The internal ID of the action.

This must be unique.

Type:

str

apply_to: Optional[List[str]] = None¶

A list of URLs to apply to.

If this is None, the action will be loaded on all pages. Otherwise, it will be limited to the URLs listed here.

Type:

list of str

attachment: str | None = None¶

The attachment point for the action.

Deprecated since version 8.0: This has been replaced by placements. This option will be removed in Review Board 9.

default_renderer_cls: type[BaseActionRenderer] | None = None¶

The default renderer used for this action.

By default, actions inherit their default renderer from a previous group or attachment point.

Default renderers can always be overridden when rendering the action.

New in version 8.0.

description: Sequence[StrOrPromise] | None = None¶

An optional description for your action.

If provided, this must be a list of strings, each used as a paragraph. Each must be plain text, and will be escaped for display.

When rendered as a button, this will be used for the button’s tooltip.

When rendered as a detailed menu item (which is used in the Review menu), this will be shown as additional text below the label.

Other renderers may use this for other purposes.

New in version 8.0.

icon_class: Optional[str] = None¶

A class name to use for an icon.

If specified, this should be the entire class to apply to a <span> element to display an icon. For example, ‘fa fa-rss’.

Type:

str

js_model_class: str = 'RB.Actions.Action'¶

The class to instantiate for the JavaScript model.

Type:

str

js_template_name: str = 'actions/action.js'¶

The name of the template to use for registering action model JavaScript.

js_view_class: str | None = None¶

The class to instantiate for the JavaScript view.

Deprecated since version 8.0: This should be set on the action’s renderer instead.

label: StrOrPromise | None = None¶

The user-visible label.

Type:

str

parent_id: str | None = None¶

The IDs of any parent actions, if needed.

Deprecated since version 8.0: This should be set in placements instead. This option will be removed in Review Board 9.

template_name: str | None = None¶

The name of the template to use when rendering.

Deprecated since version 8.0: This should be set on the action’s renderer instead. This option will be removed in Review Board 9.

url: str = '#'¶

The URL that this action links to.

Type:

str

url_name: Optional[str] = None¶

A URL name to resolve.

If this is not None, it will take precedence over url.

Type:

str

verbose_label: StrOrPromise | None = None¶

The user-visible verbose label.

This can be used to provide a longer label for wider UIs that would benefit from a more descriptive label. It’s also intended for ARIA labels.

This is always optional.

New in version 8.0.

visible: bool = True¶

Whether this action is visible.

Type:

bool

__init__() → None[source]¶

Initialize the action.

parent_registry: ActionsRegistry | None¶

The parent registry managing this action.

New in version 8.0.

placements: Sequence[ActionPlacement] | None = None¶

The placements of this action within the page.

Each entry defines a placement within an attachment point and an action parent/child hierarchy where action should be rendered, along with options controlling the rendering.

New in version 8.0.

property parent_action: reviewboard.actions.base.BaseAction | None[source]¶

The parent of this action, if this is an item in a group.

Deprecated since version 8.0: This has been replaced by ActionPlacement.parent_action. It will be removed in Review Board 10.

property child_actions: Sequence[BaseAction][source]¶

The children of this action, if this is a group.

Deprecated since version 8.0: This has been replaced by ActionPlacement.child_actions. It will be removed in Review Board 10.

property depth: int[source]¶

The depth of the action.

Deprecated since version 8.0: This is scheduled for removal in Review Board 10. This has been replaced by ActionPlacement.depth.

Type:

int

get_placement(attachment_point_id: str) → ActionPlacement[source]¶

Return the Placement for the action matching the attachment point.

New in version 8.0.

Parameters:

attachment_point_id (str) – The ID of the attachment point matching the placement.

Returns:

The Placement, or None if not found.

Return type:

ActionPlacement

Raises:

KeyError – The attachment point ID is not a valid placement for this action.

get_renderer_cls(*, placement: reviewboard.actions.base.ActionPlacement | None, preferred_renderer_cls: type[reviewboard.actions.renderers.BaseActionRenderer] | None = None, fallback_renderer_cls: type[reviewboard.actions.renderers.BaseActionRenderer] | None = None) → type[reviewboard.actions.renderers.BaseActionRenderer] | None[source]¶

Return the renderer class used to render this action.

This takes into account the attachment point, the preferred renderer from the caller, and the fallback if no suitable renderer is found.

New in version 8.0.

Parameters:

• placement (ActionPlacement) – The placement where the action will be rendered.

• preferred_renderer_cls (type, optional) –

  The preferred renderer for items.

  This will be used if provided, unless item isn’t custom-rendered (a deprecated feature).

• fallback_renderer_cls (type, optional) – The fallback renderer if the placement or action does not provide one.

Returns:

The renderer class, or None if one could not be determined.

Return type:

type

is_custom_rendered() → bool[source]¶

Whether this action uses custom rendering.

By default, this will return True if a custom template name is used. If the JavaScript side needs to override rendering, the subclass should explicitly return True.

Deprecated since version 8.0: This is scheduled for removal in Review Board 9. This was only ever used for menu items. Custom menu items should instead set the data-custom-rendered="true" attribute on the custom element.

New in version 7.0.

Returns:

True if this action uses custom rendering. False if it does not.

Return type:

bool

should_register(*, context: Context, request: HttpRequest) → bool[source]¶

Return whether this action should be registered.

By default, an action will be registered only if it’s rendered somewhere on the page (which will itself depend in part on the result of should_render()).

Subclasses can override this to register even if not rendered, which may be useful for actions that are entirely managed dynamically in JavaScript. When overriding, it’s recommended to call should_render() in order to avoid registering an action that is not applicable to a page or is hidden by a hook.

New in version 8.0.

Parameters:

• context (django.template.Context) – The current rendering context.

• request (django.http.HttpRequest) – The HTTP request from the client.

Returns:

True if the action should be registered. False if it should not.

Return type:

bool

should_render(*, context: Context) → bool[source]¶

Return whether this action should render.

This differs from visible in that non-visible actions still render but are hidden by CSS, whereas if this returns False the action will not be included in the DOM at all.

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

True if the action should render.

Return type:

bool

get_dom_element_id() → str[source]¶

Return the ID used for the DOM element for this action.

Deprecated since version 8.0: This is scheduled for removal in Review Board 9. This has been replaced by ActionPlacement.dom_element_id.

Returns:

The ID used for the element.

Return type:

str

get_js_model_data(*, context: Context) → SerializableDjangoJSONDict[source]¶

Return data to be passed to the JavaScript model.

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

A dictionary of attributes to pass to the model instance.

Return type:

dict

get_js_view_data(*, context: Context) → SerializableDjangoJSONDict[source]¶

Return data to be passed to the JavaScript view.

Deprecated since version 8.0: Actions implementing this should instead move to custom renderers.

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

A dictionary of options to pass to the view instance.

Return type:

dict

get_label(*, context: Context) → StrOrPromise | None[source]¶

Return the label for the action.

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

The label to use for the action.

Return type:

str

get_verbose_label(*, context: Context) → StrOrPromise | None[source]¶

Return the verbose label for the action.

This can be used to provide a longer label for wider UIs that would benefit from a more descriptive label. It’s always optional.

Version Added:

8.0

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

The verbose label to use for the action.

Return type:

str

get_url(*, context: Context) → str[source]¶

Return the URL for the action.

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

The URL to use for the action.

Return type:

str

get_visible(*, context: Context) → bool[source]¶

Return whether the action should start visible.

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

True if the action should start visible. False, otherwise.

Return type:

bool

get_extra_context(*, request: HttpRequest, context: Context) → dict[str, Any][source]¶

Return extra template context for the action.

Subclasses can override this to provide additional context needed by the template for the action. By default, this returns an empty dictionary.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• context (django.template.Context) – The current rendering context.

Returns:

Extra context to use when rendering the action’s template.

Return type:

dict

render(*, request: HttpRequest, context: Context, placement: ActionPlacement | None = None, renderer: type[BaseActionRenderer] | None = None, fallback_renderer: type[BaseActionRenderer] | None = None) → SafeString[source]¶

Render the action.

Changed in version 8.0: Added the extra_js_view_data, fallback_renderer, placement, and renderer arguments.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• context (django.template.Context) – The current rendering context.

• placement (ActionPlacement, optional) –

  The placement the action is being rendered into.

  If not added, the first will be used, with a warning.

  This argument will be required in Review Boad 9.

  New in version 8.0.

• renderer (type, optional) –

  The renderer used to render this action.

  If not specified, default_renderer_cls will be used.

  New in version 8.0.

• fallback_renderer (type, optional) –

  The renderer used to render this action if no other is found.

  New in version 8.0.

Returns:

The rendered action HTML.

Return type:

django.utils.safestring.SafeString

Raises:

• TypeError – An invalid renderer class was provided.

• reviewboard.actions.errors.MissingActionRendererError – A renderer was not found or provided.

render_model_js(*, request: HttpRequest, context: Context) → SafeString[source]¶

Render the action’s JavaScript model.

This will set up the JavaScript model, registering it for use in views.

New in version 8.0.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• context (django.template.Context) – The current rendering context.

Returns:

The rendered action JavaScript.

Return type:

django.utils.safestring.SafeString

render_js(*, request: HttpRequest, context: Context, extra_js_view_data: SerializableDjangoJSONDict | None = None, placement: ActionPlacement | None = None, renderer: type[BaseActionRenderer] | None = None, fallback_renderer: type[BaseActionRenderer] | None = None) → SafeString[source]¶

Render the action’s JavaScript view.

This will set up an instance of an action’s view using either the provided renderer or the action’s default renderer.

Changed in version 8.0: Added the extra_js_view_data, fallback_renderer, placement, and renderer arguments.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• context (django.template.Context) – The current rendering context.

• extra_js_view_data (dict, optional) –

  Optional extra data to pass to the JavaScript action view’s constructor.

  New in version 8.0.

• placement (ActionPlacement, optional) –

  The placement the action is being rendered into.

  If not added, the first will be used, with a warning.

  This argument will be required in Review Boad 9.

  New in version 8.0.

• renderer (type, optional) –

  The renderer used to render this action.

  If not specified, default_renderer_cls will be used.

  New in version 8.0.

• fallback_renderer (type, optional) –

  The renderer used to render this action if no other is found.

  New in version 8.0.

Returns:

The rendered action JavaScript.

Return type:

django.utils.safestring.SafeString

Raises:

• TypeError – An invalid renderer class was provided.

• reviewboard.actions.errors.MissingActionRendererError – A renderer was not found or provided.

class BaseGroupAction[source]¶

Bases: BaseAction

Base class for a group of actions.

This can be used to group together actions in some form. Subclasses can implement this as menus, lists of actions, or in other presentational styles.

New in version 8.0.

js_model_class: str = 'RB.Actions.GroupAction'[source]¶

The class to instantiate for the JavaScript model.

Type:

str

children: Sequence[str] = []¶

An ordered list of child action IDs.

This can be used to specify a specific order for children to appear in. The special string ‘–’ can be used to add separators. Any children that are registered with this group as their parent but do not appear in this list will be added at the end of the group.

get_js_model_data(*, context: Context) → SerializableDjangoJSONDict[source]¶

Return data to be passed to the JavaScript model.

Parameters:

context (django.template.Context) – The current rendering context.

Returns:

A dictionary of attributes to pass to the model instance.

Return type:

dict

Raises:

reviewboard.actions.errors.ActionError – There was an error retrieving data for the action. Details will be in the error message.

class BaseMenuAction[source]¶

Bases: BaseGroupAction

Base class for menu actions.

New in version 6.0.

default_renderer_cls¶

alias of MenuActionGroupRenderer

js_model_class: str = 'RB.Actions.MenuAction'[source]¶

The class to instantiate for the JavaScript model.

Type:

str

is_custom_rendered() → bool[source]¶

Whether this menu action uses custom rendering.

By default, this will return True if a custom template name is used. If the JavaScript side needs to override rendering, the subclass should explicitly return True.

Deprecated since version 8.0: This is scheduled for removal in Review Board 10. This was only ever used for menu items. Custom menu items should instead set the data-custom-rendered="true" attribute on the custom element.

New in version 7.0.

Returns:

True if this action uses custom rendering. False if it does not.

Return type:

bool