Page tree
Skip to end of metadata
Go to start of metadata

The images property controls how images are handled within a Textbox.io editor instance.

This property can be configured to one of three behaviors:

  • Uploading Images via Textbox.io's Built-in Upload Mechanism
  • Uploading Images via a Custom JavaScript Upload Handler Function
  • Preventing Local Images (No Upload)

Properties

PropertyTypeDefaultProperties
allowLocalBooleantrue

true allows local images into editor content. false prevents local images from being inserted.

uploadObject 

Configures the uploading of local images to your application using Textbox.io's built in upload mechanism.

To use Textbox.io's built-in upload mechanism, use upload.url, upload.basePath, and upload.credentials.

PropertyTypeDefaultProperties
urlString Defines the location of your POST acceptor script. This is the URL to which images will be uploaded.
basePathString [Optional] Defines the base path of images uploaded in your application. This path is combined with the path returned from your POST acceptor script.
credentialsBooleanfalse[Optional] true: sends cookies with the upload POST (sets the XHR credentials flag). false: does not send cookies.

To use a custom JavaScript handler function, use upload.handler. Note that defining upload.handler overrides Textbox.io's built in upload mechanism.

PropertyTypeDefaultProperties
handlerFunction Configures the uploading of images to your application using a custom Javascript upload handler.

Examples

Using Textbox.io's Built-in Upload Mechanism

The simplest way to handle images is use automatic background uploads. A simple configuration object is used to define the upload location for images. url is the target to which local images are uploaded via HTTP POST. basePath is used in conjunction with the value returned by the POST handler to link to the uploaded image within the editor's content. More information is available in the Handling Local Images guide.

 

var config = {
	images : {
		upload : {
			url : 'http://example.com/path/to/POSTAcceptor.php',
            basePath : 'http://example.com/path/to/images'
		}
	}
};

var editor = textboxio.replace('#targetId', config);

 

Using a Custom JavaScript Upload Handling Function

If images must be uploaded using more than a simple HTTP POST, the entire upload process can be replaced. For example, you may wish to perform additional client side validation or manipulation on the images prior to their upload.  The handler function is passed three arguments; Data, Success and Failure.

Data Properties

The first argument is an object providing information about the image that has been inserted.

FunctionTypeDescription

data.blob()

Blob

JavaScript Blob instance representing the image binary data

data.base64() String

A copy of the image binary data pre-converted to base64 for your convenience

data.filename()StringThe actual filename, where possible, otherwise a generated filename based on the MIME type
data.id()StringA unique identifier for this image
Success Parameters

 The second argument is a function that indicates the upload has successfully completed

url

String

The URL to use as the image src. No post-processing is performed on this value (the basePath configuration property is ignored).

Failure Parameters

The third argument is a function that indicates the upload failed.

message

String (optional)

A message to display to the user in an error banner.

This value is optional - if you do not wish to translate your error a generic message is available which has been translated into all supported languages.

var config = {
	images : {
		upload : {
			handler : function (data, success, failure) {
				// For example, if myuploader.upload() returns a promise, e.g. jQuery ajax
				myuploader.upload(data.blob(), data.filename()).then(function (<upload response>) {
					success(<response image url>);
				}, function () {
					failure("my failure message");
				});
			}
		}
	}
};
 
var editor = textboxio.replace('#targetId', config);

Preventing Local Images (No Upload)

A developer may choose to prevent local images from being added to an editor  ( allowLocal : false ). When local images have been blocked, the insert image dialog does not display the Local Files tab. If the user attempts to paste an image into the editor or drag and drop image insertion, an error message is displayed.

var config = {
	images : {
		allowLocal : false	
	}
};
 
var editor = textboxio.replace('#targetId', config);

  • No labels