Class: Totem

Defined in: src/totem.coffee

Overview

Note: Totem triggers an event called avatarChange on being notified that a build, equip, or colour change has occurred on an Avatar being drawn. Data sent by the event will be of the form avatar:<Avatar>, event:<String>. You can listen to this event using $(totem).on "avatarChange", (e, data) ->, or a similar method.
Note: Totem triggers events called startedDrawing and finishedDrawing on being notified that a DrawingService has started or finished drawing on a canvas. Data sent by the event will be of the form avatar:<Avatar> canvas:<Object>.

The Totem class provides an API for working with avatar builder applications. It's intended that you normally use Totem to create Avatars, Inventories and other collaborating objects rather than creating them yourself. Totem will then manage their lifecycles for you, including attaching relevant events, caching, etc.

Totem is not intended to replace an MVC framework; you may want to wrap objects like Avatars using your preferred model layer, so that you can find and sort them according to your application's requirements.

Instance Method Summary

Constructor Details

- (void) constructor(params)

Create a new Totem object.

Parameters:

  • params (Object) — Parameters to initialise Totem. These will be sent to config

Options Hash: (param):

  • clientId (Integer) — Required: the id of your client application (used by hapilib)

Instance Method Details

- (Object) config()
- (Object) config(key)
- (Object) config(params)
- (Object) config(key, value)

Get and set Totem's configuration.

Possible keys are: - representation Default avatar representation - palette Default palette -- A palette arranged by category: : colour1: ["#FF0000", ...], colour2: ["#00FFFF"] Optionally include a global: key if you want to use the palette globally. Unset keys will be silently ignored - globalPalette Whether to use the palette globally - defaultGoods An array of labels defining default goods to be purchased by the AuthorizedUser at bootstrap - defaultAssets An array of labels defining default assets to be used when resetting an avatar - drawingAdaptor Define an adaptor type which will be used to draw avatars. should be given in the form type:<String>, options:<Object>. type should be a requirable class in the "./drawing/adaptor" folder. options is an object passed to the class constructor. Default is type: "canvasElement", which will create a new {CanvasElementAdaptor CanvasElementAdaptor} - authService A service which will be used for authentication. Default is a new AuthService

Overloads:

- (Object) config()

Get the current configuration.

Returns:

  • (Object) — The current configuration

- (Object) config(key)

Get the value for a key in the current configuration

Parameters:

  • key (String) — The key for the value you want to get

Returns:

  • (Object) — The value of the given key

- (Object) config(params)

Set the complete configuration

Parameters:

  • config (Object) — The complete configuration

Returns:

  • (Object) — The set configuration

- (Object) config(key, value)

Set the value for a key in the configuration

Parameters:

  • key (String) — The key for which to set the value
  • value (Object) — The value to set

Returns:

  • (Object) — The value set

- (Object) authenticate(type = "client", data = {}, bootstrap = false)

Authenticate with a HAPI instance.

Examples:

`totem.authenticate "code", code: 5496`
or
`totem.authenticate "code", (callback) -> callback code: 5496`

Parameters:

  • type (String) — How to authenticate; see AuthService
  • data (Object/Function) — Data to send with the authentication request, or a function which will call back with that data; see AuthService

Returns:

  • (Object) — A promise, resolving when authentication is complete

- (Boolean) userIsAuthorized()

Whether an authorized user is available.

Returns:

- (void) logout()

Log out of the application.

- (Object) bootstrap()

Load all data necessary to bootstrap an app.

Returns:

  • (Object) — A promise, resolving to an object of form inventory:<Inventory>, categories:<Array>, goods:<Array>, userGoods:<Array>

- (AbstractUser) user()

Get the active user - either a GuestUser or an AuthorizedUser.

Throws:

  • (Error) — If no user is active

Returns:

- (Object) categories()

Retrieve the categories used by the avatar.

Returns:

  • (Object) — A promise, resolving to an array of category data

- (Object) goods()

Retrieve all available goods.

Returns:

  • (Object) — A promise, resolving to an array of goods data

- (Object) purchase(good, options = {})

Purchase a good on behalf of the logged-in user. On a successful purchase, the Inventory is refreshed.

Parameters:

  • good (String) — The label of a good to purchase
  • options (Object) — Options to use in the purchase

Options Hash: (option):

  • paymentService (Object) — A payment service which will confirm that payment has been recieved for the good. Should accept as arguments userId, goodId, callback and call back with error, response
  • purchaseService (PurchaseService) — Optional. Defaults to a new PurchaseService
  • confStrategy (Function) — Optional. A confirmation strategy to use to determine whether the purchase has been accepted by the HAPI server. Accepts arguments user, goodId, paymentResponse and returns a promise, resolving with any [Error] raised during the confirmation process.

Returns:

  • Object

- (Object) purchaseDefaultGoods()

Ensure that the user owns any {#defaultGoods default goods}.

Returns:

  • (Object) — A promise, resolving when all purchases are complete

- (Object) assets()

Retrieve assets available to a user, indexed by good. Delegates to User.

Returns:

  • (Object) — A promise, resolving to an object of form good: [assets]

- (Object) inventory()

Retrieve a complete Inventory.

Returns:

  • (Object) — A promise, resolving to an Inventory

- (Object) refresh()

Refresh the inventory. This will reload assets available to the user and add any new ones to the inventory.

Returns:

  • (Object) — A promise, resolving when the refresh is complete

- (Avatar) avatar(representation = null, attributes = {})

Create a new Avatar. If {#defaultAssets defaultAssets} have been set, the avatar will be built using them.

Parameters:

  • representation (String) — A representation. Will use the {#representation default} if not given.
  • attributes (Object) — A set of attributes. Optional, including (Id:, Label:, Metadata:, Assets:)

Returns:

- (Object) avatars(options = {})

Get an Avatar or set of Avatars belonging to the User. If the default representation is not set, and avatars retrieved do not have representations set, avatars will be returned without renderable assets, and must be built using randomise or Avatar#build; you can force 'bare' avatars to be returned using the option assets: false. Image urls can still be retrieved from non-renderable avatars.

Parameters:

Returns:

  • (Object) — A promise, resolving to an Avatar or array of Avatars

- (Object) randomise(avatar, options = {}, inventory = null)

Randomise the assets equipped to an Avatar. This operation will use the representation set on an avatar, or the {#representation default representation}. If no representation can be set using these values, an error will be thrown.

Parameters:

  • avatar (Avatar) — An Avatar to randomise
  • options (Object) — Options to use to randomise the Avatar
  • inventory (Inventory) — An Inventory. Will attempt to use the cached inventory if not given

Options Hash: (option):

  • palette (Array<Array<String>>) — See {#palette}. If not given, will use the {#palette default palette}
  • globalPalette (Boolean) — See {#globalPalette}. If not given, will use the {#globalPalette default setting}

Throws:

  • (Error) — If no representation is given (explicitly or by default)

Returns:

  • (Object) — A promise, resolving when randomisation is complete

- (Avatar) reset(avatar, inventory = null)

Reset the given Avatar's assets to the {#defaultAssets defaults}. This operation will use the representation set on an avatar, or the {#representation default representation}. If no representation can be set using these values, an error will be thrown.

Parameters:

  • avatar (Avatar) — The Avatar to reset
  • inventory (Inventory) — An inventory to retrieve assets from. Will attempt to use the cached Inventory if not given

Returns:

- (Object) drawOn(avatar, canvas, options = {}, service = null)

Draw an Avatar on an HTMLCanvasElement. The autoDraw option, true by default, will keep drawing the avatar on the given canvas whenever a change is made to it (a build, equip or colour change), until a different Avatar is drawn on the canvas.

Parameters:

  • avatar (Avatar) — The avatar to draw
  • canvas (HTMLCanvasElement) — The canvas to draw on
  • options (Object) — Options to use when drawing

Options Hash: (option):

  • autoDraw (Boolean) — Whether to keep drawing the avatar on the canvas

Returns:

  • (Object) — A promise, resolving when the first draw is complete