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
andjs_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
.- request¶
The HTTP request from the client. This is only set once
render_to_string()
is called.
- review_request¶
The review request containing the object being reviewed.
- 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.
- 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).
- 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.
- __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
- 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
- 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
- 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
- get_comments()[source]¶
Return all existing comments on the reviewable object.
Subclasses must override this.
- get_caption(draft=None)[source]¶
Return the caption to show for the reviewable object.
This defaults to requiring
caption
anddraft_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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
ofreviewboard.reviews.models.base_comment.BaseComment
) – The list of objects to serialize. This will be the result ofget_comments()
.- Returns
The list of serialized comment data.
- Return type
- 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
- class FileAttachmentReviewUI(review_request, obj)[source]¶
Bases:
reviewboard.reviews.ui.base.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.
- diff_object_key = 'diff_against_file'[source]¶
The key passed to the template representing an object to diff against.
- 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
- 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
ofreviewboard.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
- 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
- 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
- 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
- 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
- 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
- classmethod get_best_handler(mimetype)[source]¶
Return the Review UI and score that that best fit the mimetype.
- 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
- __annotations__ = {}¶
- 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 ofFileAttachmentReviewUI
.- 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 ofFileAttachmentReviewUI
, 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.