- Index

< Previous |  | Next >

# LiveView JavaScript Client API

The LiveView JavaScript API focuses on simplicity, conformity to common JavaScript patterns, compatibility with modern JavaScript frameworks, and detailed documentation.

Full JavaScript Client API Documentation is incorporated into the LiveView documentation set. JavaScript API documentation is also embedded in every running LiveView Server at the path `/lv/api`. For example: `http://localhost:10080/lv/api`

## JavaScript Client API Samples

The JavaScript Client API is illustrated in the Creating web applications with JavaScript sample shipped with LiveView. To load this sample in StreamBase Studio:

1. Select File → Load StreamBase Sample from Studio's top-level menu.

2. Enter `javasc` in the filter field to narrow the selection.

3. Select the sample whose description is `Creating web applications with JavaScript` from the TIBCO LiveView category.

4. Click OK.

Follow the instructions in the sample's README.txt file to run the sample project as a LiveView Project. Then open one of the following URLs in a web browser on the same machine:

`http://localhost:10080/simple`
`http://localhost:10080/query-runner`
`http://localhost:10080/dashboard`
`http://localhost:10080/ipad`

If available, open this last URL from a browser on an iPad, using the network name of the current machine instead of `localhost`. For example:

`http://graemsay.local:10080/ipad`

## General Architecture

Control commands (such as connect, subscribe, addAlertRule, and so on) use Promises to simplify handling of asynchronous calls to the server. For those who would prefer to not use Promises, onSuccess and onError callback functions are also available for control commands. Rather than polling the LiveView Server for updates, the API uses WebSockets to receive data pushed by the server. Data received on the WebSocket is communicated via registered callback functions, specified when subscribing to a query, as described below.

## Accessing the JavaScript API

The API is packaged in a single, minified script file. Inclusion of this file (plus the two required third-party libraries) is all that is required. Including the API looks like the following:

    <script src="/lv-web/api/lib/jquery.min.js"></script>
    <script src="/lv-web/api/lib/atmosphere.min.js"></script>
    <script src="/lv-web/api/liveview.min.js"></script>

## Connecting

You call LiveView.connect and pass an object parameter that defines URL, username, and password. When the connection has been established, the Promise returned by connect will resolve and the connection is passed to the promise resolution handler. With this connection, you can issue server commands (running queries, adding alert rules, and so on). If using callbacks, the onSuccess function is invoked upon successful connection and the same connection object is passed to it.

## Running Queries

You call subscribe on an active connection object, passing callbacks for query events of interest (such as onSnapshotStart, onSnapshotEnd, onInsert, onUpdate, and onDelete). When an event occurs for the query, the corresponding callback function is invoked, and appropriate data is passed as an argument. The subscribe function is a server command that returns a Promise. Upon successful subscription to the query, the Promise resolves, and the resolution handler is passed a QuerySubscription object that the user can then use to later reference and update the running query.

## Third Party Requirements

The API requires jQuery and jQuery Atmosphere.