Action System

Introduction

DutchPIPE has a powerful action system. Actions can be performed by clicking on items and selecting the desired menu entry. Alternatively users can type actions in "verb noun" style. This system is also used under the hood when you use the mouse, and by computer generated characters. So performing an action is defined as either clicking on an object and selecting the desired action (for example "examine" on a flower object), or by entering a command ("examine flower").

You can define actions in all objects. A note would sport the action "read", a beer the action "drink", and so on. Adding an action involves calling the addAction method in an object, usually from its creation method. addAction is defined in the DpObject class, which all objects extend on. It takes arguments such as the menu title, verb and the method to call when the action is executed. An action doesn't have to appear on the object that defines it. addAction takes arguments that allow you to set where and for who the action appears. For example, the DpLiving class, which user objects extend on, defines actions such as "examine" which appear on other objects' menus.

How addAction and the action system work

Actions are added to objects by calling addAction with at least the three mandatory parameters: its title in the menu ($actionMenu), its command line equivalent ($actionVerb), and the method called in this object when a user or object performs the action ($actionMethod).

So note.php has the following line in its createDpObject method:

1. $this->addAction('read me!', 'read', 'actionRead');

When someone clicks on the note and selects "read me!", or types "read something" or even just "read", method actionRead is called with two parameters:

1. function actionRead($verb, $noun)

$verb contains "read", $noun contains whatever else the user typed (minus the leading space, NULL if only the verb was given), or the objects unique id if the mouse was used (see DpObject's uniqueId property).

This method should check for the right syntax and if the right noun is used. If not, it should throw an error and return FALSE. By returning FALSE, execution continues and other objects defining the read command may be called. If succesful, it should show messages and return TRUE.

1. function actionRead($verb, $noun)
2. {
3.     /* Replies to object entering "read" */
4.     if (!strlen($noun)) {
5.         get_current_dpobject()->actionFailure =
6.             'What do you want to read?<br />';
7.         return FALSE;
8.     }
9.  
10.     /* Replies to object entering "read noet" (typo) */
11.     if (FALSE === $this->isId($noun)) {
12.         get_current_dpobject()->actionFailure = 'Read WHAT?<br />';
13.         return FALSE;
14.     }
15.  
16.     /* Shows a nice window with content */
17.     get_current_dpobject()->tell('<window>Hello world.</window>');
18.     return TRUE;
19. }

The get_current_dpobject function returns the object causing the current chain of execution, in this case the object performing the action.

When the user or NPC performs an action but the action fails, there are two ways for the method implementing the action to communicate the failure to the.

1. Call tell() in the object and return TRUE, for example:

   1. get_current_dpobject()->tell('Action foo failed because of bar.');
   2. return TRUE;

   The action system will stop looking for other ways to perform the action.

2. Set the actionFailure property, defined by the DpLiving class, in the object performing the action and return FALSE. This failure setup is used when different objects can have the same actions implemented with addAction - if one fails, another might still succeed. Example:

   1. get_current_dpobject()->actionFailure = 'Action foo failed because of bar.';
   2. return FALSE;

   The action system will continue looking for other ways to perform the action. If it doesn't find any, the previously set failure message is communicated. Otherwise, the next method implementing the action takes over. The action system will continue looking for object/methods implementing the action, until TRUE is returned or no more implementations are found. In that case, the last set action failure is communicated. If no action failure was set, the default failure message is shown, see the actionDefaultFailure property defined in DpLiving. This is "What?" by default for the English version of DutchPIPE.

Full parameter list for addAction

The full addAction synopsis looks like this, with only the first three parameters mandatory.

1. public function addAction(
2.     $actionMenu,
3.     $actionVerb,
4.     $actionMethod,
5.     $actionOperant = DP_ACTION_OPERANT_MENU,
6.     $actionTarget = DP_ACTION_TARGET_SELF,
7.     $actionAuthorized = DP_ACTION_AUTHORIZED_ALL,
8.     $actionScope = DP_ACTION_SCOPE_ALL,
9.     $mapArea = NULL,
10.     $mapAreaAction = NULL)

Most parameters can be callback methods. A callback method is defined by an array of two elements, the object where the method can be found and a string with the name of the method, see the is_dp_callable() function. If you give a callback method, it is called with the following parameters: a string with the action verb, the object the action is targetted on (which is NULL if the action is entered from the command line), the object defining the action and the object performing the action. Usually these are not all different objects.

Various parameters use constants defined in actions.php.

The parameters in full detail:

• mixed $actionMenu

• The text for the clickable action menu item. Can be one of the following.

  • string

  • A simple string, for example "smile", with text for the menu entry. It may not contain the # character, which is reserved for the following two possible formats.

  • "iconImgHtml#text"

  • A string with HTML for an image separated by a # from the text used for the menu entry, for example <img src="/images/checked.gif" width="7" height="7" border="0" alt="" title="" />#command mode

  • "iconImgHtml#iconSrcOver#text"

  • A string with HTML for an image separated by a # from the image location used to replace the src attribute of the image when the mouse is moved over the menu entry, separated by another # from the text used for the menu entry, for example <img src="/images/checked.gif" width="7" height="7" border="0" alt="" title="" />#/images/check_over.gif#command mode

  • array

  • An array of the above elements can be given to create submenus, for example array('more chat', 'emotions', 'smile'). Elements may be callbacks method like seen below, and should return a value in one of the formats above.

  • callback method

  • A callback method which should return a value in one of the formats above.

  Can also be an array of strings and/or callback methods to create submenus.

• mixed $actionVerb

• The verb of the alternative command which can be entered from the command line, or an array of strings to give various aliases.

  • string

  • A simple string, for example "smile", with text for the menu entry. The rest of the command (usually only a noun), must not be given. The full commands that menus produce are dynamically generated according to the $actionOperant argument (see below).

  • array

  • An array with aliases for use in the input area, for example array('take', 'get'). The first alias is used for menu actions, from a command line both take and get can be used.

• mixed $actionMethod

• The method called to perform the action when it is clicked on or entered as a command.

  • string

  • The method with the given name is called in the object defining the action,

  • callback method

  • A callback method can be used to call a method in other objects.

• mixed $actionOperant = DP_ACTION_OPERANT_MENU

• $actionOperant is used when you click to perform an action only, and is used to define on who the action operates, in other words, how the verb noun command that is internally formed gets its noun. $actionOperant can be:

  • DP_ACTION_OPERANT_MENU

  • The default, the noun becomes the object that carries the action in its action menu, for example "object_41", a unique object id. Where a user would type "read note", clicking would generate "read object_41".

  • DP_ACTION_OPERANT_NONE

  • There is no noun, for example "laugh".

  • DP_ACTION_OPERANT_COMPLETE

  • Ask the user on who or what the action must be performed by inserting the verb into the command line.

  • callback method

  • The callback method should return either a string, which is then used, with the verb, to complete the command, or an array defining a submenu. If the string ends with a space, the command will be inserted into the input area, so it can be further completed by the user. Otherwise the command is immediately executed after clicking, without use of the input area.

    This array should consist of key/value pairs of a string with the text of the clickable submenu item, and a string with the full associated command.

• mixed $actionTarget = DP_ACTION_TARGET_SELF

• On which objects' action menus must this action appear?

  • DP_ACTION_TARGET_SELF

  • The default, the action appears on the object that defines it. For a user object that defines actions, this would be true for the action "laugh", it should appear in the action menu of the user itself.

  • DP_ACTION_TARGET_LIVING

  • The menu item appears on other users and computer generated characters in the inventory or environment, for example action "kiss" should not appear on the user but on anyone near.

  • DP_ACTION_TARGET_LIVING

  • The menu item appears on other users in the inventory or environment.

  • DP_ACTION_TARGET_OBJINV

  • Makes the action appear on any object in the object's inventory.

  • DP_ACTION_TARGET_OBJENV

  • Makes the action appear on any object in the object's inventory.

  • DP_ACTION_TARGET_NONE

  • Action doesn't appear on any action menu.

  • array($ob, target)

  • Use object $ob instead of the object adding the action, with target one of the constants above.

  • combination

  • A combination of DP_ACTION_TARGET_SELF, DP_ACTION_TARGET_LIVING, DP_ACTION_TARGET_OBJINV, and DP_ACTION_TARGET_OBJENV separated by the | character, for example: DP_ACTION_TARGET_SELF | DP_ACTION_TARGET_OBJINV

  • callback method

  • The callback method should return any of the above.

• mixed $actionAuthorized = DP_ACTION_AUTHORIZED_ALL

• What objects or users may perform the action if the action is in their scope (see next parameter)?

  • DP_ACTION_AUTHORIZED_ALL

  • The default, everybody may try to perform the action (although the method that is called may forbid it anyway)

  • DP_ACTION_AUTHORIZED_GUESTS

  • The action becomes only available for guests.

  • DP_ACTION_AUTHORIZED_REGISTERED

  • The action becomes only available for registered users.

  • DP_ACTION_AUTHORIZED_ADMIN

  • Restrict the action to your site administrators.

  • DP_ACTION_AUTHORIZED_DISABLED

  • The action is "ghosted" in the menu for everybody.

  • combination

  • A combination of DP_ACTION_AUTHORIZED_DISABLED with one the other authorization constants, separated by the | character.

  • callback method

  • The callback method should return any of the above.

• mixed $actionScope = DP_ACTION_SCOPE_ALL

• Which objects have access to the action to begin with?

  • DP_ACTION_SCOPE_ALL

  • The default, the action becomes available for the object to which is was added, but also all objects it contains or in its environment. For example, the action "read" on a note uses this.

  • DP_ACTION_SCOPE_SELF

  • The action becomes available for the object itself only. For example, the action "smile" added to a user object ecomes available for the user, not other objects nearby.

  • DP_ACTION_SCOPE_ENVIRONMENT

  • Restrict the scope to the environment of the object

  • DP_ACTION_SCOPE_INVENTORY

  • Restrict the scope to the inventory of the object

  • array($ob, scope)

  • Use object $ob instead of the object adding the action, with scope one of the constants above.

  • combination

  • A combination of one of the constants above, separated by the | character.

  • callback method

  • The callback method should return any of the above.

• mixed $mapArea = NULL

• Normally actions appear on the menus that appear when clicking on objects. You can make them appear on imagemaps on pages by providing a non NULL value with this argument.

  • NULL

  • Don't use imagemaps. The default.

  • string

  • The imagemap area id of an area previously set by a call to setMapArea in DpObject.

  • array

  • An array with the arguments to setMapArea in DpObject, in which case the imagemap area will be created on the fly.

• string $mapAreaAction = NULL

• Specific action to use when $mapArea (see above) is not NULL.

  • NULL

  • The default, when you click on the action, the right phrase (in only verb or verb noun format, for example) is automatically constructed.

  • string

  • If this doesn't lead to the desired effect, the full action phrase to use can be given here.

Other methods adding actions

With the addItem method in DpObject you can add things that can be examined.

With the addExit method in DpObject you can add exits to a page. This can be used by imagemaps, by NPCs or by entering the exit from the command line.