---

WebScripting Protocol Reference

(informal protocol)

Overview

WebScripting is an informal protocol that defines methods that classes can implement to expose their interfaces to a WebScript environment such as JavaScript.

A method is valid for export if its return type and all its arguments are Objective-C objects or scalars. If your class conforms to this protocol, all of its methods which meet those export criteria are immediately reflected in the scripting environment. If you want to further restrict this behavior—to limit the availability of a method to JavaScript, for example—you can do so using the class methods defined below.

Method argument and return types will be converted to appropriate types for the scripting environment. For example:

• NSNumber objects will be converted to JavaScript numbers.

• NSString objects will be converted to JavaScript strings.

• NSArray objects will be mapped to special read-only arrays.

• NSNull will be converted to JavaScript’s null.

• WebUndefined will be converted to undefined.

• WebScriptObject instances will be unwrapped for the scripting environment.

Instances of all other classes will be wrapped before being passed to the script, and unwrapped as they return to Objective-C.

Access to an object’s attributes, such as instance variables, is managed by key-value coding (KVC). The KVC methods setValue:forKey: and valueForKey: are used to access the attributes of an object from the scripting environment. Additionally, the scripting environment can attempt any number of attribute requests or method invocations that are not exposed by your class. You can manage these requests by overriding the setValue:forUndefinedKey: and valueForUndefinedKey: methods from the key-value coding protocol.

Exceptions can be raised from the scripting environment by sending a throwException: message to the relevant WebScriptObject instance. The method raising the exception must be within the scope of the script invocation.

Tasks

Getting Attributes

• + webScriptNameForKey:
• + webScriptNameForSelector:
• + isSelectorExcludedFromWebScript:
• + isKeyExcludedFromWebScript:

Invoking Methods

• – invokeDefaultMethodWithArguments:
• – invokeUndefinedMethodFromWebScript:withArguments:

Finalizing

• – finalizeForWebScript

Class Methods

isKeyExcludedFromWebScript:

Returns whether a key should be hidden from the scripting environment.

+ (BOOL)isKeyExcludedFromWebScript:(const char *)name

Discussion

This method should return YES to hide the attribute specified by name from the scripting environment, or NO to expose it.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebScriptObject.h

isSelectorExcludedFromWebScript:

Returns whether a selector should be hidden from the scripting environment.

+ (BOOL)isSelectorExcludedFromWebScript:(SEL)aSelector

Discussion

This method should return YES to hide the selector specified by aSelector from the scripting environment, or NO to expose it. If you do not implement this method, all selectors that match the export criteria will be exposed.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebScriptObject.h

webScriptNameForKey:

Returns the scripting environment name for an attribute specified by key.

+ (NSString *)webScriptNameForKey:(const char *)name

Discussion

This method returns the name in the scripting environment to represent the attribute specified by name.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebScriptObject.h

webScriptNameForSelector:

Returns the scripting environment name for a selector.

+ (NSString *)webScriptNameForSelector:(SEL)aSelector

Discussion

This method returns the name to be used in the scripting environment for the selector specified by aSelector. It is your responsibility to ensure that the returned name is unique to the script invoking this method. If this method returns nil or you do not implement it, the default name for the selector will be constructed as follows:

• Any colon (“:”)in the Objective-C selector is replaced by an underscore (“_”).

• Any underscore in the Objective-C selector is prefixed with a dollar sign (“$”).

• Any dollar sign in the Objective-C selector is prefixed with another dollar sign.

The following table shows examples of how the default name is constructed:

Since the default construction for a method name can be confusing depending on its Objective-C name, developers are advised to implement this method and return a more human-readable name.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebScriptObject.h

Instance Methods

finalizeForWebScript

Performs cleanup when the scripting environment is reset.

- (void)finalizeForWebScript

Discussion

This method is invoked on objects exposed to the scripting environment just before the scripting environment is reset. After invocation, the receiving object will no longer be referenced by the scripting environment. Further references to WebScriptObject instances created by the exposed object will be invalid and may produce unpredictable results.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebScriptObject.h

invokeDefaultMethodWithArguments:

Invoked when a script attempts to invoke a method on an exposed object directly.

- (id)invokeDefaultMethodWithArguments:(NSArray *)args

Discussion

You should implement this method to return the result of invoking the default method passing the arguments specified by args.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebScriptObject.h

invokeUndefinedMethodFromWebScript:withArguments:

Handles undefined method invocation from the scripting environment.

- (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)args

Discussion

This method is invoked when a script attempts to invoke a method not directly exposed to the scripting environment. The script attempted to invoke the method specified by name with arguments specified by args. You should return the result of the invocation, converted appropriately for the scripting environment.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebScriptObject.h

---