Mac Developer Library

Developer

WebKit Framework Reference WebScripting Protocol Reference

Options
Deployment Target:

On This Page
Language:

WebScripting

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import WebKit

Objective-C

@import WebKit;

Availability


Available in OS X v10.3.9 and later.

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:

  • nil is converted to undefined.

  • 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. 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.

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

    Declaration

    Swift

    class func webScriptNameForKey(_ name: UnsafePointer<Int8>) -> String!

    Objective-C

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

    Parameters

    name

    The name of the attribute.

    Return Value

    The name used to represent the attribute in the scripting environment.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

    Available in OS X v10.3.9 and later.

  • Returns the scripting environment name for a selector.

    Declaration

    Swift

    class func webScriptNameForSelector(_ aSelector: Selector) -> String!

    Objective-C

    + (NSString *)webScriptNameForSelector:(SEL)aSelector

    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

    setFlag:

    setFlag_

    setFlag:forKey:withAttributes:

    setFlag_forKey_withAttributes_

    propertiesForExample_Object:

    propertiesForExample$_Object_

    set_$_forKey:withDictionary:

    set$_$$_$_forKey_withDictionary_

    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.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

    Available in OS X v10.3.9 and later.

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

    Declaration

    Swift

    class func isSelectorExcludedFromWebScript(_ aSelector: Selector) -> Bool

    Objective-C

    + (BOOL)isSelectorExcludedFromWebScript:(SEL)aSelector

    Parameters

    aSelector

    The selector.

    Return Value

    YEStrue if the selector specified by aSelector should be hidden from the scripting environment; otherwise, NOfalse.

    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 YEStrue.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

    Available in OS X v10.3.9 and later.

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

    Declaration

    Swift

    class func isKeyExcludedFromWebScript(_ name: UnsafePointer<Int8>) -> Bool

    Objective-C

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

    Parameters

    name

    The name of the attribute.

    Return Value

    YEStrue if the attribute specified by name should be hidden from the scripting environment; otherwise, NOfalse.

    Discussion

    The default value is YEStrue.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

    Available in OS X v10.3.9 and later.

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

    Declaration

    Swift

    func invokeDefaultMethodWithArguments(_ args: [AnyObject]!) -> AnyObject!

    Objective-C

    - (id)invokeDefaultMethodWithArguments:(NSArray *)args

    Parameters

    args

    The arguments to be passed to the default method.

    Return Value

    The result of invoking the default method.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

    Available in OS X v10.3.9 and later.

  • Handles undefined method invocation from the scripting environment.

    Declaration

    Swift

    func invokeUndefinedMethodFromWebScript(_ name: String!, withArguments args: [AnyObject]!) -> AnyObject!

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

    Available in OS X v10.3.9 and later.

  • Performs cleanup when the scripting environment is reset.

    Declaration

    Swift

    func finalizeForWebScript()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

    Available in OS X v10.3.9 and later.