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' });
  });

Configuration Options

token

For projects that require authentication, pass in the user access token (defaults to empty string). 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).

account

  • String

The account id. In the Epicenter UI, this is the Team ID (for team projects). If left undefined, taken from the URL.

project

  • String

The project id. If left undefined, taken from the URL.

group

  • String

The group name. Defaults to session's groupName.

userId

  • String

The user id. Defaults to session's userId.

scope

  • String

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.

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.

transport

  • object

The transport object contains the options passed to the XHR request.

Methods

create

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().

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' });
  });

Parameters

  • filename: string (Required) Name of the file to create.

  • params: object (Optional) 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 (Optional) Options object to override global options.

get

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

Parameters

  • filename: string (Required) Name of the file to retrieve.

  • options: object (Optional) Options object to override global options.

list

Gets the list of the assets in a scope.

Example

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

Parameters

  • options: object (Optional) Options object to override global options.

  • options.scope: string (Optional) The scope (user, group, project).

  • options.fullUrl: boolean (Optional) 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).

replace

Replaces an existing file in the Asset API.

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' });
  });

Parameters

  • filename: string (Required) Name of the file being replaced.

  • params: object (Optional) 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 (Optional) Options object to override global options.

delete

Deletes a file from the Asset API.

Example

  aa.delete(sampleFileName);

Parameters

  • filename: string (Required) Name of the file to delete.

  • options: object (Optional) Options object to override global options.