Last updated September 26, 2012. Created on July 24, 2012.
Edited by Sylvain Lecoy. Log in to edit this page.

This is the specifications for the WoW Character component.

API specifications

Character entity

The WoW Character component declares a Character entity. The entity is composed of the basic dataset returned when requesting the API with zero additional fields.

  • realm: character's realm (in its slug version).
  • name: character's name.
  • level: character's level.
  • lastModified: timestamp for character last modification date (service side).
  • thumbnail: character's thumbnail.
  • race: character's race. @see wow_character_races().
  • achievementPoints: character's achievement points.
  • gender: character's gender.
  • class: character's class. @see wow_character_classes().

The following fields are added and used by the component:

  • cid: the {character}.cid primary key.
  • uid: the {user}.uid foreign key when a character is owned by a user.
  • region: character's region.
  • status: whether the character is blocked(0) or active(1).
  • isMain: whether the character is an alt(0) or a main(1). By convention, a user can have only one main.
  • lastFetched: timestamp for character last fetched date (client side).
  • gid: WoW Guild Component. The {wow_guild}.gid foreign key of the character's guild.
  • rank: WoW Guild Component. The rank of the character within the above guild.

Note: The term "client side" is the website using the World of Warcraft API, whereas "service side" is the Blizzard API service itself.

WoW Guild Component: When installing the WoW Guild Component, the Character entity base table is modified, the 'gid' and 'rank' column are added (read more).

The component will ensure unicity of a main character. By itself, it is checked in the presave method when character saving is triggered. Changing isMain from 0 to 1 result in an update of the isMain property to 0 for other characters belonging to the user.

Administration

The WoW Character component provides two administrative links, one for managing characters and users mapped to them of your website, another for managing the wow_character entity itself.

  • Characters administration page: admin/wow/characters. This page allows you to manage characters present in your database. You can block/unblock characters, and set a main character for your users. You get a listing that you can filter by class, race, or rank in the guild for instance.
  • Character entity configuration: admin/config/wow/characters. This page allows you to configure the entity itself. You can set the refresh mode, three methods for refreshing characters are supported and a threshold can be set.
    1. At loading time: each time you load a character entity from the database, the lastFetched timestamp get checked, and the character get refreshed from the battle.net API if needed (compared with threshold value). Because each time a character needs an update, the loading hook make a remote API call, this mode is best suited for small guild website for instance.
    2. Via cron: each cron runs, all characters that needs a refresh will be queued in a separate thread using the Drupal cron queue API. This allows long running tasks such as massive character update to be run in parallel for instance. This mode is best suited for both small guild website or large community website as the remote API call is defined.
    3. By code: this mode does not refresh the entity at all, developers that wants to provide their own methods can lock the module API into this mode for instance, and write their own implementation for character refresh. Developers can have more information on how to provide their own refresh mode. This mode is for website that need complete control over API calls.

User functionalities

The user functionalities are the possibilities of owning multiple characters through an in-game verification mechanism:

  1. Navigate to your user page, and select the Characters tab.
  2. Under the table of characters, you can add your own character by specifying a realm and a name.
  3. Once added to the list, you are able to unlock/verify your character by clicking on the operation link.
  4. The default procedure asks you to remove 4 items, then log out the game. Submit the form and if a modified character is detected, it will be linked to your account.

This list also allow to select a main character (the default one), and the component logic ensure a character and only one can be main.

Theming

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.