Namespace: bitbucket/feature/files/file-handlers

bitbucket/feature/files/file-handlers

Provides a way to register file-handlers to handle rendering the source of a file.
For example, a FileHandler can be registered to handle .stl files and render them as 3D files.
JS files registering file-handlers should use the resource context 'bitbucket.internal.feature.files.fileHandlers'.

This module is available synchronously.

Web Resource: com.atlassian.bitbucket.server.bitbucket-web-api:file-handlers

Source:

Example

function MyView(options) {
    var $element = $('<div/>');
    $container.append($element);

    return {
        destroy: function() {
            $element.remove();
        },
        extraClasses: 'my-class something-else'
    };
}

var myFileHandler = {
    weight: 400,
    handle: function(options) {
        if (options.fileChange.path.extension === 'stl') {
            return new MyView(options);
        } else if (options.fileChange.path.extension === 'stl2') {
            // Returning a rejected promise with a message will display errors appropriately
            return $.Deferred().reject('File extension not supported');
        }
        // Return null/undefined or an empty promise to pass silently
    }
};

// Register your handler immediately to ensure it is in place when needed.
// Note that we use the synchronous syntax to require the module, which ensures there is no delay before
// register() is called.
require('feature/file-content/file-handlers').register(myFileHandler);

Members

<static, readonly> fileHandlers.builtInHandlers :string

An enum of built-in handlers that may be used to handle the display of file content. It is not an exhaustive list.
Any plugin can handle any file it wishes and may or may not provide an ID.

Type:
  • string
Properties:
Name Type Default Description
ERROR string error

Generic error handler
DIRECTORY string directory

Directory handler
SOURCE_TEXT string source-text

Textual source handler
SOURCE_EMPTY string source-empty

Empty source handler
SOURCE_IMAGE string source-image

Image source handler
SOURCE_BINARY string source-binary

Non-image binary source handler
DIFF_TEXT_SIDE_BY_SIDE string diff-text-side-by-side

Textual diff handler with side-by-side display
DIFF_TEXT_UNIFIED string diff-text-unified

Textual diff handler with unified display
DIFF_EMPTY string diff-empty

Empty diff handler
DIFF_TOO_LARGE string diff-too-large

Too-large diff handler
DIFF_IMAGE string diff-image

Image diff handler
DIFF_BINARY string diff-binary

Non-image binary diff handler
Source:

Methods

<static> register(fileHandler)

Register a file handler. Call this method as soon as possible to ensure your handler is considered when a file content is loaded.

Parameters:
Name Type Description
fileHandler FileHandler

your file handler to register
Source:

Type Definitions

FileHandleCallback(context) → {Promise}

Callback to handle file.

Parameters:
Name Type Description
context bitbucket/feature/files/file-handlers.FileHandlingContext

A map of properties describing the content
to be rendered and the context in which it is to be rendered.
Source:
Returns:

A promise object that resolves with FileHandlerResult if this handler will handle the request, or rejects otherwise.

Type
Promise

FileHandler

An object that can either render file sources, file diffs, or both for a particular subset of files.

Type:
  • Object
Properties:
Name Type Argument Default Description
weight number <optional>
 1000

The weight of handler determining the order it is tried.
The default weight of the source/diff view is 1000.
handle bitbucket/feature/files/file-handlers.FileHandleCallback

A function called to handle file content rendering.
Source:

FileHandlerResult

Type:
  • Object
Properties:
Name Type Argument Description
destroy function <optional>

A function that will be called before the current view is destroyed, which may happen on state change.
This is a chance to destroy/cleanup any event listeners and remove DOM elements.
extraClasses string <optional>

Additional style class applied to parent file-content. Can be used to apply background color.
handlerID string <optional>

A unique string identifying your handler (or a "sub-" handler if your handler has a few different ways
to display data). This is passed to toolbar web-fragments so they can enable or disable themselves based
on which handler is being displayed.

                                   The built-in handler IDs are listed in bitbucket/feature-files/file-handlers#builtInHandlers. Your handler
                                   should NOT use these IDs, but should instead specify a unique ID string of its own.
editing EditingContext <optional>

An object which indicates whether the current handler is editable, and if so, supplies the methods required for editing
Source:

FileHandlingContext

Type:
  • Object
Properties:
Name Type Argument Description
contentMode string

The mode of content. This is either 'source' or 'diff'.
$toolbar jQuery

A jQuery object pointing to the toolbar contents - any toolbar web panels can be found as descendants. (Since 3.5)
$container jQuery

A jQuery object in which you should append your rendered file content.
fileChange JSON.FileChangeJSON

Describes the changed file.
commentMode string

The comment rendering mode. "none", "read", "reply-only", or "create-new"
isExcerpt boolean

Indicates whether this is only an excerpt and not a full file/diff.
anchor *

An anchor of any type which can be used by the appropriate handler to deep link into the content
scrollStyle string <optional>

The style of scrolling to be used, "fixed" or "inline".
diffUrlBuilder function <optional>

An optional function that accepts a {JSON.FileChangeJSON} and will return
a {bitbucket/util/navbuilder.Builder} to the built-in Stash REST
endpoint to obtain the diff information.
lineComments Array.<JSON.CommentJSON> <optional>

An array of comments anchored to the lines of the file. The structure
matches the structure for comments retrieved via the REST API. This is only provided
for handling diffs as activity items for a pull request. For other usages, line comments
will be retrieved from the server when retrieving diffs.
commentUrlBuilder function <optional>

– An optional function that returns a {bitbucket/util/navbuilder.Builder} to the built-in Stash REST
endpoint to send the comment information.
diffViewType DiffViewType

the type of diff being displayed - an effective merge diff, or a common ancestor diff
Source: