WebScripting Protocol Reference
(informal protocol)
| Framework | /System/Library/Frameworks/WebKit.framework |
| Availability | Available in OS X v10.3.9 and later. |
| Companion guide | |
| Declared in | WebScriptObject.h |
Overview
WebScripting is an informal protocol that defines methods that classes can implement to export their interfaces to a WebScript environment such as JavaScript.
Not all properties and methods are exported to JavaScript by default. The object needs to implement the class methods described below to specify the properties and methods to export. Furthermore, a method is not exported if its return type and all its parameters are not Objective-C objects or scalars.
Method argument and return types that are Objective-C objects will be converted to appropriate types for the scripting environment. For example:
nilis converted to undefined.NSNumberobjects will be converted to JavaScript numbers.NSStringobjects will be converted to JavaScript strings.NSArrayobjects will be mapped to special read-only arrays.-
NSNullwill be converted to JavaScript’snull. WebUndefinedwill be converted to undefined.WebScriptObjectinstances 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. Primitive types such as int and char are cast to a numeric in JavaScript.
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 exported 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
Finalizing
Class Methods
isKeyExcludedFromWebScript:
Returns whether a key should be hidden from the scripting environment.
Parameters
- name
The name of the attribute.
Return Value
YES if the attribute specified by name should be hidden from the scripting environment; otherwise, NO.
Discussion
The default value is YES.
Availability
- Available in OS X v10.3.9 and later.
Declared In
WebScriptObject.hisSelectorExcludedFromWebScript:
Returns whether a selector should be hidden from the scripting environment.
Parameters
- aSelector
The selector.
Return Value
YES if the selector specified by aSelector should be hidden from the scripting environment; otherwise, NO.
Discussion
Only methods with valid parameters and return types are exported to the WebKit JavaScript environment. The valid types are Objective-C objects and scalars. The default value is YES.
Availability
- Available in OS X v10.3.9 and later.
Declared In
WebScriptObject.hwebScriptNameForKey:
Returns the scripting environment name for an attribute specified by a key.
Parameters
- name
The name of the attribute.
Return Value
The name used to represent the attribute in the scripting environment.
Availability
- Available in OS X v10.3.9 and later.
Declared In
WebScriptObject.hwebScriptNameForSelector:
Returns the scripting environment name for a selector.
Parameters
- aSelector
The selector.
Return Value
The name used to represent the selector in the scripting environment.
Discussion
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 is constructed as follows:
A colon (“:”) in the Objective-C selector is replaced by an underscore (“_”).
An underscore in the Objective-C selector is prefixed with a dollar sign (“$”).
A 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:
Objective-C selector | Default script name for selector |
|---|---|
|
|
|
|
|
|
|
|
Since the default construction for a method name can be confusing depending on its Objective-C name, you should implement this method and return a more human-readable name.
Availability
- Available in OS X v10.3.9 and later.
Declared In
WebScriptObject.hInstance Methods
finalizeForWebScript
Performs cleanup when the scripting environment is reset.
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 OS X v10.3.9 and later.
Declared In
WebScriptObject.hinvokeDefaultMethodWithArguments:
Executes when a script attempts to invoke a method on an exposed object directly.
Parameters
- args
The arguments to be passed to the default method.
Return Value
The result of invoking the default method.
Availability
- Available in OS X v10.3.9 and later.
Declared In
WebScriptObject.hinvokeUndefinedMethodFromWebScript:withArguments:
Handles undefined method invocation from the scripting environment.
Parameters
- name
The name of the undefined method.
- args
The arguments passed to the undefined method.
Return Value
The result of invoking the undefined method.
Discussion
This method is invoked when a script attempts to invoke a method not directly exported to the scripting environment. You should return the result of the invocation, converted appropriately for the scripting environment.
Availability
- Available in OS X v10.3.9 and later.
Declared In
WebScriptObject.h© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-02-24)