Table of Contents Previous Section

Action Methods

An action method is a method that's associated with a user action. You associate methods with a user action using a dynamic element. For example, WOSubmitButton has an attribute named action to which you can assign a method. When the submit button in the corresponding HTML page is clicked, the action method is invoked in the subsequent cycle of the request-response loop. This declaration in the HelloWorld application associates the action method sayHello with a submit button:

SUBMIT_BUTTON: WOSubmitButton {action = sayHello};

Clicking the submit button sends a request to the HelloWorld application, initiating a cycle of the request-response loop in which sayHello is invoked.

Note: The WOActiveImage, WOHyperlink, and WOForm dynamic elements can also be used to associate action methods to a user action.

Action methods take no arguments and return a page that will be packaged with an HTTP response. For example, the sayHello action method of the HelloWorld example is defined as follows:

- sayHello
{
    id nextPage = [WOApp pageWithName:@"Hello"];
    [nextPage setNameString:nameString];
    return nextPage;
}

As in sayHello, most action methods perform page navigation. It is common for action methods to determine the response page based on user input. For example, the following action method returns an error page if the user has entered an invalid part number (stored in the component variable partnumber) or an inventory summary otherwise:

- showPart {
    id errorPage;
    id inventoryPage;
    
    if ([self isValidPartNumber:partnumber]) {
        errorPage = [[self application] pageWithName:@"Error"];
        [errorPage setErrorMessage:@"Invalid part number %@.", partnumber];
        return errorPage;
    }
    inventoryPage = [[self application] pageWithName:@"Inventory"];
    [inventoryPage setPartNumber:partnumber];

    return inventoryPage;
}

Action methods don't have to return a new page. They can instead direct the application to regenerate the request page. When an action method returns nil, the application uses the request component as the response component.

Note: Returning self in an action method generally has the same effect as returning nil. However, there's a difference when the action method is implemented in a nested component. When a nested component---a component representing only a portion of the request page---returns self in an action, the application attempts to use the nested component to generate the response page. Since the component only represents a portion of a page, returning self is probably an error. Returning nil always has the effect of using the request page---the component representing the whole request page---as the response page. As a result, returning nil is considered to be a better practice than returning self.

In the Visitors example, the request page is also used as the response page. The WebScript recordMe action method records the name of the last visitor and clears the text field:

- recordMe
{  
   if ([aName length]) {
       [[self application] setLastVisitor:aName];  
       [self setAName:@""]; // clear the text field
   }
   return nil;
}

Table of Contents Next Section