Jump to >

reviewboard.reviews.ui.base

class ReviewUI(review_request, obj)[source]

Base class for a Review UI.

Review UIs are interfaces for reviewing content of some type. They take a type of object and render a page around it, optionally allowing for the display of a diff view for the content. They can render context for comments made on the object, provide details for social media sharing (such as on a chat or social network).

A Review UI makes use of a JavaScript side for the interaction, defined using js_model_class and js_view_class. The JavaScript side should interface with the API to create/update reviews and comments for the object being reviewed.

Extensions providing Review UIs for file attachments should subclass FileAttachmentReviewUI.

diff_against_obj

The object being diffed against, if any.

Type

object

obj

The object being reviewed.

Type

object

request

The HTTP request from the client. This is only set once render_to_string() is called.

Type

django.http.HttpRequest

review_request

The review request containing the object being reviewed.

Type

reviewboard.reviews.models.review_request.ReviewRequest

name = None[source]

The display name for the Review UI.

template_name = 'reviews/ui/default.html'[source]

The template that renders the Review UI.

Generally, subclasses should use the default template and render the UI using JavaScript.

object_key = 'obj'[source]

The key passed to the template representing the object.

diff_object_key = 'diff_against_obj'[source]

The key passed to the template representing an object to diff against.

allow_inline = False[source]

Whether the Review UI can be rendered inline in diffs and other places.

If set, the Review UI will be able to be displayed within the diff viewer (and potentially other locations).

supports_diffing = False[source]

Whether this Review UI supports diffing two objects.

css_bundle_names = [][source]

A list of CSS bundle names to include on the Review UI’s page.

js_bundle_names = [][source]

A list of JavaScript bundle names to include on the Review UI’s page.

js_files = [][source]

A list of specific JavaScript URLs to include on the page.

It is recommended that js_bundle_names be used instead where possible.

js_model_class = None[source]

The name of the JavaScript model class to use for the Review UI.

js_view_class = None[source]

The name of the JavaScript view class to use for the Review UI.

set_diff_against(obj)[source]

Set the object to generate a diff against.

This can only be called on Review UIs that support diffing, and must be called before rendering.

Parameters

obj (object) – The object being diffed against.

is_enabled_for(user=None, review_request=None, **kwargs)[source]

Return whether the Review UI is enabled under the given criteria.

This can enable or disable a Review UI’s functionality depending on the user, review request, or some state associated with one or more of those.

When this is called, the arguments are always passed as keyword arguments. Subclasses don’t need to accept all the arguments, as long as they take a **kwargs.

Parameters
Returns

True if the Review UI is enabled for the given criteria. False otherwise.

By default, Review UIs are always enabled.

Return type

bool

render_to_response(request)[source]

Render the Review UI to a response.

This is used to render a page dedicated to the Review UI, complete with the standard Review Board chrome.

Parameters

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

Returns

The HTTP response containing the page for the Review UI.

Return type

django.http.HttpResponse

render_to_string(request, inline=True)[source]

Render the Review UI to an HTML string.

This renders the Review UI to a string for use in embedding into either an existing page or a new page.

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

  • inline (bool, optional) – Whether to render this such that it can be embedded into an existing page, instead of as a standalone page.

Returns

The HTML for the Review UI.

Return type

django.utils.safestring.SafeText

build_render_context(request, inline=False, **kwargs)[source]

Build context for rendering the page.

This computes the standard template context to use when rendering the page. Generally, subclasses should override get_extra_context(), instead of this.

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

  • inline (bool, optional) – Whether to render this such that it can be embedded into an existing page, instead of as a standalone page.

Returns

The context to use in the template.

Return type

dict

get_page_cover_image_url()[source]

Return the URL to an image used to depict this on other sites.

The returned image URL will be used for services like Facebook, Slack, Twitter, etc. when linking to the reviewable object. This may be anything from a standard thumbnail to a full-size image.

By default, no image URL is returned.

Returns

The absolute URL to an image used to depict the reviewable object.

Return type

unicode

get_comments()[source]

Return all existing comments on the reviewable object.

Subclasses must override this.

Returns

The list of comments for the page.

Return type

list of object

get_caption(draft=None)[source]

Return the caption to show for the reviewable object.

This defaults to requiring caption and draft_caption attributes on the reviewable object. Subclasses can override this to use something else.

Parameters

draft (reviewboard.reviews.models.review_request_draft.ReviewRequestDraft, optional) – The active review request draft for the user, if any.

Returns

The caption for the reviewable object.

Return type

unicode

get_comment_thumbnail(comment)[source]

Return an HTML thumbnail for a comment.

If comment thumbnails are possible for the reviewable object, this function should return HTML for the thumbnail.

Parameters

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to return a thumbnail for.

Returns

The HTML for a thumbnail for the comment, or None if one can’t be generated (using the default thumbnailing for the comment type, if one exists).

Return type

django.utils.safestring.SafeText

Return a URL for linking to a comment.

Subclasses must override this.

Parameters

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to return a link for.

Returns

The URL to link to the comment.

Return type

unicode

Return the text to link to a comment.

This must be implemented by subclasses.

Parameters

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to return text for.

Returns

The text used to link to the comment.

Return type

unicode

get_extra_context(request)[source]

Return extra context to use when rendering the Review UI.

Parameters

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

Returns

The context to provide to the template.

Return type

dict

get_js_model_data()[source]

Return data to pass to the JavaScript Model during instantiation.

This data will be passed as attributes to the reviewable model when constructed.

Returns

The attributes to pass to the model.

Return type

dict

get_js_view_data()[source]

Return data to pass to the JavaScript View during instantiation.

This data will be passed as options to the reviewable view when constructed.

Returns

The options to pass to the view.

Return type

dict

get_comments_json()[source]

Return a JSON-serialized representation of comments for a template.

The result of this can be used directly in a template to provide comments to JavaScript functions.

Returns

Serialized JSON content representing the comments on the reviewable object.

Return type

unicode

serialize_comments(comments)[source]

Serialize the comments for the Review UI target.

By default, this will return a list of serialized comments, but it can be overridden to return other list or dictionary-based representations, such as comments grouped by an identifier or region. These representations must be serializable into JSON.

Parameters

comments (list of reviewboard.reviews.models.base_comment.BaseComment) – The list of objects to serialize. This will be the result of get_comments().

Returns

The list of serialized comment data.

Return type

list of dict

serialize_comment(comment)[source]

Serialize a comment.

This will provide information on the comment that may be useful to the JavaScript code.

Subclasses that want to add additional data should generally augment the result of this function and not replace it.

Parameters

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to serialize.

Returns

The serialized comment data.

Return type

dict

class FileAttachmentReviewUI(review_request, obj)[source]

Base class for Review UIs for file attachments.

Review UIs that deal with FileAttachment objects can subclass this to provide the common functionality for their Review UI.

This class handles fetching and serializing comments, locating a correct subclass for a given mimetype, and feeding data to the JavaScript RB.AbstractReviewable() model.

This also handles much of the work for diffing file attachments.

is_enabled_for(user=None, review_request=None, file_attachment=None, **kwargs)[source]

Return whether the Review UI is enabled under the given criteria.

This can enable or disable a Review UI’s functionality, both on the file attachment thumbnail and Review UI page, depending on the user, review request, file attachment, or some state associated with one or more of those.

When this is called, the arguments are always passed as keyword arguments. Subclasses don’t need to accept all the arguments, as long as they take a **kwargs.

Parameters
Returns

True if the Review UI is enabled for the given criteria. False otherwise.

By default, Review UIs are always enabled.

Return type

bool

get_comments()[source]

Return a list of comments made on the file attachment.

If this Review UI is showing a diff between two attachments, the comments returned will be specific to that diff.

Returns

The list of comments on the file attachment or the diff.

Return type

list of reviewboard.reviews.models.file_attachment_comment.FileAttachmentComment

get_caption(draft=None)[source]

Return the caption to show for the file attachment.

Parameters

draft (reviewboard.reviews.models.review_request_draft.ReviewRequestDraft, optional) – The active review request draft for the user, if any.

Returns

The caption for the file attachment.

Return type

unicode

Return a URL for linking to a comment.

This will normally just link to the Review UI itself, but subclasses may want to override this to provide a more specialized URL.

Parameters

comment (reviewboard.reviews.models.file_attachment_comment.FileAttachmentComment) – The comment to return a link for.

Returns

The URL to link to the comment.

Return type

unicode

Return the text to link to a comment.

This will normally just return the file attachment’s display name, but some may want to specialize to list things like page numbers or sections.

Parameters

comment (reviewboard.reviews.models.file_attachment_comment.FileAttachmentComment) – The comment to return text for.

Returns

The text used to link to the comment.

Return type

unicode

serialize_comment(comment)[source]

Serialize a comment.

This will provide information on the comment that may be useful to the JavaScript code.

Parameters

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to serialize.

Returns

The serialized comment data.

Return type

dict

build_render_context(request, inline, **kwargs)[source]

Return extra context to use when rendering the Review UI.

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

  • inline (bool, optional) – Whether to render this such that it can be embedded into an existing page, instead of as a standalone page.

Returns

The context to use in the template.

Return type

dict

get_js_model_data()[source]

Return model data for the JavaScript AbstractReviewable subclass.

This will return information on the file attachment, its history, and any information on an attachment being diffed against.

Subclasses can override this to return additional data.

Returns

The attributes to pass to the model.

Return type

dict

classmethod get_best_handler(mimetype)[source]

Return the Review UI and score that that best fit the mimetype.

Parameters

mimetype (tuple) – A parsed mimetype to find the best review UI for. This is a 3-tuple of the type, subtype, and parameters as returned by mimeparse.parse_mime_type().

Returns

A tuple of (best_score, review_ui), or (0, None) if one could not be found.

Return type

tuple

classmethod for_type(attachment)[source]

Return the Review UI that is the best fit for a file attachment.

Parameters

attachment (reviewboard.attachments.models.FileAttachments) – The file attachment to locate a Review UI for.

Returns

The Review UI for the attachment, or None if a suitable one could not be found.

Return type

FileAttachmentReviewUI

register_ui(review_ui)[source]

Register a Review UI class.

This will register a Review UI. Review Board will use it to display a UI when reviewing a supported file attachment.

Parameters

review_ui (type) – The Review UI to register. This must be a subclass of FileAttachmentReviewUI.

Raises

TypeError – The provided Review UI class is not of a compatible type.

unregister_ui(review_ui)[source]

Unregister a Review UI class.

This will unregister a previously registered Review UI.

Only FileAttachmentReviewUI subclasses are supported. The class must have been registered beforehand or a ValueError will be thrown.

Parameters

review_ui (type) – The Review UI to unregister. This must be a subclass of FileAttachmentReviewUI, and must have been registered before.

Raises
  • TypeError – The provided Review UI class is not of a compatible type.

  • ValueError – The provided Review UI was not previously registered.