RDB2JS

2nd generation RdbHost JavaScript library.
Use SQL from your browser, for the smoothest easiest possible client-app development process.
The library can be loaded with a script tag, like:

<script src="https://www.rdbhost.com/vendor/rdbhost/2.3/lib/js/util-bundle;rdbhost.js"></script>

but other libraries, including polyfills, will often need to be loaded as well.
I recommend you use Lab.Js to load all modules, with a code block like:

<script type="text/javascript" src="https://www.rdbhost.com/vendor/rdbhost/2.3/vendor/labjs/LAB.js"></script>
<script>
    var $L = $LAB
        .script('https://www.rdbhost.com/vendor/rdbhost/2.3/lib/js/util-bundle;rdbhost.js')
        .script('https://www.rdbhost.com/vendor/rdbhost/2.3/lib/js/rdbhost_livereload.js');

    if (!Rdbhost.featuredetects.hasPromises())
        $L = $L.script('https://www.rdbhost.com/vendor/rdbhost/2.3/vendor/es6-promises/dist/es6-promise.js');

    if (!Rdbhost.featuredetects.hasFetch())
        $L = $L.script('https://www.rdbhost.com/vendor/rdbhost/2.3/vendor/fetch/fetch.js').wait();
        $L.script('your_app.js');
</script>

This loads the RdbHost library and conditionally the necessary polyfills. hasPromises and hasFetch detect whether Promise and fetch are available already. Lab.js loads the libraries asynchronously and in parallel, for fastest load time.

Connect

Before making any request objects, you should call the connect method.

Rdbhost.connect('www.rdbhost.com', <acct_number> [, template_path])

The optional template_path parameter provides a url where custom templates are to be found, if you need custom templates.

Request Objects

There are four request object constructors, one for each role, and named for the roles: preauth, super, auth, and reader. Most web apps will need super and preauth; if you do your setup with RdbAdmin, you may only need preauth.

var req = Rdbhost.preauth();

The super and auth constructors take an optional authcode parameter, for testing purposes.

Request Methods

Each request object, regardless of which constructor you use, will have these methods. Most of these methods return the request object this, allowing methods to be chained.

  • query(sql) provides the sql query to the request. returns this
  • params(args, namedParams) provides args (a list of values) or namedParams (a dictionary of names and values) to the request. Can take either type of parameter, or one of each. Can be called without parameters to clear any data from request. returns this
  • form_data(formData) provides a FormData object to the request. Cannot be used with params in same request. FormData objects contain field data to submit to server. Any query (q) in the FormData will be overwritten by the query provided in query method. returns this
  • proxy(mode) if a mode other than data query is needed, this method sets the mode. Possible modes are 'email', 'credit', and 'proxy'. returns this
  • repeat(ct) if query is to be done repeatedly in the same request, this method records the repeat count. returns this
  • clone() returns a copy of the request, complete with all above options. Each request can only be submitted once, but can be cloned and each clone submitted once. returns new request
  • listen(channel) listen([channel1, channel2, ...]) wraps the query sql in additional sql that catches any NOTIFYs that get emitted by the query. It is also part of registering this client to recieve all NOTIFYs payloads on the given channel. Once this client is registered, it will receive all NOTIFY payloads on that channel from any connection by any client. Parameter can be string or list of strings. returns this
  • broadcast(channel, message) adds to the query, additional sql that uses NOTIFY to emit a message on a channel. This must be used with .listen() method to catch the messages emitted. When the client does catch a message, it is registered on that channel, for all messages emitted on the channel in the account for the life of the connection. returns this
  • get_data() submits the request to the server, and returns a Promise for the results. This method applies whether results are expected or not. returns Promise

If a super request was made without providing the authcode, then the request processing will ask the user for the login email and password, connect to the server for the authcode, and continue with the request query.

If a preauth request gets an error from the server, then it presents the user a form for login email and password, and connects to the server to get the authcode, and again to add the preauth query to the whitelist and execute it.

In either case, the authcode is cached in the client once retrieved.

A Simple Example:

var prom = Rdbhost.preauth()
       	.query('SELECT name, address FROM contacts;')
        .get_data();

prom.then(function(data) {
		// do something with data
	})
	.catch(function(error) {
		// error will be a JavaScript Error
	});
				

A Simple Example with Arguments:

var prom = Rdbhost.preauth()
        .query('SELECT name, address FROM contacts WHERE id = %s;')
        .params([220])
        .get_data();

prom.then(function(data) {
		// do something with data
	})
	.catch(function(error) {
		// error will be a JavaScript Error
	});
				

A Simple Example with Named Parameters:

var prom = Rdbhost.preauth()
    	.query('SELECT name, address FROM contacts WHERE id = %(employee_id)s;')
        .params({employee_id: 220})
    	.get_data();

prom.then(function(data) {
		// do something with data
	})
	.catch(function(error) {
		// error will be a JavaScript Error
	});
				

A Simple Example with both:

var prom = Rdbhost.preauth()
    	.query('SELECT name, address FROM contacts WHERE city = %(city)s AND state = %s;')
        .params(['CA'], {city: 'San Francisco'})
    	.get_data();

				

Event Emitter

The Rdbhost object is an event emitter, with on, off, once and emit methods.

Some named events are:

  • connection-openedconnection-closed indicate that a Websocket has been opened or closed. the event is provided two parameters, the role ...
  • connection-error indicates an error in the Websocket connection
  • database-error is emitted whenever a query has a database error. The event is emitted with the complete errorcode, and also with a two-digit errorcode prefix. You can listen for a specific error, such as 'database-error:55b00', or for a class of errors, such as 'database-error:55'.
  • database-user-error is emitted whenever a query has a database error, not handled by rdbhost code. The event is emitted multiple times per error, as above.
  • notify-received is emitted when a NOTIFY payload is received over the Websocket connection. The two parameters are channel and payload.
  • reload-request indicates the servers SFTP server has saved (or updated) a file in this account. The rdbhost-livereload library uses this event to conditionally reload files.
  • form-cleared indicates that a confirmation html form has been cleared from view.

Example:

Rdbhost.on('notify-received', function(channel, payload) {

	if (channel === 'chat') {

		add_to_chat_log(payload);
	}
	else if (channel === 'status') {

		if (payload === 'goodbye')
			console.log('user is leaving');
	}
});
				

SQL Inline

If you use the RdbHost inline SQL feature, the library will read the inlined data from the DOM, and provide it to your rendering code.

Example

<script id="RDBHOST-SQL-INLINE-ID" type="text/sql" data-sql="SELECT * FROM samples;"
        data-role=p0000000014></script>

<script>
  var p = Rdbhost.inline_sql();
  p.then(function(d) {
    var rows = d.result_rows[0].records.rows;
    // do something with rows data from 'samples' table
  })
</script>

If the query is not whitelisted the first time you load the page, the inline data will be the JSON error results, and the module will try to get the rows data via its regular ajaxy request, and you will be asked, via the usual dialog, to authorize whitelisting.

For a live demo, see JS Demos. [use view-source]

Github

See the Github Repo.