WOComponent
Inherits from: WOElement : NSObject
Conforms to: WOActionResults NSObject
(NSObject)
Declared in: WebObjects/WOComponent.h
Class Description
WOComponent objects dynamically render web pages (or sections of pages) at run time. They provide custom navigation and other logic for the page, provide a framework for organizing constituent objects (static and dynamic HTML elements and subcomponents), and enable the attribute bindings of dynamic elements.
The WOComponent class has many methods that have the same names as methods of the WOApplication class. However, the scope of the WOComponent methods is limited to a component rather than being application-wide. For example, you can control component-definition caching on a per-component basis using setCachingEnabled:, which has a WOApplication counterpart. When this kind of caching is enabled for a component, the application parses the contents of the component directory the first time the component is requested, creates the component definition, stores this object in memory, and restores it for subsequent requests.
WOComponent objects also respond to awake, sleep, and the three request-handling messages: takeValuesFromRequest:inContext:, invokeActionForRequest:inContext:,and appendToResponse:inContext:. You can override these methods in your compiled subclasses, and thereby integrate your custom behavior into the request-response loop. (You can also override these methods in component scripts using WebScript.)
Subcomponents
A WOComponent object can represent a dynamic fragment of a Web page as well as an entire page. Such subcomponents, or reusable components, are nested within a parent component representing the page or another subcomponent. Each component keeps track of its parent and subcomponents-when a component receives a request-handling message, such as takeValuesFromRequest:inContext:, it forwards that message to its subcomponents
The WOComponent class also provides a child-parent callback mechanism to allow a child component to communicate with its parent. In the parent's declaration file, bind an arbitrary attribute of the child to an action method of the parent. Then, as the last step in the child's action method, invoke performParentAction: with the argument being the arbitrary attribute, returning the object received back as the response page. See the method description for performParentAction: for details.
Stateless Components
For extra efficiency, you can create stateless components: components that can be shared between sessions. Stateless components aren't replicated each time they're needed; rather, a single shared instance is referenced each time the component is used.
Stateless components cannot have state. They can have instance variables, but the variable's content must be transient. To ensure that when the shared instance of a component is reused by another session there are no side effects, reset your component's instance variables by implementing the reset method. In your implementation of reset , release and set to nil each instance variable. Note that a stateless component's instance variables will remain valid for the duration of the phase (takeValuesFromRequest, invokeAction and appendToResponse); this lets you use instance variables in your stateless components to hold things analgous to items in a WORepetition.
Stateless components primarily save memory, but they can significantly speed up your application as well depending on how many stateless components you use in your application. To make a component stateless, override the component's isStateless method so that it returns YES.
If a stateless component is needed simultaneously in separate threads, additional instances of the component are created (and later discarded) as necessary to prevent conflicts. Thus, the number of threads in which a component could be used determines the maximum number of instances of a stateless component that may be allocated at any given time.
Adopted Protocols
WOActionResultsgenerateResponse NSCoding- encodeWithCoder: - initWithCoder: NSCopying- copy - copyWithZone:
Method Types
- Creation
- - init
- Obtaining attributes
- - application
- - baseURL
- - context
- - frameworkName
- - hasSession
- - name
- - pageWithName:
- - path
- - session
- Caching
- - isCachingEnabled
- - setCachingEnabled:
- Handling requests
- - appendToResponse:inContext:
- - awake
- - ensureAwakeInContext:
- - invokeActionForRequest:inContext:
- - sleep
- - takeValuesFromRequest:inContext:
- Logging
- - debugWithFormat:
- - isEventLoggingEnabled
- - logWithFormat:
- - logWithFormat:arguments:
- Template parsing
- + templateWithHTMLString:declarationString:languages:
- Component statistics
- - descriptionForResponse:inContext:
- Invoking actions
- - parent
- - performParentAction:
- Synchronizing components
- - canGetValueForBinding:
- - canSetValueForBinding:
- - hasBinding:
- - setValue:forBinding:
- - synchronizesVariablesWithBindings
- - valueForBinding:
- Other
- - isStateless
- - reset
- - templateWithName:
Class Methods
templateWithHTMLString:declarationString:languages:
+ (WOElement *)templateWithHTMLString:(NSString
*)anHTMLString
declarationString:(NSString *)aDeclarationString
languages:(NSArray*)languages
See Also: - templateWithName:
Instance Methods
appendToResponse:inContext:
- (void)appendToResponse:(WOResponse
*)aResponse
inContext:(WOContext *)aContext
See Also: - invokeActionForRequest:inContext:, - takeValuesFromRequest:inContext:
application
- (WOApplication *)application
See Also: WOApplication class, - context, - session
awake
- (void)awake
See Also: - ensureAwakeInContext:, - init, - sleep
baseURL
- (NSString *)baseURL
canGetValueForBinding:
- (BOOL)canGetValueForBinding:(NSString
*)aBindingName
See Also: - canSetValueForBinding:, - hasBinding:, - valueForBinding:
canSetValueForBinding:
- (BOOL)canSetValueForBinding:(NSString
*)aBindingName
See Also: - canGetValueForBinding:, - hasBinding:, - setValue:forBinding:
context
- (WOContext *)context
See Also: WOContext class, - application, - session
debugWithFormat:
- (void)debugWithFormat:(NSString
*)aFormatString,...
See Also: - logWithFormat:arguments:
descriptionForResponse:inContext:
- (NSString *)descriptionForResponse:(WOResponse
*)aResponse
inContext:(WOContext *)aContext
This message is sent only to the top-level response component, that is, the one representing the entire page. Components nested inside of that top-level component do not receive this message.
If a CLFF log file is kept for this application, the string returned by this method is recorded in that log file. Thus, you must ensure that the string you return can be analyzed by a CLFF-analysis tool.
See Also: WOStatisticsStore class
ensureAwakeInContext:
- (void)ensureAwakeInContext:(WOContext
*)aContext
Ensures that the receiver is awake in the specified context. Invoke this method before using a component which was stored in a variable. You don't need to invoke ensureAwakeInContext: if the component was just created with pageWithName:, if it was restored from the WebObjects page cache, or if the page will simply be returned as the result of an action. That is, you only need to invoke this method if you're going to send messages to a component that is otherwise not awakened. If the receiving component is already awake, this method has no effect.
See Also: - awake
frameworkName
- (NSString *)frameworkName
If the component is not stored in a framework, this method returns nil.
See Also: WOResourceManager class
generateResponse
- (WOResponse *)generateResponse
See Also: - generateResponse (WOResponse)
hasBinding:
- (BOOL)hasBinding:(NSString
*)aBindingName
See Also: - canGetValueForBinding:, - canSetValueForBinding:
hasSession
- (BOOL)hasSession
See Also: - session
init
- (id)init
See Also: - awake
invokeActionForRequest:inContext:
- (WOElement *)invokeActionForRequest:(WORequest
*)aRequest
inContext:(WOContext *)aContext
See Also: - appendToResponse:inContext:, - takeValuesFromRequest:inContext:
isCachingEnabled
- (BOOL)isCachingEnabled
See Also: - setCachingEnabled:
isEventLoggingEnabled
- (BOOL)isEventLoggingEnabled
Called to determine if a component wants event logging. This is not desirable, for example, for components which are associated with event display as they would interfere with the actual event logging. The default implementation of this method returns YES.
See Also: WOEvent class
isStateless
- (BOOL)isStateless
By default, this method returns NO, indicating that state will be maintained for instances of the receiver. Overriding this method to return YES will make the component stateless. A single instance of each stateless component is shared between multiple sessions, reducing your application's memory footprint.
See Also: - reset
logWithFormat:
- (void)logWithFormat:(NSString
*)aFormat,...
id i = 500; id f = 2.045; [self logWithFormat:@"Amount = %@, Rate = %@, Total = %@", i, f, i*f];
Note that in WebScript, all variables are objects, so the only conversion specifier allowed is %@ as shown above. In compiled Objective-C code, all printf conversion specifiers are allowed. The equivalent method in Java is logString.
logWithFormat:arguments:
- (void)logWithFormat:(NSString
*)aFormat
arguments:(va_list)someArguments
name
- (NSString *)name
pageWithName:
- (WOComponent *)pageWithName:(NSString
*)aName
See Also: - restorePageForContextID: (WOSession), - savePage: (WOSession)
parent
- (WOComponent *)parent
path
- (NSString *)path
performParentAction:
- (id)performParentAction:(NSString
*)anActionName
An example best illustrates this mechanism. Let's say you have a Palette subcomponent, and this WOComponent is nested in a parent component with a "displaySelection" action method. When the user selects an item in the palette (perhaps a color), you want to invoke "displaySelection" to show the result of the new selection (perhaps a car in the new color). The declaration in the parent's ".wod" file would look like this:
PALETTE: Palette { selection = number; callBack = "displaySelection"; };
The "callBack" item is an arbitrary attribute of the child component bound in this declaration to the parent component's "displaySelection" method.The performParentAction: method is used to activate this binding. Let's assume the child component has an action method called "click"; the implementation would look like this:
- click { /* this is the child's action */ selection = /* some value */; /* now invoke the parent's action */ return [self performParentAction:callBack]; }
reset
- (void)reset
This method-which is only invoked if the component is stateless-allows a component instance to reset or delete temporary references to objects that are specific to a given context. To ensure that when the shared instance of a component is reused by another session there are no side effects, implement this method so that it releases and sets to nil each of the component's instance variables.
See Also: - isStateless
session
- (WOSession *)session
See Also: WOSession class, - application, - context, - hasSession
setCachingEnabled:
- (void)setCachingEnabled:(BOOL)flag
With WOApplication's method of the same name, you can turn component-definition caching off globally. You can then control caching of individual component definitions using WOComponent's version of this method. Selective caching is an especially valuable technique for very large applications where only the most frequently requested components should be cached.
See Also: - isCachingEnabled
setValue:forBinding:
- (void)setValue:(id)aValue
forBinding:(NSString *)aBindingName
See Also: - isValueSettableInComponent: ( WOAssociation class)
sleep
- (void)sleep
synchronizesVariablesWithBindings
- (BOOL)synchronizesVariablesWithBindings
See Also: - setValue:forBinding:, - valueForBinding:
takeValuesFromRequest:inContext:
- (void)takeValuesFromRequest:(WORequest
*)aRequest
inContext:(WOContext *)aContext
See Also: - appendToResponse:inContext:, - invokeActionForRequest:inContext:
templateWithName:
- (WOElement *)templateWithName:(NSString
*)aName
See Also: - setCachingEnabled:
validationFailedWithException:value:keyPath:
- (void)validationFailedWithException:(NSException
*)exception
value:(id)value
keyPath:(NSString *)keyPath
valueForBinding:
- (id)valueForBinding:(NSString
*)aBindingName
See Also: - canGetValueForBinding:, - setValue:forBinding:, - synchronizesVariablesWithBindings