Active Query Builder support area

[Obsolete] JavaScript API of Active Query Builder ASP.NET edition 2.0

Last modified:

Contents

Web Application API

Basic methods

QB.Web.Application.refreshSql(callback);
The refreshSql method should be called to apply changes in the query that were made by the user in the SQL Text Editor. Calling this method will lead to sending the SQL query text to the server, it parsing and subsequent updating of the query visual representation. In the callback function of this method, the programmer can check the QB.Web.Application.SqlErrorEventArgs property. It will be null in case of a successful parsing of the updated query; otherwise, it will contain information about SQL parsing error.

Status Bar message displaying methods

QB.Web.Application.MessageInfo(message);
QB.Web.Application.MessageWarning(message); 
QB.Web.Application.MessageError(message);
These methods display the specified message in the Status Bar with the appropriate icon at the left (information, exclamation and red cross icons).

Query parameters handling methods

QB.Web.Application.getQueryParams(callback);
QB.Web.Application.setQueryParamValues(params, callback);
If you want to let the user specify values of the query parameters, call the getQueryParams method first. In the callback function you will receive the array of objects of the following type (or null if parameters aren't found):
QB.Web.Dto.QueryParamDto = function() {
   this.Symbol = null;
   this.Name = null;
   this.FullName = "";
   this.DataType = "String";
   this.DataTypeDB = 0;
   this.CompareOperator = null;
   this.ComparedField = null;
   this.ComparedObject = null;
   this.MetadataObjectGuid = null;
   this.MetadataFieldGuid = null;
   this.Value = null;
};
Show the dialog prompting for parameter values, apply them to the Value field and send this array back to the server using the setQueryParamValues method call. In the callback function of this method, you can fire SQL query execution on the server.
There's the "Query Results" demo project that illustrates query parameters handling and SQL query execution. It is shipped with the component's installation package in two variants: one for the classic WebForms ASP.NET environment and another for MVC with Razor view engine. All demo projects are installed to the "%USERPROFILE%\Documents\Active Query Builder ASP.NET Examples" folder.

Criteria Builder handling methods

QB.Web.Application.CriteriaBuilder.isValid(); 
QB.Web.Application.CriteriaBuilder.sendDataToServer(callback);
QB.Web.Application.CriteriaBuilder.update(callback);
The isValid method allows for checking of the Criteria Builder's validity state. The control might have an invalid state if some of its conditions have incorrect or unspecified values.
The sendDataToServer method should be called to apply criteria to the query on the server. It fails to apply criteria and returns false if Criteria Builder is currently in the invalid state. In the callback function of this method, you can fire SQL query execution on the server.
The update method requests the actual data from the server and updates the control. One may need to call this method when criteria are changed in the QueryTransformer object programmatically on the server side, to update data in control.

Basic properties

These properties allow getting SQL query text. The first always gets valid query text from the query builder; the second gets the content of SQL text editor that may contain arbitrary text entered by the user.
QB.Web.Application.SQL
QB.Web.Application.editor.val()
The following properties can be used to get information about component's state on the server.
QB.Web.Application.UserData 
QB.Web.Application.SqlErrorEventArgs
Use the UserData property to get custom information from the server side about the query. To send this information from the server, assign an object instance to the SessionStore.Current.Exchange.Data property in the QueryBuilderControl.SQLUpdated event handler. An example of such usage can be found in the "Alternate Names" demo project.
Use the SqlErrorEventArgs property to get information about SQL parsing errors after applying manual changes from the text editor. The following fields are available for this property:
QB.Web.Dto.SqlErrorEventArgs = function() {
   this.SQL = null;
   this.Error = null;
   this.ErrorToken = null;
   this.ErrorTokenPos = {pos:0,col:0,line:0};
};

Client Core API

Client core API allows to interchange the query model objects between client and server. Using this API, you can change the behavior of existing web controls, or create custom UI using different web controls.
QB.Web.Core.ExchangeObject; // Data container for exchange with the server

QB.Web.Core.sendDataToServer(callback);  // Sends QB.Web.Core.ExchangeObject to the server
The main object that allows to interchange between the server-based SQL parsing engine and the client web UI can be accessed via the QB.Web.Core.ExchangeObject property. The QB.Web.Core.sendDataToServer method sends the necessary updates stored in the ExchangeObject property to the server.
QB.Web.Core.update(callback);
QB.Web.Core.fullUpdate(callback);
QB.Web.Core.reconnect(callback);
The update method updates the query objects state in case of changing the query on the server side. For example, this method can be called after loading of the previously saved query on the server. User controls get updated automatically after updating the query objects.
The fullUpdate method updates the query objects state and metadata in the database schema tree. This method should be called after re-establishing database connection on the server.
The reconnect method call initiates re-establishing of ASP.NET session and re-initialization of the server part of the component, then updates the visual query representation and reloads metadata in the database schema tree. During this procedure, the Init event handler is called on the server. This handler must initialize the QueryBuilder component, establish a connection to the database or populate the Metadata Container in some other way.
In other words
  • The update method gets updated query from the server;
  • The fullUpdate method does the same as "update", plus reloads the database schema tree;
  • The reconnect method re-initializes the ASP.NET session together with the component's server side, then performs "fullUpdate".
On receiving the data from the server via these methods, the appropriate Core API events are fired to reflect changes in the UI.
Q: Where to find documentation for all of those Dto's referred in the code below?
A: You can find them in the "\web-parts\js\release\dto.generated.js" file included in the installation package.

Query objects model methods

The following methods are introduced to work with the query object model on the client:
/**
 * Add dataSource
 * @param dataSource {QB.Web.Dto.DataSourceDto}
 */
QB.Web.Core.addDataSource(dataSource);

/**
 * Remove dataSource
 * @param dataSource {QB.Web.Dto.DataSourceDto}
 */
QB.Web.Core.removeDataSource(dataSource);

/**
 * Update dataSource
 * @param dataSource {QB.Web.Dto.DataSourceDto}
 */
QB.Web.Core.updateDataSource(dataSource);


/**
 * Add datasouce link
 * @param link {QB.Web.Dto.DataSourceLinkDto}
 */
QB.Web.Core.addLink(link);

/**
 * Remove datasouce link
 * @param link {QB.Web.Dto.DataSourceLinkDto}
 */
QB.Web.Core.removeLink(link);

/**
 * Update datasouce link
 * @param link {QB.Web.Dto.DataSourceLinkDto}
 */
QB.Web.Core.updateLink(link);


/**
 * Add rows to grid
 * @param {QB.Web.Dto.GridRowDto[]} rows
 */
QB.Web.Core.addGridRows(rows);

/**
 * Update rows in grid
 * @param {QB.Web.Dto.GridRowDto[]} rows
 */
QB.Web.Core.updateGridRows(rows);

/**
 * Remove rows from grid
 * @param {QB.Web.Dto.GridRowDto[]} rows
 */
QB.Web.Core.removeGridRows(rows);


/**
 * Update SQL
 */
QB.Web.Core.updateSQL(sql);
After applying the necessary changes using the core API methods listed above, you should call the QB.Web.Core.sendDataToServer method to send data to the server.

Core API events

QB.Web.Core.Events = {
    
    DataSending,
    /** @param data {ExchangeObject} */
    DataReceived,
    /** @param data {object} */
    UserDataReceived,
    /** @param data {string} */
    SQLReceived,
    /** @param data {string} */
    SQLChanged,
    /** @param data {SqlErrorEventArgs} */
    SQLError,
    /** @param data {QB.Web.Dto.QueryStructureDto} */
    QueryStructureChanged,
    /** @param data {Items: string[], LastItemId} */
    MessagesReceived,
    /** @param data {QB.Web.Dto.ContextMenuDto} */
    ContextMenuReceived
};

/**
 * Bind to core event
 * @param event {QB.Web.Core.Events}
 * @param callback
 * @param context
 */
QB.Web.Core.bind(event, callback, context);

QB.Web.Core.NavBar.bind(event, callback, context);
QB.Web.Core.NavBar.Events: {
    /** @param data {QB.Web.Dto.UnionNavBar} */
    DataReceived
}

QB.Web.Core.Canvas.bind(event, callback, context);
QB.Web.Core.Canvas.Events: {
    /** @param data {QB.Web.Dto.CanvasDto} */
    DataReceived
}

QB.Web.Core.Grid.bind(event, callback, context);
QB.Web.Core.Grid.Events: {
    /** @param data {QB.Web.Dto.GridDto} */
    DataReceived
};

QB.Web.Core.CriteriaBuilder.bind(event, callback, context);
QB.Web.Core.CriteriaBuilder.Events: {
    /** @param data {QB.Web.Dto.CriteriaBuilderDto} */
    DataReceived
};

QB.Web.Core.MetadataTree.bind(event, callback, context);
QB.Web.Core.MetadataTree.Events: {
    Loaded,
    /** @param data {QB.Web.Dto.ExchangeTreeDto} */
    DataReceived
};
The QB.Web.Core.MetadataTree.Loaded event is fired when the necessary metadata information is fully loaded on the web page. After that, the component is ready to interact with the end-user. You may want to hide or disable the component area on the web page until it's completely loading and ready for user actions.
The SQLChanged event is fired each time the query is updated, and SQL query text is received from the server.
The SQLError event is fired when the parsing error occurs on the server.
The DataSending and DataReceived events are fired before and after exchanging data packets with the server. The UserDataReceived event is fired after the data exchange if some user data is passed to the client. The data passed to the client is available via the QB.Web.Application.UserData property. The rest of "*Received" events are fired on receiving the appropriate types of data from the server: SQL text (SQLReceived), User messages (MessagesReceived), Context menu (ContextMenuReceived). The rest of the information is handled by appropriate core objects (NavBar, Canvas, Grid, CriteriaBuilder and MetadataTree).

API usage samples

How to add a new table/view to the design pane in javascript through the exposed metadata name?

    var ds = new QB.Web.Dto.DataSourceDto();
    ds.Name = "......"; // Set name
    ds.Alias = "....."; // Set alias
    QB.Web.Core.addDataSource(ds);
    QB.Web.Core.sendDataToServer();

How to add items to the query column list, as well as to change their properties (for example, the WHERE clause)?

    var row = new QB.Web.Dto.GridRowDto();
    row.Select = true;
    row.Expression = ".......";
    QB.Web.Core.addGridRows([row]);
    QB.Web.Core.sendDataToServer();

Events of UI controls

Database Schema Tree:

Binding:
    QB.Web.Application.Tree.bind(event, callback);
Events:
    QB.Web.Tree.Events.TreeSelectNode
    QB.Web.Tree.Events.TreeDoubleClickNode

Design Pane:

Binding:
    QB.Web.Application.Canvas.bind(event, callback);
Events:
    QB.Web.Canvas.Events.CanvasOnAddTable
    QB.Web.Canvas.Events.MetadataObjectAdded
    QB.Web.Canvas.Events.CanvasOnRemoveTable
    QB.Web.Canvas.Events.CanvasOnDropObject
    QB.Web.Canvas.Events.CanvasOnAddTableField
    QB.Web.Canvas.Events.CanvasContextMenuCommand
    QB.Web.Canvas.Link.Events.CanvasLinkOnChanged
Sub-query Navigation Bar:
Binding:
    QB.Web.Application.NavBar.bind(event, callback);
Events:
    QB.Web.NavBar.Events.NavBarBreadCrumbSelectNode
    QB.Web.NavBar.Events.NavBarAction

Datasource controls (objects on the Design Pane):

Binding:
Use the QB.Web.Canvas.Events.MetadataObjectAdded event to bind to datasources.
Events:
    QB.Web.TableObject.Events.TableObjectOnCheckField
    QB.Web.TableObject.Events.TableObjectOnCreate
    QB.Web.TableObject.Events.TableObjectOnClose
    QB.Web.TableObject.Events.TableObjectOnDestroy
    QB.Web.TableObject.Events.TableObjectOnMoved
    QB.Web.TableObject.Events.TableObjectOnUpdated
    QB.Web.TableObject.Events.TableObjectOnLinkCreate
    QB.Web.TableObject.Events.TableObjectOnLinkDelete
    QB.Web.TableObjectField.Events.TableObjectFieldOnCheckField

Query Columns Grid:

Binding:
    QB.Web.Application.Grid.bind(event, callback);
Events:
    QB.Web.Grid.Events.GridOnAddTable
    QB.Web.Grid.Events.GridOnAddTableField
    
    QB.Web.Application.Events.GridOnRowChanging
    QB.Web.Application.Events.GridOnRowChanged
    QB.Web.Application.Events.GridOnRowAdding
    QB.Web.Application.Events.GridOnRowAdded
    QB.Web.Application.Events.GridOnRowRemoved

SQL Text Editor:

Binding:
    QB.Web.Application.bind(event, callback);
Events:
    QB.Web.Application.Events.SQLTextChanged
    QB.Web.Application.Events.RefreshSQLClick
Is this article helpful for you?
Configuring custom state storage provider to use Active Query Builder in a web farm
How to setup Active Query Builder to use SignalR? (for Blazor apps)