Item Actions Extend the Item Class

One purpose for Methods is to extend the Item Class. Methods extend the Item Class when they are bound as the related Item for ‘Item Action’ relationships on the ItemType. In the AML the Method name is the action attribute name for the Item tag.

<Item type="My ItemType” action="My Method” id="…"/>

The Method could be called using the IOM like this (all three examples below are equivalent and are written in C#):

1) Item myItem = this.newItem(“My ItemType”, “My Method”);
myItem.setID(this.getID());
Item results = myItem.apply();
2) Item myItem = this.newItem(“My ItemType”);
myItem.setID(this.getID());
Item results = myItem.apply(“My Method”);
3) Item myItem = this.newItem();
myItem.setID(this.getID());
myItem.setType(“My ItemType”);
myItem.setAction(“My Method”);
Item results = myItem.apply();

As mentioned before Item Action Methods are executed on an instance of Item which is called a context item (read section Built in Action Methods for more information on how a context item is obtained for Item Action Methods). The context item must be referenced inside Item Action Methods as this keyword in JavaScript, and C#, and the Me keyword Object in VB.NET. The context item is an instance of the IOM Item class; correspondingly any methods of the IOM Item class (see section Item Class for more details) could be called on the context item, e.g this.getProperty(“foo”) (C#) or Me.getProperty(“foo”) (VB.NET).

Methods follow the Factory design pattern in that they return an Item or Error Object. The ‘Item Action’ Method must return an Item, which often is the result of an Item.apply() method call; typically, the last step in the business logic for the Method. There are several ways to create an Item; the following IOM methods return an Item Object: Item.apply(), Item.newItem(), Item.clone(), Innovator.newItem(), Innovator.newResult(), and Innovator.newError().

C#

Item qryItem = this.newItem(this.getType(), “get”);
qryItem.setID(this.getID());
qryItem.setLevels(1);
return qryItem.apply();

If the Method needs to return an error then use the Innovator.newError(text) method.

C#

Innovator innovator = this.getInnovator();
return innovator.newError(“This method has <b>failed</b>.”);

Sometimes it is desirable to share the same Method for many ItemTypes. However, there are cases in which the Method is intended to be used only by an Item of a specific ItemType.

The way you can prevent the use of a Method with a context item of a wrong type is to throw an exception when the wrong ItemType is used (this is what the core Item Class methods do when the ItemType is not of the specific desired value). Here is a sample of what should be done in a Method that needs to operate on a specific type of Item:

C#

Innovator innovator = this.getInnovator();
if (this.getType() != “My ItemType”)
{
return innovator.newError(“Item must be of type ‘My ItemType’”);
}
return null;

One of the principal concepts in programming Aras Innovator is to write Methods called on Items. The ‘Item Action’ relationships on ItemTypes simulate Object Oriented programming, where the ItemType is the Class and ‘Item Action’ relationships to Methods are the Class methods. Literally the Method code is compiled dynamically to extend the Item Class with this method and calls it. Like class instance in OO programming the context item is an object on which Methods are performed. At the same time there are some peculiarities in how to use a context item in Aras Innovator’s Item Action Methods. One important detail about Item Action Methods is that they must always return an Item which is the result of work done by the Item Action Method. An Item Action Method might work with a context item, but the context item is used here more as an input value (it still must be referenced as this or Me from inside Methods). It’s highly recommended that Item Action Methods do not change the context item but rather create a new item that is returned from the method. You can use the combination of the Item.getProperty(…) method with the Item.setProperty(…) method to populate the new temporary Item or use the Item.clone(…) method to construct the new Item from the context item. If the developer of the Method code chooses to modify the context item and not create a new item, the context item must be returned from the method.