forio Toggle navigation

Asset API Adapter

The Asset API Adapter allows you to store assets -- resources or files of any kind -- used by a project with a scope that is specific to project, group, or end user.

Assets are used with team projects. One common use case is having end users in a group or in a multiplayer world upload data -- videos created during game play, profile pictures for customizing their experience, etc. -- as part of playing through the project.

Resources created using the Asset Adapter are scoped:

Project assets are writable only by team members, that is, Epicenter authors. Group assets are writable by anyone with access to the project that is part of that particular group. This includes all team members (Epicenter authors) and any end users who are members of the group -- both facilitators and standard end users. User assets are writable by the specific end user, and by the facilitator of the group. All assets are readable by anyone with the exact URI.

To use the Asset Adapter, instantiate it and then access the methods provided. Instantiating requires the account id (Team ID in the Epicenter user interface) and project id (Project ID). The group name is required for assets with a group scope, and the group name and userId are required for assets with a user scope. If not included, they are taken from the logged in user's session information if needed.

When creating an asset, you can pass in text (encoded data) to the create() call. Alternatively, you can make the create() call as part of an HTML form and pass in a file uploaded via the form.

// instantiate the Asset Adapter
var aa = new F.service.Asset({
   account: 'acme-simulations',
   project: 'supply-chain-game',
   group: 'team1',
   userId: '12345'
});

// create a new asset using encoded text
aa.create('test.txt', {
    encoding: 'BASE_64',
    data: 'VGhpcyBpcyBhIHRlc3QgZmlsZS4=',
    contentType: 'text/plain'
}, { scope: 'user' });

// alternatively, create a new asset using a file uploaded through a form
// this sample code goes with an html form that looks like this:
//
// <form id="upload-file">
//   <input id="file" type="file">
//   <input id="filename" type="text" value="myFile.txt">
//   <button type="submit">Upload myFile</button>
// </form>
//
$('#upload-file').on('submit', function (e) {
   e.preventDefault();
   var filename = $('#filename').val();
   var data = new FormData();
   var inputControl = $('#file')[0];
   data.append('file', inputControl.files[0], filename);
   aa.create(filename, data, { scope: 'user' });
});

Constructor options

Required? Name Type Description
Yes userId string The user id. Defaults to session's userId.
Yes scope user / group / project The scope for the asset. Valid values are: user, group, and project. See above for the required permissions to write to each scope. Defaults to user, meaning the current end user or a facilitator in the end user's group can edit the asset.
Yes fullUrl boolean Determines if a request to list the assets in a scope includes the complete URL for each asset (true), or only the file names of the assets (false). Defaults to true.
  account string The account id. In the Epicenter UI, this is the Team ID (for team projects) or User ID (for personal projects). Defaults to undefined. If left undefined, taken from the URL.
  project string The project id. Defaults to undefined. If left undefined, parsed from the URL.
  token string For projects that require authentication, pass in the user access token (defaults to undefined). If the user is already logged in to Epicenter, the user access token is already set in a cookie and automatically loaded from there. (See more background on access tokens). @see Authentication API Service for getting tokens.
  transport JQueryAjaxOptions Options to pass on to the underlying transport layer. All jquery.ajax options are supported.
  server object
  server.host string The value of host is usually the string api.forio.com, the URI of the Forio API server. This is automatically set, but you can pass it explicitly if desired. It is most commonly used for clarity when you are hosting an Epicenter project on your own server
  server.protocol https / http Defaults to https

Methods

create(filename[, params, options])

Creates a file in the Asset API. The server returns an error (status code 409, conflict) if the file already exists, so check first with a list() or a get().

Parameters

Required? Name Type Description
Yes filename string Name of the file to create.
  params object Body parameters to send to the Asset API. Required if the options.transport.contentType is application/json, otherwise ignored.
  params.encoding string Either HEX or BASE_64. Required if options.transport.contentType is application/json.
  params.data string The encoded data for the file. Required if options.transport.contentType is application/json.
  params.contentType string The mime type of the file. Optional.
  options object Options object to override global options.

Example

var aa = new F.service.Asset({
         account: 'acme-simulations',
         project: 'supply-chain-game',
         group: 'team1',
         userId: ''
      });

      // create a new asset using encoded text
      aa.create('test.txt', {
          encoding: 'BASE_64',
          data: 'VGhpcyBpcyBhIHRlc3QgZmlsZS4=',
          contentType: 'text/plain'
      }, { scope: 'user' });

      // alternatively, create a new asset using a file uploaded through a form
      // this sample code goes with an html form that looks like this:
      //
      // <form id="upload-file">
      //   <input id="file" type="file">
      //   <input id="filename" type="text" value="myFile.txt">
      //   <button type="submit">Upload myFile</button>
      // </form>
      //
      $('#upload-file').on('submit', function (e) {
         e.preventDefault();
         var filename = $('#filename').val();
         var data = new FormData();
         var inputControl = $('#file')[0];
         data.append('file', inputControl.files[0], filename);

         aa.create(filename, data, { scope: 'user' });
      });

get(filename[, options])

Gets a file from the Asset API, fetching the asset content. (To get a list of the assets in a scope, use list().)

Parameters

Required? Name Type Description
Yes filename string (Required) Name of the file to retrieve.
  options object Options object to override global options.

list([options])

Gets the list of the assets in a scope.

Parameters

Required? Name Type Description
  options object Options object to override global options.
  options.scope string The scope (user, group, project).
  options.fullUrl boolean Determines if the list of assets in a scope includes the complete URL for each asset (true), or only the file names of the assets (false).

Example

aa.list({ fullUrl: true }).then(function(fileList){
          console.log('array of files = ', fileList);
      });

replace(filename[, params, options])

Replaces an existing file in the Asset API.

Parameters

Required? Name Type Description
Yes filename string Name of the file being replaced.
  params object Body parameters to send to the Asset API. Required if the options.transport.contentType is application/json, otherwise ignored.
  params.encoding string Either HEX or BASE_64. Required if options.transport.contentType is application/json.
  params.data string The encoded data for the file. Required if options.transport.contentType is application/json.
  params.contentType string The mime type of the file. Optional.
  options object Options object to override global options.

Example

// replace an asset using encoded text
      aa.replace('test.txt', {
          encoding: 'BASE_64',
          data: 'VGhpcyBpcyBhIHNlY29uZCB0ZXN0IGZpbGUu',
          contentType: 'text/plain'
      }, { scope: 'user' });

      // alternatively, replace an asset using a file uploaded through a form
      // this sample code goes with an html form that looks like this:
      //
      // <form id="replace-file">
      //   <input id="file" type="file">
      //   <input id="replace-filename" type="text" value="myFile.txt">
      //   <button type="submit">Replace myFile</button>
      // </form>
      //
      $('#replace-file').on('submit', function (e) {
         e.preventDefault();
         var filename = $('#replace-filename').val();
         var data = new FormData();
         var inputControl = $('#file')[0];
         data.append('file', inputControl.files[0], filename);

         aa.replace(filename, data, { scope: 'user' });
      });

delete(filename[, options])

Deletes a file from the Asset API.

Parameters

Required? Name Type Description
Yes filename string (Required) Name of the file to delete.
  options object Options object to override global options.

Example

aa.delete(sampleFileName);