Browser host implementation of host-specific functions. This module provides functions to generate web content for accessors. It relies on the /common/commonHost.js module, which it loads when needed.
To generate an interactive instance of an accessor, where you can provide input and parameter values into entry boxes and cause the accessor to react, Include in the head section of your web page the following:
<script src="/accessors/hosts/browser/browser.js"></script>In the body of a web page, you can instantiate an accessor by creating an HTML element with class "accessor" and specifying a source, which is the fully qualified accessor name. For example:
<div class="accessor" src="net/REST" id="REST"></div>The id attribute can have whatever value you like, but it must be unique on the web page.
You can also create a directory of accessors by including in your document an element with class "accessorDirectory". For example:
<div class="accessorDirectory"></div>This will provide a hierarchical expandable list of accessors that this host can instantiate. In addition, if your document has an element with id equal to "accessorDirectoryTarget", then clicking on an accessor in the directory will cause that target to be filled with an instance of the accessor, similar to the one above with class "accessor". For example,
<div class="accessorDirectoryTarget"></div>The style of the generated web pages can be customized using CSS. A default style is achieved by including in the head section of your document the following:
<link rel="stylesheet" type="text/css" href="/accessors/hosts/browser/accessorStyle.css">The main entry point to this module is the generate() function, which is invoked when the web page DOM content has been loaded.
- Version:
- $$Id$$
- Source:
Methods
(inner) appendDoc(target, label, content)
Local function controlling how standard elements are rendered in the document with an optional label.
Parameters:
| Name | Type | Description |
|---|---|---|
target |
The target document element id. |
|
label |
The label, or null to not have a label. |
|
content |
The content. |
(inner) appendPlaceholder(target, id, element)
Local function to add a placeholder to later populate.
Parameters:
| Name | Type | Description |
|---|---|---|
target |
The target document element id. |
|
id |
The id for the placeholder. |
|
element |
The element type (e.g. 'div', 'pp', or 'span'). |
Returns:
The placeholder element.
(inner) generate()
Populate the current page by searching for elements with class 'accessor' and attribute 'src', generating HTML for the specified accessor, and inserting that HTML content into the element. Also search for elements with class 'accessorDirectory' and insert an accessory directory.
(inner) generateAccessorCodeElement(code, id)
Generate a button that will optionally reveal the accessor source code.
Parameters:
| Name | Type | Description |
|---|---|---|
code |
The code. |
|
id |
The ID of the accessor. |
(inner) generateAccessorDirectory(element)
Generate a directory of accessors and place into the specified page element. If the document has an element with id equal to "accessorDirectoryTarget", then clicking on an accessor in the directory will cause that target to be filled with the accessor HTML.
Parameters:
| Name | Type | Description |
|---|---|---|
element |
The document element into which to place the directory. |
(inner) generateAccessorDocumentation(path, id)
Generate documentation for the accessor. This looks for a a PtDoc file for the accessor, then it uses that to build a documentation data structure.
Parameters:
| Name | Type | Description |
|---|---|---|
path |
The fully qualified class name of the accessor. |
|
id |
The id of the accessor. |
(inner) generateAccessorHTML(id, text)
Generate HTML for an accessor defined at the specified path. If the path is relative (does not begin with '/' or './'), then the accessor specification will be loaded from the accessor library stored on the host. If the path is absolute (beginning with '/'), then the accessor specification will be loaded from the web server providing this swarmlet host at that path. If the accessor has no inputs, then it will be initialized and fired. Otherwise, a 'react to inputs' button will appear that will initialize and fire the actor on command.
As a side effect of invoking this, the window object for the web page
acquires a field accessors with a property whose name equals the
id argument whose value is the provided accessor
instance with some additional utilities to support the web page.
If there was a previously generated accessor with this same id, and it has has been initialized, then this function will invoke its wrapup() function, if it defines one, before generating the HTML. It will also clear the target element (which has the same id as the accessor).
Optionally, this method can accept the full text of an accessor via the text parameter. This is used to create accessors on-the-fly. The tutorial instantiates accessors this way.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
The id of the accessor, which is also the id of the target element on the web page into which to insert the generated HTML. |
|
text |
(Optional) The text of the accessor, to be used instead of retrieving an accessor from the filesystem. |
(inner) generateListOfContainedAccessors(instance, id)
Generate a list of accessors contained by the specified accessor instance.
Parameters:
| Name | Type | Description |
|---|---|---|
instance |
An accessor instance created by common/commonHost.js. |
|
id |
The id of the accessor. |
(inner) generateReactButton(id)
Generate a react button.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
The id of the accessor. |
(inner) generateTable(title, names, contents, role, id)
Generate a table with the specified title and contents and append it to the element on the page with the specified id.
Parameters:
| Name | Type | Description |
|---|---|---|
title |
The title for the table. |
|
names |
A list of field names in the contents object to include, in order. |
|
contents |
An object containing one field for each object to include. |
|
role |
One of 'input', 'output', or 'parameter'. |
|
id |
The id of the accessor. |
(inner) generateTableRow(table, name, id, options, editable, visible, role)
Generate a table row for an input, parameter, or output. Table rows are still created for invisible items so that the content is available when the accessor is fired. Invisible rows are tagged with the class "invisible" to instruct the CSS formatter not to show the row.
Parameters:
| Name | Type | Description |
|---|---|---|
table |
The element into which to append the row. |
|
name |
The text to put in the name column. |
|
id |
The id of the accessor. |
|
options |
The options. |
|
editable |
True to make the value an editable input element. |
|
visible |
True to make the table row visible. |
|
role |
Can be parameter, input or output. |
(inner) generateTables(accessor, id)
Generate parameter, input, and output tables for the specified accessor instance and insert it into the element on the page with the specified id. Also generate a list of contained accessors, if there are any.
Parameters:
| Name | Type | Description |
|---|---|---|
accessor |
An accessor instance created by common/commonHost.js. |
|
id |
The id of the accessor. |
(inner) getAccessorCode(path)
Return the text of an accessor definition from the accessor library on the host. This implementation appends the string '.js' to the specified path (if it is not already there) and retrieves from the server's accessor repository the text of the accessor specification. This is a blocking call.
Parameters:
| Name | Type | Description |
|---|---|---|
path |
The path on the server for the JavaScript code, e.g. 'net/REST'. |
(inner) getBaseDocumentation(docs, path)
Get default documentation from a base accessor or implemented interface. This ignores description, author, and version fields of the base documentation.
Parameters:
| Name | Type | Description |
|---|---|---|
docs |
The data structure to populate with documentation. |
|
path |
The path of the base accessor or interface. |
(inner) getHostName()
Return the name of this host.
Return the string "Browser".
Returns:
In browser.js, return "Browser".
(inner) getIndex(baseDirectory, docElement, indent)
Fetch the top-level index.json file and puts its contents in the specified docElement. This function will be invoked recursively to populate subdirectories.
Parameters:
| Name | Type | Description |
|---|---|---|
baseDirectory |
The directory to fetch; for example, net for the net/REST accessor. |
|
docElement |
The HTML document element to add content to. |
|
indent |
The amount of left indentation, in pixels. |
(inner) getInputOrParameter(name, role, id)
Get data from an input or parameter. This is used by get() and getParameter().
Parameters:
| Name | Type | Description |
|---|---|---|
name |
The name of the input (a string). |
|
role |
One of 'input' or 'parameter'. |
|
id |
The id of the accessor. |
Returns:
The value received on the input, or null if no value is received.
(inner) getJavaScript(path, callback, module)
Return the source code of an accessor or module definition. This implementation appends the string '.js' to the specified path (if it is not already there) and issues an HTTP GET with the specified path. If the path begins with '/' or './', then it is used as is. Otherwise, depending on the third argument, it is prepended with the location of the directory in which accessors are stored ('/accessors' on this host) or the directory in which modules are stored ('/accessors/hosts/browser/modules' on this host).
If no callback function is given, then this is a blocking request. It will not return until it has the text, and then will return that text. If a callback is given, then this will issue the HTTP get and return, and then later invoke the callback when the response has been completely received. The callback function will be passed two argument: an error string (or null if no error occurred) and the text of the response (or null if an error occurred).
Parameters:
| Name | Type | Description |
|---|---|---|
path |
The path on the server for the JavaScript code. |
|
callback |
The callback function. |
|
module |
True to look in the modules directory for paths that do not begin with '/' or './'. False (or omitted) to look in '/accessors'. |
(inner) initializeIfNecessary(instance)
Initialize the specified accessor instance if it has not been initialized and its exports object has an initialize function.
Parameters:
| Name | Type | Description |
|---|---|---|
instance |
The instance. |
(inner) normalizePath(path)
Normalize the specified accessor path by removing any trailing '.js' and prepending, if necessary, with '/accessors/'.
Parameters:
| Name | Type | Description |
|---|---|---|
path |
The path to normalize. |
(inner) provideInput(id, name, value)
Provide an input to the accessor with the specified id.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
The id of the accessor. |
|
name |
The name of the input. |
|
value |
The value to provide. |
(inner) reactIfExecutable(id, suppress)
If the accessor is marked executable, then invoke its react() function. If it has not been previously initialized, then initialize it first. Otherwise, provide a message that the accessor is not executable, unless that message is suppressed by the second argument.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
The accessor ID. |
|
suppress |
True to suppress the 'not executable' message. |
(inner) setParameter(id, name, value)
Set a parameter of the accessor with the specified id.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
The id of the accessor. |
|
name |
The name of the input. |
|
value |
The value to provide. |
(inner) toggleVisibility(id, indent, getIndex)
Toggle the visibility of an element on the web page. If the element is empty, then populate it from the directory.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
The id of the element. |
|
indent |
The amount by which to indent the contents. |
|
getIndex |
A function that will populate a specified element with an index of accessors. |