Active Query Builder support area

AQB ASP.NET 3 - JavaScript Client Controls

Last modified:

AQB.Web.UI module

The AQB.Web.UI module contains the client components which contain the necessary properties to visual options in case of client-side JavaScript rendering.

Contents:

startApplication method

It fires the component initialization on the client-side.

Simple initialization of Active Query Builder on the client.
AQB.Web.UI.startApplication(id);

This method must be called to start working with Active Query Builder.

If the visual query building process doesn't start immediately on the page load, you can delay this method call to save resources.

Additionally, it can instantiate the component server-side. If an instance of the QueryBuilder object is not created in the action controller method, you can pass the second parameter to this method to create it right when you initialize the client. This parameter can be either a path to the QueryBuilder initialization controller method or a function that will call this method itself and fire onSuccess and onError callbacks.

Initialization of the component on both the client-side and server-side.
AQB.Web.UI.startApplication(id, '/QueryBuilder/CreateQueryBuilder');

 

Initialization of the component on both the client and server when special handling should be performed before calling the server-side initialization method.
        function createQueryBuilder(onSuccess, onError) {
            checkToken(function () {
                createQbOnServer(onSuccess, onError);
            });
        }

        function checkToken(callback) {
            // do the needful
            // ...
            callback();
        }

        function createQbOnServer(onSuccess, onError) {
            $.ajax({
                url: AQB.Web.host + '/QueryBuilder/CreateQueryBuilder',
                data: { name: instanceId },
                beforeSend: beforeSend,
                success: onSuccess,
                error: onError
            });
        }

        AQB.Web.UI.startApplication(instanceId, createQueryBuilder);

Client controls

This section describes the HTML layout rendering controls or helpers as they must be defined in different development environments:

  • WebForms controls
  • MVC HTML helpers
  • Client-side JavaScript rendering 
  • ASP.NET Core 2.0 Tag helpers

For all of the client-side control constructors:

The first parameter is the component's instance Id. It must be the same on the client and server. It allows for the initialization of individually configured instances on the server and for running multiple instances of the component on the client.

The second parameter is the id or path of the HTML DOM element hosting the component on the web page.

The third parameter is a collection of properties of the respective component.

QueryBuilder

Remark: This control is named QueryBuilderControl in WebForms.

constructor

Creates the component on the client-side.

Creation of the QueryBuilder control on the client-side
var params = {
    disableSessionKeeper: false,
    theme: 'default',
    language: 'Auto',
    reinitUrl: '/QueryBuilder/CreateQueryBuilder' 
};
AQB.Web.UI.QueryBuilder(qbId, '.activeQueryBuilder', params);

After the initialization, the component is available via the AQB.Web.QueryBuilder reference.

Properties

Name Type Default Description
Language

string

 "Auto" The component's UI language code.
Theme string "default" Defines the theming scheme applied to UI controls. Allowed values: "default", "jqueryui", "bootstrap".

Alternatively, you can define custom CSS styling assigning class names to elements of the AQB.Web.theme object.
LoadStyleFrom string "" Allows redefining the styles file completely.
DisableSessionKeeper bool false Allows to turn off "ping" requests which maintain the server-side session during periods of user inactivity.
HandlersPath
(only for the server-side rendering mode)		 string  "" Allows redefining the path to AQB handlers on the server-side for each particular instance. If not defined, the path is set to the default value which is also registered automatically on the server-side. 

An example of handling AQB requests on a custom path can be found in remarks for the BaseHandler.DisableRegistration method.

Note: In the client-side rendering mode, use the AQB.Web.virtualDirectory or host properties instead.
ReinitUrl
(only for the client-side rendering mode)		 string "" Points to the server-side QueryBuilder instance creation method. 

This parameter is needed for the case a component instance is destroyed on the server due to the client's inactivity (session expiration).

Helpers

HTML layout helper samples for the QueryBuilder control
<!--WebForms-->
<AQB:QueryBuilderControl ID="QueryBuilderControl1" runat="server" UseDefaultTheme="false" Language="en" />
<!--HtmlHelpers-->
@Html.QueryBuilder(Model, s => { s.UseDefaultTheme = false; s.Language = "en"; }).GetHtml()
<!--TagHelpers-->
<query-builder query-builder="@Model" use-default-theme="false" language="en"></query-builder>

ObjectTreeView

constructor

Creates the component on the client-side.

Creation of the TreeView control on the client-side
var params = {
    showFields: true,
    showDescriptionInTooltip: true,
    autoExpandSingleNode: true,
    sortingType: ObjectsSortingType.NameExceptFields,
    sortOrder: SQLOrderByOrders.Asc,
    defaultExpandMetadataType: MetadataType.Schema
};
AQB.Web.UI.ObjectTreeView(qbId, '#treeView', params);

After the initialization, the component is available via the AQB.Web.QueryBuilder.TreeViewComponent reference.

Properties:

Name Type Default Description
ShowDescriptionInTooltip bool true Determines whether object and field descriptions should be displayed in tooltips.
ShowFields bool true Determines whether the field nodes should be visible.
AutoExpandSingleNode bool true Prescribes to expand the only child node automatically on expanding the parent node.
SortingType ObjectsSortingType NameExceptFields Determines to sort of objects within the tree.
Possible values:
Name (sort by name,
TypeName (sort by object type, then - name),
NameExceptFields (sort by name, but keep the original order of fields),
TypeNameExceptFields (sort by object type, then - name, but keep the original order of fields),
None.
SortOrder SQLOrderByOrders Asc Determines whether the objects should be sorted ascending (Asc) or descending (Desc).
DefaultExpandMetadataType*
(read remarks below)		 MetadataType Objects Specifies the type of objects to which the tree should be expanded automatically on start.
Possible Values:
None,
Server, Database, Schema, Package,
Namespaces= (Server| Database| Schema| Package),
Table, View, Procedure, Synonym,
Objects= (Table| View| Procedure| Synonym),
Aggregate,
Parameter, Field, ForeignKey,
ObjectMetadata= (Parameter| Field| ForeignKey),
UserQuery, UserField,
All = (/all of the above/).
To keep the tree completely collapsed set this property to None.
DefaultExpandFolderNodes*
(read remarks below)		 Boolean false Determines whether to initially expand nodes that aren't tied to a specific metadata object (grouping nodes, such as "Tables", "Views", etc.)

Remarks:

1. To display the fully collapsed tree on the application start, turn the AutoExpandSingleNode to false and the DefaultExpandMetadataType to Server.

2. The client loads the tree no deeper than the server loads according to the QueryBuilder.DatabaseSchemaViewOptions.DefaultExpandMetadataType and DefaultExpandFolderNodes server-side properties. Please check these properties if the corresponding client properties don't seem to work.

Helpers:

HTML layout helper samples for the ObjectTreeView control
<!--Webforms-->
<AQB:ObjectTreeView runat="server" ID="ObjectTree1" SortingType="Name" ShowFields="True" />
<!--HtmlHelpers-->
@controls.ObjectTreeView(s => { s.SortingType = ObjectsSortingType.Name; s.ShowFields = true; }).GetHtml()
<!--TagHelpers-->
<object-tree-view query-builder="@Model" sorting-type="Name" show-fields="true"></object-tree-view>

Canvas

constructor

Creates the component on the client-side.

Creation of the Canvas component on the client-side
var params = {
    Direction: ContentDirection.LeftToRight,
    defaultDatasourceWidth: 250,
    defaultDatasourceHeight: 160,
    markColumnVisible: true,
    nameColumnVisible: true,
    typeColumnVisible: true,
    descriptionColumnVisible: false,
    disableQueryProperties: false,
    disableDatasourceProperties: false,
    disableLinkProperties: false,
    linkStyle: LinkStyle.MSAccess,
    linkColor: '#000B9D',
    displayKeyCardinality: true
};
AQB.Web.UI.Canvas(qbId, '.canvas', params);

After the initialization, the component is available via the AQB.Web.QueryBuilder.CanvasComponent reference.

Properties:

Name Type Default Description
DefaultDatasourceWidth int 250 The default width of new datasource objects.
MaxDefaultDatasourceHeight int 160 The maximum height of new datasource objects. 
DescriptionColumnVisible bool false Determines whether to show field descriptions in the datasource field list.
DisableDataSourceProperties bool false Determines whether the user is allowed to edit datasource properties (alias).
DisableLinkProperties bool false Determines whether the user is allowed to edit link properties (join expression and type)
DisableQueryProperties bool false Determines whether the user is allowed to edit query properties (distinct, etc.).
DisplayKeyCardinality bool true Determines whether to show key cardinality labels at the link ends ("1" to "infinity").
LinkColor string "#000B9D" The color of links between datasources on the design pane.
LinkStyle LinkStyle MSAccess Style of links between datasources on the design pane.
Possible values:
MSAccess, MSSQL, Simple.
MarkColumnVisible bool true Determines whether to show an indicator (primary key) next to each field in the datasource field list.
NameColumnVisible bool true Determines whether to show field names in the datasource field list.
TypeColumnVisible bool true Determines whether to show field data types in the datasource field list.

Remarks:

  • By default, datasource height is calculated to fit the height of the field list.
  • The content of the Query Properties dialog depends on the Syntax Provider being used.
  • Key cardinality isn't a property of join, but the underlying foreign key, so it's drawn only for links for which a corresponding foreign key exists.
  • Link styles mostly differ from each other by the join type marker in the middle of the link. 

Helpers:

HTML layout helper samples for the Canvas control
<!--Webforms-->
<AQB:Canvas ID="Canvas1" runat="server" LinkStyle="MSSQL" LinkColor="#3d566d" DisplayKeyCardinality="False" />
<!--HtmlHelpers-->
@controls.Canvas(s => { s.LinkStyle = LinkStyle.MSSQL; s.LinkColor = "red"; s.DisplayKeyCardinality = true; }).GetHtml()
<!--TagHelpers-->
<aqb-canvas query-builder="@Model" link-style="MSSQL" link-color="green" display-key-cardinality="false"></aqb-canvas>

Grid

constructor

Creates the component on the client-side.

Creation of the Grid component on the client-side
var params = {
    nullOrderingInOrderBy: false,
    orColumnCount: 2,
    useCustomExpressionBuilder: AffectedColumns.None,
    quickFilterInExpressionMatchFromBeginning: false
};
AQB.Web.UI.Grid(qbId, '.grid', params);

After the initialization, the component is available via the AQB.Web.QueryBuilder.GridComponent reference.

Properties:

Name Type Default Description
CreateColumnAliasesForUnnamedColumns bool true Prescribes to define an alias for the query columns which require alias to address (not a single field SQL expressions).
NullOrderingInOrderBy bool false Display "Nulls first", "Nulls last" options in the Ordering grid column.
OrColumnCount int 2 The initial number of visible "Or" columns.
QuickFilterInExpressionMatchFromBeginning bool false Determines if quick filtration in the drop-down list of Expression grid column match values only from the beginning; otherwise - by substring.
UseCustomExpressionBuilder AffectedColumns None Determines if a button should be displayed next to the Expression and/or conditions cells of the grid.
Possible values:
None, ExpressionColumn,
ConditionColumns,
AllColumns. 

Remarks:

Setting the value of the UseCustomExpressionBuilder property to a different value than None, the programmer should handle the ... event to display the expression editor, accepting the existing cell value and returning the modified value. 

Helpers:

HTML layout helper samples for the Grid control
<!--Webforms-->
<AQB:Grid ID="Grid1" runat="server" UseCustomExpressionBuilder="AllColumns" OrColumnCount="0" />
<!--HtmlHelpers-->
@controls.Grid(s => { s.UseCustomExpressionBuilder = AffectedColumns.ExpressionColumn; s.OrColumnCount = 0; }).GetHtml()
<!--TagHelpers-->
<grid query-builder="@Model" use-custom-expression-builder="ConditionColumns" or-column-count="0"></grid>

Editor (SqlEditor)

constructor

Creates the component on the client-side.

Creation of the Editor component on the client-side
var params = {
    readOnly: false,
    targetQueryPart: QueryPart.Query
};
AQB.Web.UI.Editor(qbId, '.sqlEditor', params);

After the initialization, the component is available via the AQB.Web.QueryBuilder.EditorComponent reference.

Properties:

Name Type Default Description
ReadOnly bool false Determines whether the control should allow text modification or not. 
TargetQueryPart QueryPart Query Specifies the displayed part of the query. By default, the whole query text is displayed.
Possible values:
Query, SubQuery, UnionSubQuery.

Remarks:

Setting the TargetQueryPart property to a different value than Query, only a certain part of the query will be visible to the end-user:

  • SubQuery - currently active sub-query (may contain set operators like UNION, EXCEPT, INTERSECT);
  • UnionSubQuery: same as SubQuery if there aren't any set operators in it or the currently active SELECT statement in a series of SELECT statements joined by set operators.

Helpers:

HTML layout helper samples for the SqlEditor control
<!--Webforms-->
<AQB:SqlEditor ID="SQLEditor1" runat="server" TargetQueryPart="Query"></AQB:SqlEditor>
<!--HtmlHelpers-->
@controls.SqlEditor(s => { s.TargetQueryPart = QueryPart.SubQuery; }).GetHtml()
<!--TagHelpers-->
<sql-editor query-builder="@Model" target-query-part="UnionSubQuery"></sql-editor>

SubQueryNavigationBar

constructor

Creates the component on the client-side.

Creation of the NavBar component on the client-side
var params = {
    unionNavBarVisible: true
};
AQB.Web.UI.SubQueryNavigationBar(qbId, '.subQueryNavigationBar', params);

After the initialization, the component is available via the AQB.Web.QueryBuilder.NavBarComponent reference.

Properties:

Name Type Default Description
UnionNavBarVisible bool true Determines whether the controls to manage set operators should be visible on the second drop-down line of the bar. 

Helpers:

HTML layout helper samples for the SubQueryNavigationBar control
<!--Webforms-->
<AQB:SubQueryNavigationBar ID="SubQueryNavigationBar1" runat="server" UnionNavBarVisible="True" />
<!--HtmlHelpers-->
@controls.SubQueryNavigationBar(s => { s.UnionNavBarVisible = false; }).GetHtml()
<!--TagHelpers-->
<sub-query-navigation-bar query-builder="@Model" union-nav-bar-visible="false"></sub-query-navigation-bar>

StatusBar

constructor

Creates the component on the client-side.

Creation of the StatusBar component on the client-side
AQB.Web.UI.StatusBar(qbId, '.statusBar');

After the initialization, the component is available via the AQB.Web.QueryBuilder.StatusBarComponent reference.

Helpers:

HTML layout helper samples for the SubQueryNavigationBar control
<!--Webforms-->
<AQB:StatusBar ID="StatusBar1" runat="server" />
<!--HtmlHelpers-->
@controls.StatusBar().GetHtml()
<!--TagHelpers-->
<status-bar query-builder="@Model"></status-bar>

UserQueries

constructor

Creates the component on the client-side.

Creation of the UserQueries component on the client-side
AQB.Web.UI.UserQueries('.userQueries');

After the initialization, the component is available via the AQB.Web.QueryBuilder.UserQueriesComponent reference.

Helpers:

HTML layout helper samples for the SubQueryNavigationBar control
<!--Webforms-->
<AQB:UserQueries ID="UserQueries1" runat="server" />
<!--HtmlHelpers-->
@controls.UserQueries().GetHtml()
<!--TagHelpers-->
<user-queries query-builder="@Model"></user-queries>

CriteriaBuilder

constructor

Creates the component on the client-side.

Creation of the CriteriaBuilder component on the client-side
var params = {
   rootJunctionPrefix: 'Where',
   junctionPostfix: 'of the following succeed',
   showPrefixes: true,
   allowCustomLogicalSQLExpressions: false,
   autoSubscribe: true,
   autoLoad: false
};
AQB.Web.UI.CriteriaBuilder(cbid, '.criteriaBuilder', params);

After the initialization, the component is available via the AQB.Web.CriteriaBuilder reference.

Properties:

Name Type Default Description
LoadStyleFrom string "" Allows redefining the styles file completely.
RootJunctionPrefix string "Where" Specifies the text that precedes the root node junction selector.
JunctionPostfix string "of the following succeed" Specifies the text printed after each node junction selector.
ShowPrefixes bool true Determines whether to display "or" or "and" prefix before each subsequent node.
AllowCustomLogicalSQLExpressions bool false Determines whether the user is allowed to enter logical SQL expressions that are not tied to one of the listed columns.
AutoSubscribe bool true Prescribes to subscribe to changes of the QueryBuilder component with the same id during the component initialization. 
AutoLoad bool false Prescribes to request the list of columns during the component initialization.
DateFormat string "dd.mm.yy" Defines the client date display format. Possible values are listed here.

Helpers:

HTML layout helper samples for the SubQueryNavigationBar control
<!--Webforms-->
<AQB:CriteriaBuilder runat="server" ID="CriteriaBuilder1" />
<!--HtmlHelpers-->
@Html.CriteriaBuilder(Model).GetHtml()
<!--TagHelpers-->
<criteria-builder query-transformer="@Model"></criteria-builder>

AQB.Web.UI Enumerations

AffectedColumns

Lists possible combinations of Query Columns Grid columns to type SQL expressions for turning specific capabilities on and off.

var AffectedColumns = {
    None: 0,
    ExpressionColumn: 1,
    ConditionColumns: 2,
    AllColumns: 3
};

ObjectsSortingType

Lists possible types of sorting objects in the Database Schema View.

var ObjectsSortingType = {
    Name: 0,
    TypeName: 1,
    NameExceptFields: 2,
    TypeNameExceptFields: 3,
    None: 4
};

SQLOrderByOrders

Used to specify ascending or descending sort order.

var SQLOrderByOrders = {
    Asc: 0,
    Desc: 1
};

LinkStyle

Lists possible styles of drawing links on the Canvas.

var LinkStyle = {
    MSAccess: 0,
    MSSQL: 1,
    Simple: 2
};

ContentDirection

Used to specify the text reading direction.

var ContentDirection = {
    NotSet: 0,
    LeftToRight: 1,
    RightToLeft: 2
};

MetadataType

Lists possible types of nodes in the Database Schema View.

var MetadataType = {
    Root: 1,
    Server: 2,
    Database: 4,
    Schema: 8,
    Package: 16,
    Namespaces: 30,
    Table: 32,
    View: 64,
    Procedure: 128,
    Synonym: 256,
    Objects: 480,
    Aggregate: 512,
    Parameter: 1024,
    Field: 2048,
    ForeignKey: 4096,
    ObjectMetadata: 7168,
    UserQuery: 8192,
    UserField: 16384,
    All: 32766
};

QueryPart

Used to specify the currently visible part of the query in the SQL Text Editor.

const QueryPart = {
    Query: 'Query',
    SubQuery: 'SubQuery',
    UnionSubQuery: 'UnionSubQuery'
};
Is this article helpful for you?
AQB ASP.NET 3 - JavaScript API Documentation
Configuration file for Active Query Builder ASP.NET Edition 3.0