Name

Description

SK.DB( token )

Constructor

The library is used for wrap the execution of Database API calls.

The library is available everywhere within the WebForce context.

The "token" can be either the session ID (if the user is logged) or an access token created with the Database API.

Database methods

getDatabases(
   callback_ok,
   callback_failure
)

Gets the list of current databases. The callback_ok's interface is:
function( sorted_array_of_databases ) 
Each of the elements in the sorted array has the same structure as every element from the array returned by db.get_all API call.

The callback_failure has the following interface:
function( message ) 
Where "message" is the description of the error that has happened. The callback_failure has the same interface in this library.

getDatabase(
   db_id,
   callback_ok,
   callback_failure
)

Retrieves information about a given db_id. The callback_ok receives a hash of the database meta data (see db.get)

getDatabaseID(
   db_name,
   callback_ok,
   callback_failure
)

Retrieves the ID of a database by its name. 

Note that this method does not take into account if there is more than 1 database with that name. It simply takes the first one.

The callback_ok receives the ID of the database with this name.

addDatabase(
   db_meta,
   callback_ok,
   callback_cancel
)

Adds a database to the account which supplies the current token. The callback_ok receives a hash with the database meta (see db.add).

Column methods

getColumns(
   db_id,
   callback_ok,
   callback_failure
)

Returns the list of columns for a given database ID. 

The callback_ok receives an array of columns sorted the way they appear in the Database Editor. If the database with ID "db_id" was never edited from the Database Editor the columns order is not defined. If there were columns added after a database with columns was edited in the Database Editor, these columns are appended at the end of the sorted list. 

Each of the elements of the array is a hash which contains the column meta data (see db.column.get) and a few more properties:
{
   ...
      column meta data from db.column.get
   ...,
   width: <column width>,
   sorted: <true or false>,
   sort_order: <"asc" or "desc">
}

NOTE: If the columns have never been modified within the Database Editor the extra fields — width, sorted, sort_order — will not exist.

getColumnsMeta(
   db_id,
   column_names,
   callback_ok,
   callback_failure
)

Returns the pure column meta information (without the Database Editor related one) as db.column.get provides, but for a list of columns.

If "column_names" is "null" meta information about all columns is returned. Otherwise the information about the array of column_names is returned.

callback_ok receives an array of meta data.

addColumn(
   column_meta,
   callback_ok,
   callback_failure
)

Adds a column to a database mentioned in the hash column_meta. For more information about the keys in column_meta see the db.column.add API call.

The callback_ok receives the meta information db.column.add provides.

NOTE: For the "type" of the column a constant from SK.DB.Column can be used.

updateColumn

Not implemented yet.

removeColumn

Not implemented yet.

Cells operations

updateCells

Not implemented yet.

Records operations

getRecords(
   db_id,
   column_names,
   filter,
   callback_ok,
   callback_failure
)

Retrieves all records from a given database filtered by "filter". The result contains only the columns listed in column_names. If the column_names array is set to null, all columns exist in the result. 

The "filter" is a hash which has the same structure as the filter in db.query.get_filtered_rows, but the "where" doesn't contain column IDs, but column names.

The callback_ok has the following interface:
funciton( columns_meta, records, total_num_records )

The columns_meta is an array which getColumns provides to callback_ok. 

The "records" is an array of hashes. Each element has the following structure:
{
   row_id: <record/row ID>,
   cells: {
      "<column name1>": "<cell value1>",
      "<column name2>": "<cell value2>",
      ...
   }
}

The total_num_records makes sense if you have specified a filter.limit value. In this case the number of records in the array of "records" will be less than total_num_records. If you haven't specified filter.limit, the length of the array of records will be the same as total_num_records value.

getRecordsByIDs(
   db_id,
   columns_meta,
   filter,
   callback_ok,
   callback_failure
)

This is the same function as getRecords, but the difference is in the list of columns. Here you specify an array of columns_meta — the same array getColumns or getColumnsMeta returns. The rest of the definition of getRecords applies here too.

addRecord(
   db_id,
   cells,
   callback_ok,
   callback_failure
)

Adds a new record to the database. 

The "cells" is a hash:
{
   "<column name1>": "<cell value1>",
   "<column name2>": "<cell value2>", 
   ...
}

The callback_ok should have the following interface:
function( row_id, cells, columns )

The "cells" is a hash of 
{
   "<column name1>": "<cell value1>",
   "<column name2>": "<cell value2>",
   ...
}

The "columns" is an array getColumns gives to callback_ok.

addRecordByIDs(
   db_id,
   columns_meta,
   cells,
   callback_ok,
   callback_failure
)

The method does the same as addRecord, but the parameters differ a little. There is an extra array of columns_meta (the same getColumns returns) and the "cells" are not a hash by column name, but by column ID, i.e.:
{
   "<column ID1>": "<cell value1>",
   "<column ID2>": "<cell value2>",
   ...
}

updateRecord(
   db_id,
   row_id,
   cells,
   callback_ok,
   callback_failure
)

Updates the cells of a given record in the database. 

The "cells" format is a hash:
{
   "<column name1>": "<cell value1>",
   "<column name2>": "<cell value2>",
   ...
}

The callback_ok has the same interface as in addRecord.

updateRecordByIDs(
   row_id,
   columns_meta,
   cells,
   callback_ok,
   callback_failure
)

The same as updateRecord — updates a record in a database. The parameters differ a little. The columns_meta is what getColumns returns to callback_ok. The "cells" are not a hash by column name, but by column ID:
{
   "<column ID1>": "<cell value1>",
   "<column ID2>": "<cell value2>",
   ...
}

The callback_ok has the same interface as in addRecord.

removeRecord

Not implemented yet.

Access tokens methods

getTokens(
   callback_ok,
   callback_failure
)

This method (as well as the other token-related methods) makes sense only if the token passed in the constructor is the logged user session ID. Otherwise it will result into an "Access denied"

The callback_ok receives an array of tokens with the same structure as db.access.get_all returns.

addToken(
   properties,
   callback_ok,
   callback_failure
)

Adds a token to the current account. The "properties" of the token are a hash with the same key-value options as db.access.add requires.

The "callback_ok" receives a hash the same structure as db.access.add.

updateToken(
   token_id,
   properties,
   callback_ok,
   callback_failure
)

Updates an existing access token. You can't update the token key though, but you can update its name and extra information. 

The properties are the same as in addToken and the returned value to callback_ok is the same as db.access.update.

getTokenByName(
   name,
   callback_ok,
   callback_failure
)

As the name implies, this method retrieves the token information by finding a token with a given "name". 

The returned information to callback_ok is a hash with the same structure as db.access.get.

getToken(
   token_id,
   callback_ok,
   callback_failure
)

Returns the token meta information but by specifying a token ID. The "callback_ok" has the same interface as in getTokenByName.


 

Examples

Getting a filtered list of rows from a database "Users" where there is a "Name" column. This example will display a neat way to build your code in an object oriented manner. 

<script type="text/javascript">
   var MyDisplayRecords = new Class({
      db_obj: null,
      print_callback: function () {},
      
      initialize: function( print_callback ) {
         // Initialize the DB library we're going to use later
         this.db_obj         = new SK.DB( SK.Singletons.env.get( 'session_id' ) );
         
         // If there's a print_callback specified, used it, otherwise use an empty function
         this.print_callback = Array.pick([ print_callback, function (){} ]);
      },
   
      run: function( name, filter ) {
         // Get the database ID from the name first
         this.db_obj.getDatabaseID(
            name,
            function( db_id ) {
               // Now that we have the DB ID get the records
               this.mgr.displayRecordsByDBID( db_id, this.filter );
            }.bind( { mgr: this, filter: filter } ),
            function( message ) {
               alert( message );
            }
         );
      },
   
      displayRecordsByDBID: function( db_id, filter ) {
         this.db_obj.getRecords(
            db_id,
            null, // All columns
            filter,
            this.finished.bind( this ),
            this.failure.bind( this )
         );
      },
      
      finished: function( columns, records, total_records ) {
         this.print_callback( "There are " + total_records + " records" );
         this.print_callback( "The columns are: " + columns.map( function( column ) { return column.name; } ).join( ", " ) );
         for ( var i = 0; i < records.length; i++ ) {
            var record = records[ i ];
            for ( var col_name in record.cells ) {
               this.print_callback( "#" + record.row_id + ". " + col_name + ": " + record.cells[ col_name ] );
            }
            this.print_callback( "------------------------" );
         }
         this.print_callback( "Done" );
      },
      
      failure: function( message ) {
         this.print_callback( "FAILURE: " + message );
      }
   });
   
   // Test what we've done
   new MyDisplayRecords( function( message ) { _$( 'mylog' ).grab( new Element( 'div', { text: message } ) ); } ).run(
      "Users",
      {
         "where": [
            [ "Name", "like", [ "test" ] ]
         ]
      }
   );
</script>
<div id="mylog"></div>