reviewboard.reviews.ui.base¶

class ReviewUI(review_request, obj)[source]¶

Bases: object

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.

__init__(review_request, obj)[source]¶

Initialize the Review UI.

Parameters:

review_request (reviewboard.reviews.models.review_request.ReviewRequest) – The review request containing the object to review.
obj (object) – The object being reviewed.

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:

user (django.contrib.auth.models.User, optional) – The user to check.
review_request (reviewboard.reviews.models.review_request.ReviewRequest) – The review request to check.
**kwargs (dict) – Additional keyword arguments, for future expansion.

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

get_comment_link_url(comment)[source]¶

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

get_comment_link_text(comment)[source]¶

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]¶

Bases: ReviewUI

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.

name = 'Unknown file type'[source]¶: The display name for the Review UI.

object_key = 'file'[source]¶: The key passed to the template representing the object.

diff_object_key = 'diff_against_file'[source]¶: The key passed to the template representing an object to diff against.

supported_mimetypes = [][source]¶

js_model_class = 'RB.DummyReviewable'[source]¶: The name of the JavaScript model class to use for the Review UI.

js_view_class = 'RB.DummyReviewableView'[source]¶: The name of the JavaScript view class to use for the Review UI.

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:

user (django.contrib.auth.models.User, optional) – The user to check.
review_request (reviewboard.reviews.models.review_request.ReviewRequest) – The review request to check.
file_attachment (reviewboard.attachments.models.FileAttachment) – The file attachment to check.
**kwargs (dict) – Additional keyword arguments, for future expansion.

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

get_comment_link_url(comment)[source]¶

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

get_comment_link_text(comment)[source]¶

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]¶

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.