JSMA file

Overview

The JSMA file provides functionality for handling files

Index

Usage

writing data

Here is an example on how to write data to a JSMA file:

...
file.setReferenceCount(7);
...

reading data

Here is an example on how to read data from a JSMA file:

... 
if file.has('description') 
{ 
   ... 
} 
...

Methods

The JSMA file provides the following methods:

file file.clone(name)

Clones the file and returns the copy as a JSMA file with a new uuid.

Example

...
var copiedFile = file.clone() // => file
...

Parameter name: (optional)

string file.content

Returns the content of a file as string

Example

...
var filecontent = file.content
...

void file.decrementReferenceCount()

Decreases and reloads the reference count.

Example

...
file.decrementReferenceCount();
...

file.delete()

Deletes a given file (cannot be undone).

Example

...
file.delete()
...

string file.fileName

Returns the object's file name.

Example

...
var fname = file.fileName;
...

file.flexAttributes

Returns an array of the flex attributes of a file

Example

...
var flexAttribute = file.flexAttributes;
...

string file.cacheKey

Returns a string that you can use in the fragment cache. This string will change whenever the file is changed.

Example

... 
file.cacheKey # => "12589387317632578294"
...

string file.get(key)

Returns the value of key as string or null if no value is set under the key.

Example

...
var keyvalue = file.get(key);
...

Parameter key:string (required)

The key to be looked up in the flexAttributes of the file.

boolean file.has(key)

Returns a boolean value depending on whether key is present for a given file

Example

...
if file.has('description') 
{
  ...
}
...

Parameter key:string (required)

The key to be checked in the flexAttributes of the file.

int file.height

Returns the height attribute for a given file.

Example

...
var height = file.height;
...

string file.humanSize

Returns a human-readable file size with a precision of two decimal places.

Example

...
var humanSize= file.humanSize(); // => 5 MB
...

int file.id

Returns the ID of a file.

Example

...
var id = file.id;
...

string file.imagePath(max_width, max_height)

Native Dragonfly file URL

Example

...
var imgPath = file.imagePath(10, 5);
...

Parameter max_width (required)

Parameter max_height (required)

void file.increment(key)

Increments the vale of a given key by one.

Example

...
file.increment("amount");
...

Parameter key:string (required)

The key to be incremented in the flexAttributes of the file.

void file.incrementReferenceCount()

Increases and reloads the reference count.

Example

...
file.incrementReferenceCount();
...

string file.location

Returns the path of a file.

Example

...
var path = file.location;
...

string file.name

Returns the name of a file.

Example

...
var filename = file.name;
...

namespace file.namespace

Returns the namespace that a file belongs to.

Example

...
fileNamespace = file.namespace;
...

string file.path

Native unresized Dragongfly URL to the file

Example

...
var fileURL = file.path;
...

file.prepareResizedImage(size)

Prepares the thumbnail for a given file.

Example

...
file.prepareResizedImage(size)
...

Parameter size (required)

int file.referenceCount()

Returns the current reference count for a given file.

Example

...
var refCount = file.referenceCount();
...

file.remove(key)

Removes the key from the flexAttributes of the file

Example

...
file.remove("description");
...

Parameter key:string (required)

The key to be removed from the flexAttributes of the file.

file.resizedImage(size, [intermediate_size], [jpeg_quality], [strip_exif], [image_format], [scale_mode], [fillcolor], [custom_command])

Generates a resized temporary version of an image.

These are the image modifications you can do with this function:

• resize to a specific size, with all features of geometry strings (resize/crop etc.)
• resize from an intermediate size for performance considerations
• set the jpeg quality, when using an image of format jpeg or converting to this format.
• strip exif data from the jpeg file
• encode in another format
• use different scaling modes (tradeoff between performance and quality)
• fill transparent sections of an image with a color
• use custom imagemagick parameters to generate all kinds of effects

Example

...
file.resizedImage(size, [intermediate_size], [jpeg_quality]);
...

Parameter size:string (required)

An Imagemagick geometry string.

Parameter intermediate_size:string (optional)

An Imagemagick geometry string.

This size will be used as the intermediate size from which the image will be created. Another resizing step is done unless the intermediate size image has already been generated.

Parameter jpeg_quality:integer (optional)

The jpeg quality (0-100)

Parameter strip_exif boolean, default false (optional)

Whether to strip all EXIF data from the file. Applicable only for jpeg files. This step will be skipped for non-jpeg files.

Parameter image_format stringEnum[jpg,gif,png] (optional)

The new image format.

Parameter scale_mode stringEnum[scale, resize, box, sample] (optional)

The Imagemagick scaling mode. Defaults to 'scale'

Parameter fillcolor string[imagemagick_color] (optional)

Transparent parts will be filled with this color.

Example: 'white', '#ff000f'

Parameter custom_command string[imagemagick_convert_arguments] (optional)

One or more Imagemagick command line parameters.

Example: '+level-colors "#acd321","#abc123"'

file.set(key, value, [options])

Sets the value of a specified key for a given file.

Example

...
file.set(key, value, [options]);
...

Parameter key:string (required)

The key to be set in the flexAttributes of the file.

Parameter value:string (required)

The value to be set for the key

Parameter options:object (optional)

May have a key 'broadcastEvent':bool which determines whether the log message shows up in the websocket log view.

file.setContent(file, [options])

Sets the content of a file

Example

...
file.setContent(file, [options]);
...

Parameter file (required)

Parameter options (optional)

file.setName(name)

Sets the file name to the specified parameter.

Example

...
file.setName(name);
...

Parameter name (required)

The name that should be used

file.setNamespace(namespaceOrId)

Sets the namespace a file belongs in to the specified parameter.

Example

...
file.setNamespace(namespaceOrId);
...

Parameter namespaceOrId (required)

void file.setReferenceCount(count)

Sets the reference count of a file to the specified parameter.

Example

...
file.setReferenceCount(7);
...

Parameter count:int (required)

The number of references that should be set

file.setType(new_type)

Sets the type for a given file.

Example

...
file.setType(new_type)
...

Parameter new_type (required)

The new type for the file, that should be used

file.size

Returns the filesize for a given file.

Example

...
var filesize = file.size;
...

string[] file.tags

Returns an array of tags for a given file.

Example

...
var filetags = file.tags;
...

string file.type

Returns the type of a given file.

Example

...
var filetype = file.type;
...

file.update(object)

Updates the file

Example

...
file.update({ name: 'new.file.name.jpg' })
...

Parameter object (required)

string file.uuid

Returns the UUID for a given file.

Example

...
var fileUUID = file.uuid;
...

int file.width

Returns the width for a given file.

Example

...
var fileWidth = file.width;
...

IBS-Specific methods

void file.promoteIBS(options)

Registers the file with the IBS.

Example

...
file.promoteIBS()
...

Parameter options:object (optional)

The IBS-Options. See the IBS Entity Documentation for possible values.

void file.updateIBS(options)

Updates the file's IBS-Options in the remote IBS instance.

Example

...
file.updateIBS({ description: 'my file description' });
...

Parameter options:object (optional)

The IBS-Options. See the IBS Entity Documentation for possible values.

void file.deleteIBS()

Unregisters the file from the IBS.

Example

...
file.deleteIBS()
...

void file.deleteLocal()

Removes the local file. On next access it will be retrieved from IBS if possible.

Example

...
file.deleteLocal()
...

bool file.isIBS

Returns whether the file is registered with IBS.

Example

...
var isIBS = file.isIBS; # => true
...

entity file.getIBSEntity()

Returns the JSMA entity of the file.

Example

...
var entity = file.getIBSEntity();
...