JSMA files

Owned by Claudius Knaak
Last updated: Mar 12, 2019 by Pascal Hartmann (Unlicensed)

Overview

The JSMA files provides functionality for finding, creating and deleting file contents. Currently the JSMA is used for editor uploads, scaled image downloads of images in the editor to users and x-server delivery of piced stores. Also the delivery of static file contents like banners, js, css resources and so on is provided by the JSMA files.

What can JSMA files do for me?

You could easily use the JSMA files to script uploading of whole file packages like cliparts or banners from external source

Index

Usage

writing data

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

...
//Creates a file in the package test
//Post multipart see jsma request
 
var pckg = packages.findByName("test");
var fileParam = request.parameter("file");
 
var file = files.create(fileParam, {
type: 'admin_upload',
package: pckg,
name: 'filename.jpg' });
...

reading data

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

...
//find by name
var file = files.findByName("logo.portal");
//return path if file was found
if (file !== null) {
  return "/static/file/get?id=" + file.uuid;
}
...

Methods

The JSMA files provides the following methods:

file files.create(fileParam, [options])

Creates a file from a multipart post parameter with options defining where to put it on the server.

Example

...
//Creates a file in the package test
//Post multipart see jsma request

var pckg = packages.findByName("test"); 
var fileParam = request.parameter("file"); 

var file = files.create(fileParam, {
type: 'admin_upload',
package: pckg,
name: 'filename.jpg' });
...

Parameter fileParam:FileParameter (required)

A request parameter that was retrieved from a multipart upload. See request.parameter in JSMA request.

Parameter options:object [optional]

Options for the new file.

Option type (default:html_editor_upload)

The bucket the file is put into on the server. The bucket "admin_upload" is displayed in the Powereditor. Other buckets are used by the system or libs for the different kinds of uploads.

Create own buckets

You can anytime specifiy your own bucket.


  • admin_upload (this bucket is shown in the Powereditor)
  • html_editor_upload (Uploads by users in the editor - is the DEFAULT)
  • preview_image (INTERNAL - Please dont use this)
  • cover_image (INTERNAL Legacy - Please dont use this)
  • template_file (INTERNAL - Please dont use this)
  • template_image (INTERNAL - Please dont use this)
  • print_file (INTERNAL - Please dont use this)
  • frontside_preview (INTERNAL Legacy - Please dont use this)
  • backside_preview (INTERNAL Legacy - Please dont use this)
  • package_zip (INTERNAL - Please dont use this)

Dont use INTERNAL

The buckets which are marked as INTERNAL are not meant to be used by macros. They might be changed in the libs and cause interferences with system components.


Cleanup on html_editor_upload

Most productive instances of IFE4 are configured to clean up old user uploads after X weeks, as the available disk space otherwise might deplete quickly over time and most user data like images are not needed after the session is timed out or the order is processed.

So if you want to upload data which shall remain on the server like extra data for customers, orders or products please make sure to use the bucket admin_upload!

Option package (default:-1)

Creates the file in the given package. You can overgive the package or the package id. The files in the package can then be retrieved using jsma package.

Option name (default:name in fileParam)

Per default the name will be retrieved from the fileParam which is given. This option allows to change the name of the newly created file.

Returns file

The new file or null otherwise.

file[] files.find(query, [options={}])

The function signature files.find(query, [page], [limit]) is deprecated and will produce a warning in log files.

Retrieves limit file for the given Sphinx query. The sort order relies on the database order (MySQL in IFE3 and PostgreSQL in IFE4).

Example

...
var files = files.find("logo", { limit: 10, page: 2 }); 

var filesOld = files.find("logo", 1, 10); // deprecated
...

Parameter query:string (required)

Query in Sphinx Extended Syntax.

Parameter options:object (optional)

Default value for page:int will be 1 if no value is provided.

Default value for limit:int will be 10 if no value is provided.

Returns file[]

Returns an array of the found files or an empty array if no files match the query.

file files.findById(id)

Retrieves a file by its id.

Avoid usage of findById

Ids change whenever a package is reimported. So please avoid using ids whenever possible. Also delivering contents to users by id might make it possible for users to flip through the files (and by that see contents of others possibly) by changing the ids in requests.


Example

...
var file = files.findById(123);
...

Parameter id:int (required)

Id of the file.

Returns file

The file or null if not found.

file files.findByName(name)

Retrieves a file by its name.

Example

...
var file = files.findByName("logo.portal");
...

Parameter name:String (required)

Name of the file.

Returns file

The file or null if not found.

file files.findByUuid(uuid)

Retrieves a file by its uuid. This is good for supporting userfiles as giving the user apis whicht find files by uuid are not easy to abuse finding files of other users as uuids have 2exp128 possibilities.

Example

...
var file = files.findByUuid(uuidParam);
...

Parameter uuid:uuid (required)

Uuid of the file.

Returns file

The file or null if not found.

IBS-Specific methods

void files.promoteIBS(files, [options])

Stores multiple JSMA file remotely, creating IBS entites for each one in a single API call.

Example

...
files.promoteIBS([file0, file1], { description: 'a common description' });
...

Parameter files:file[] (required)

An array of JSMA file objects.

Parameter options:object (optional)

Common options for the files that will be stored.
See possible fields in the IBS entity documentation.

void files.updateIBS(files, [options])

Updates multiple IBS-backed JSMA file objects in a single API call.

Example

...
files.updateIBS([file0, file1], { description: 'a common description' });
...

Parameter files:file[] (required)

An array of JSMA file objects.

Parameter options:object (optional)

Common options for the files that will be updated.
See possible fields in the IBS entity documentation.

void files.deleteIBS(files)

Updates multiple IBS-backed JSMA file objects in a single API call.

Example

...
files.deleteIBS([file0, file1]);
...

Parameter files:file[] (required)

An array of JSMA file objects.

reference[] files.referenceIBS(parent, *children)

Creates a /wiki/spaces/IKONA/pages/555810842 for each given child.

Example

...
var refs = files.referenceIBS(parent, file1, file2);
refs[0].uuid # => '4c8f8a4c-795c-47cd-adfa-fe3650e9d114'
...

Parameter parent:file (required)

A JSMA file designated as parent in the reference.

Parameter children:file (required)

One or several JSMA file that will be referenced as children.

Further code examples

WebMacro swcl:file.path

Returns the url path to the file.

Source

/*
* Copyright Jenomics GmbH 2018. All rights reserved.
* For details to the licence read www.jenomics.de/softwarelicense
*/
//has to be called with exactly 1 parameter
if (args.length === 1) {
  //find by name
  var file = files.findByName(args[0]);
  //return path if file was found
  if (file !== null) {
    return "/static/file/get?id=" + file.uuid;
  }
}

WebMacro swcl:file.get

Returns a natural, flex or functional attribute of a file object.

Source

/*
* Copyright Jenomics GmbH 2018. All rights reserved.
* For details to the licence read www.jenomics.de/softwarelicense
*/
include("swcl.lib");
//needs at least 2 attributes
if (args.length > 1) {
  //find file by args[0] - name
  var file = files.findByName(args[0]);
  //if file found use swcl.lib.getFileAttribute to retrieve virtual attribute with args[1] - key
  if (file !== null) {
    return getFileAttribute(file, args[1], args);
  }
}

WebMacro swcl:image.path

Returns the url path to the image with given maxX and maxY dimensions.

Source

function main(imageName, maxWidth, maxHeight)
{
  //find image by imageName
  var image = files.findByName(imageName),
  size = "";
  //if found return path calculated from uuid and args[1] - maxX and args[2] - maxY
  if (image !== null) {
    if (typeof maxWidth !== 'undefined' && maxWidth !== null) {
     size += "&size=" + maxWidth + "x";
     if (typeof maxHeight !== 'undefined' && maxHeight !== null) {
      size += maxHeight;
    } else {
      size += maxWidth;
    }
  }
  return "/static/image/get?id=" + image.uuid + size;
 }
 return "";
}

For further details see image.path