pp108 : cordys

cordys

The cordys object provides generic APIs for applications running on multiple browsers.

A number of methods and properties related to HTML and XML manipulations are supported differently by different browsers such as Internet Explorer, FireFox, Chrome, and Safari. An application that uses these Javascript APIs may not be rendered properly or related functionality may not be available for use on all browsers.

To address this issue, wrapper methods are introduced that enable the functionality to work on all browsers. These wrapper methods are defined on the cordys object, which is available for all applications.
The cordys object can be accessed by any application (HTML or XForm). It can also be accessed using the window object through an XForm. The following wrapper methods are available for the cordys object.

Table 1. List of Methods

Method

Corresponding Method Used Earlier

Description

addDOMListener(htmlElement, eventName, handler)

<htmlElement>.attachEvent(<eventName>, <handler>);

Binds the specified function handler to an event specified by eventName so that the function is called whenever the event fires on the HTML element

appendXMLNode(childNode, parentNode)

<xmlNode>.appendChild(<childNode>)

Appends a node as a child to the parent node. The node is always appended as the last child node.

appendXMLNamespaces(xmlDocument, namespaces)

Appends the specified namespaces to existing namespaces for use in XPath expressions in an XML document. Double namespaces, if any, are overwritten. The parameters that can be defined are:

  • xmlDocument: Refers to the document to which the namespaces are to be appended
  • namespaces: Refers to the array of prefixes and namespaces; for example, { ns1: namespace1, ns2: namespace2 }
    Namespaces must be defined in the XML style as a space-separated list of namespace declaration attributes. This can be used to set default namespaces as well. For example, for namespaces { ns1: namespace1, ns2: namespace2 }, the prefixes must not start with xml.

createAttributeNS(xmlDocument, namespaceURI, qualifiedName)

<xmlNode>.createNode(2, <qualifiedName>, <namespaceURI>)

Creates an XML attribute using the specified name and namespace on the scope of the XML document supplied

createElementNS(xmlDocument, namespaceURI, qualifiedName)

<xmlNode>.createNode(1, <qualifiedName>, <namespaceURI>)

Creates an XML element using the specified name and namespace on the scope of the XML document supplied

cloneXMLDocument(xmlDocument)

<xmlDocument>.cloneNode(true)

Creates a copy of the specified XML document

dataTransferGetData(eventObject, sDataFormat)

dataTransfer.getData(sDataFormat)

Retrieves data in the specified format from the clipboard through the dataTransfer or clipboardData objects. The data retrieved can be text, an image, or a URL. The parameters that can be defined are:

  • eventObject: Object that denotes the event that fired the action related to set or get data
  • sDataFormat: String that specifies the format of the data to be transferred

The possible values are:

    • Text: Transfers data that is formatted as text
    • URL: Transfers data formatted as a URL

Note: The values of the sDataFormat parameter are case-sensitive. With the exception of the Internet Explorer browser that expects text, other browsers expect values as provided above.

dataTransferSetData(eventObject, sDataFormat, sData)

dataTransfer.setData(sDataFormat, sData)

Assigns data to the dataTransfer object in a specified format. The parameters that can be defined are:

  • eventObject: Object that denotes the event that fired the action related to set or get data
  • sDataFormat: String that specifies the format of the data to be transferred

The possible values are:

    • Text: Transfers data that is formatted as text
    • URL: Transfers data that is formatted as a URL
    • sData: String that specifies the data supplied by the source object. This information can be descriptive text, a source path to an image, or a URL for an anchor. When you pass URL as the sDataFormat parameter, you must use the sData parameter to provide the location of the object that is transferred.

Note: The values of the sDataFormat parameter are case-sensitive. With the exception of the Internet Explorer browser that expects text, other browsers expect values as provided above.

Returns the following boolean values:

    • true: The data was successfully added.
    • false: The data was not added.

getComputedStyle(htmlElement)

<htmlElement>.currentStyle

Returns the cascaded format and style of the HTML element as specified by global style sheets, inline styles, and HTML attributes. The properties are returned as a JavaScript object; for example, width can be retrieved using getComputedStyle(htmlElement).width.

getConnection()

new ActiveXObject('Microsoft.XMLHTTP') new XMLHttpRequest()

Enables the browser to send and receive HTTP requests (in XML or as text) from the Web server. You can manipulate the response through client-side scripting.

getDOMAttribute(htmlElement, attributeName)

htmlElement.<attributeName>

Returns the attribute present on the HTML element as specified by the attribute name. Use this method when the attribute is set on the HTML and not through JavaScript.

getElementById(htmlElement, id)

<htmlElement>.allID

Searches the HTML element and returns the first control specified by the ID

getElementsById(htmlElement, id)

<htmlElement>.allID

Searches the HTML element and returns an array of controls specified by the ID

getEventTarget(eventObject)

<eventObject>.srcElement

Retrieves the HTML element that fired the event specified by eventObject

getLocalName(node)

node.baseName

Returns the base name of the node qualified with a namespace. If no namespace or prefix exists for the node, it returns the node name. The parameter that can be specified is:

  • node: Denotes the XML node for which the local name is requested.
    The returned value comprises the right-hand-side part of the namespace-qualified name. For example, it returns yyy for the element <xxx:yyy>. The returned value is always a non-empty string.

getNodeText(xmlNode, xpath, defaultValue, namespaces)

Returns the text of the XML node that is selected using the XPath expression. If no XML node is specified, or is not selected, then the default value will be returned.

getPrefix(htmlNode)

<htmlNode>.scopeName

Returns the namespace defined for the HTML node. This method is available for HTML nodes only.

getTextContent(xmlOrHTMLNode)

<xmlNode>.text <htmlElement>.innerText

Returns the text set on the XML or an HTML node.

getXMLDocument()

new ActiveXObject('Microsoft.XMLDOM')

Creates an XMLDocument object. The created XML document can be used for accessing, manipulating, and using the XML.

getXMLNamespaces(xmlDocument)

<xmlDocument>.getProperty('SelectionNamespaces')

Returns the namespaces defined for use in XPath expressions in an XML document. This returns namespaces as follows: { ns1: namespace1, ns2: namespace2 }.

getXML(xmlNode)

<xmlNode>.xml

Returns the XML (string) of a node and its descendants

insertAdjacentHTML(htmlElement, position, unParsedHTMLString)

insertAdjacentHTML()

Inserts a specific HTML text into the specified element at the specified location. The parameters that can be specified are:

  • htmlElement: Denotes the HTML element adjacent to which, the new HTML element is to be added
  • position: Denotes the position, with respect to the htmlElement, where the new HTML element is to be appended. The possible values are:
    • beforeBegin: Inserts unparsedHTMLString immediately before the htmlElement
    • afterBegin: Inserts unparsedHTMLString after the start of the htmlElement but before all other content in the htmlElement
    • beforeEnd: Inserts unparsedHTMLString immediately before the end of the htmlElement but after all other content in the htmlElement
    • afterEnd: Inserts unparsedHTMLString immediately after the htmlElement
  • unparsedHTMLString - String that specifies the XHTML text to be inserted. The string can be a combination of text and HTML tags. It must be well formed, valid HTML or this method will fail.

loadXMLDocument(xmlString, xmlDocument)

<xmlDocument>.loadXML(<xmlstring>)

Loads an XML document from the specified string. The xmlDocument parameter is optional, and when specified, returns an XML document on an existing document.

loadXMLFromURL(sURL)

xmlDocument.load(sURL)

Loads and returns an XML document from the specified URL. The parameter that can be specified is:

  • sURL: String that specifies the URL of the XML document to be loaded

preventDefault(eventObject)

<eventObject>.returnValue = <true/false>

Sets the return value from the event specified by eventObject. By default, the value returned from an event is true, so this method will prevent the default action, thereby returning false, that is returnValue is set as false.

removeDOMListener(element, eventType, handler)

<htmlelement>.detachEvent(<eventname>, <handler>);

Unbinds the specified function handler from the event specified by the event name so that the function stops receiving notifications when the event fires

replaceXMLNode(parentNode, newNode, oldNode)

parentNode.replaceChild(newNode, oldNode);

Replaces a child node with the specified node. The parameters that can be specified are as follows:

  • parentNode: Required. Denotes the parent node of the child node that is to be replaced.
  • newNode: Required. Denotes the new node that must replace the old child node.
  • oldNode: Required. Denotes the old child node that must be replaced.

setNodeText(xmlNode, xpath, value, namespaces)

Tries to set the text of an XML node, and if one is found, will set the text content of that XML node.

setPrefix(htmlNode, prefix)

<htmlNode>.scopeName = prefix

Sets the namespace (prefix) defined for the HTML node. This method is available for HTML nodes only.

stopPropagation(eventObject)

<eventObject>.cancelBubble = <true/false>

Sets whether the current event specified by eventObject must bubble up and apply to events higher up in the hierarchy of event handlers. Calling this method stops propagation of the event handlers thereby cancelling the bubbling that is cancelBubble is set as true.

setTextContent(xmlOrHTMLNode, textContent)

<xmlNode>.text = <value> <htmlElement>.innerText = <value>

Sets the text specified by textContent on the XML or HTML node

setXMLAttribute(xmlNode, attributeNamespace, attributeName, attributeValue)

xmlNode.setAttribute(attributeName, attributeValue)

Sets an attribute on the specific XML node. If the namespace is not provided, it is taken as the default, which is the namespace of the XML node.

setXMLNamespaces(xmlDocument, namespaces)

<xmlDocument>.setProperty('SelectionNamespaces', stringNamespaces)

Sets the specified namespaces for use in XPath expressions on an XML document. This is used to define new namespaces externally. Namespaces must be defined in the XML style as a space-separated list of namespace declaration attributes. This can be used to set default namespaces as well. For example, for namespaces { ns1: namespace1, ns2: namespace2 }, the prefixes must not start with xml.

selectXMLNode(xmlNode, xpathExpression, namespaces)

<xmlNode>.selectSingleNode(xslPatternExpression)

Searches and returns the first XML node that matches the specified XPath expression. The namespaces parameter is optional, and must be an array of prefixes and namespaces. For example, for the namespaces { ns1: namespace1, ns2: namespace2 }, the prefixes must not start with xml.

selectXMLNodes(xmlNode, xpathExpression, namespaces)

<xmlNode>.selectNodes(xslPatternExpression)

Searches and returns a list of XML nodes that match the specified XPath expression. The namespaces parameter is optional and if provided, must be an array of prefixes and namespaces. For example, for the namespaces { ns1: namespace1, ns2: namespace2 }, the prefixes must not start with xml.

transformXMLDocument(xmlDocument, xsltDocument)

<xmlDocument>.transformNode(xsltDocument)

Processes the XML document and its children using the supplied XSL Transformations (XSLT) style sheet and returns the resulting transformation

getButtonTypeFromEvent(eventObject)

Returns the button type pressed in case of mouse events

  • left
  • right
  • middle