Effector 6.3 developer manual

XML reference 6.3

Effector Studio 6.3 summary

Effector Studio 6.3 manual

Effector 6.2 developer manual

XML reference 6.0

Effector Studio 3.2 summary

Effector Studio 3.2 manual

DataDefinition and filter management

The data definition objects (DataDefinition) cut across the operation of the entire system. They are behind practically all display objects. They provide the ability to establish a connection between the two outermost layers of the system, the user interface and the database, traversing various other layers. These data definition objects are able to employ business objects to carry out various database operations while serving the display components. For instance, saving is done by the BusinessObject also in case of inplace editing. However, the main task of DataDefinition is to function as a datasource for the majority of displays and help manage the filters during user interactions.

Location in the system

Its physical location is in the DataDefinition library of the XML package.

The DataDefinition never appears directly in the system, however, it has several points of connection to the various displays:

DataDefinition in the system

Available features

  • Datasource definition
  • Setting columns
  • Defining and attaching filters

Example

<DataDefinition xmlns="http://effector.hu/schema/ns/datadefinition">
    <SqlSelect>
        <![CDATA[    
            FROM Project p WITH(NOLOCK)    
            WHERE p.Deleted=0 AND 1=1    
        ]]>
    </SqlSelect>
    <Columns>
        <Column name="ProjectID">
            <Definition>
                <![CDATA[p.ProjectID]]>
            </Definition>
            <OutFilter>
                <Alias>Project_ID</Alias>
                <Type>Out</Type>
            </OutFilter>
            <IdColumn>ProjectID</IdColumn>
        </Column>
        <Column name="ObjectType">
            <Definition>
                <![CDATA[p.ObjectType]]>
            </Definition>
            <OutFilter>
                <Alias>Template_Project</Alias>
                <Type>Param</Type>
            </OutFilter>
            <IdColumn>ProjectID</IdColumn>
        </Column>
        <Column name="CompanyID">
            <Definition>
                <![CDATA[p.CompanyID]]>
            </Definition>
            <OutFilter>
                <Alias>Company_ID</Alias>
                <Type>Param</Type>
            </OutFilter>
            <IdColumn>ProjectID</IdColumn>
        </Column>
        <Column name="Name">
            <Definition>
                <![CDATA[p.Name]]>
            </Definition>
            <IdColumn>ProjectID</IdColumn>
        </Column>
        <Column name="ProjectName">
            <Definition>
                <![CDATA[p.Name AS ProjectName]]>
            </Definition>
            <IdColumn>ProjectID</IdColumn>
        </Column>
    </Columns>
    <InFilters>
        <InFilter>
            <Alias>Project_ID</Alias>
            <ConnectedColumnDefinition>p.ProjectID</ConnectedColumnDefinition>
        </InFilter>
    </InFilters>
</DataDefinition>

Datasource definition

The configuration of the datasource can be done with SqlSelect node. This node contains by default an SQL expression with no column definitions. The completion of the columns will be done by the DataDefinition based on the Column elements located under the /DataDefinition/Columns collection. This SQL statement defines which data will be loaded from the database by the given object. These pieces of data will serve as a datasource for the associated display components.

    <SqlSelect>
        <![CDATA[    
            FROM Project p WITH(NOLOCK)    
            WHERE p.Deleted=0 AND 1=1    
        ]]>
    </SqlSelect>

Available attributes

  • Running a stored procedure as a datasource is an option in which case the value of Type attribute should be StoredProcedure, while the value of the SqlSelect node should contain the name of the stored procedure. Its default value is Select.
  • With the setting of the distinct attribute, the distinct function of the SQL server is turned on. Its value can be true or false. Its default value is false.

Important note

What does the 1=1 mean in the example? The 1=1 expression has to be present in the WHERE part of all DataDefinitions. It is necessary because the system replace this string with the criteria provided by Filters, PSearch and other elements suitable for filtering.

DLL as source

If data source is a result of a programme code written in DLL, then node Module should be used instead of node SqlSelect.

<Module className="Namespace.Class" action="">[##LocalProgramPath##]\Namespace.dll</Module>

Class Class of the above example has to implement interface IExportModule.

Setting columns

The definition of columns can be done by using the Column nodes in the /DataDefinition/Columns collection. Each Column node contains a name attribute, which plays the role of the column identifier in the DataDefinition. Later, when using displays, this will create the connection between the two column definitions. The name attribute is identical either with the name of the SQL column or with the string used as an "alias". The Alias can be defined using the as keyword. Its use is shown in the following example:

<Definition>Count(e.EventId) as EventDB</Definition>

Nodes available for definition:

  • The BusinessObject node defines which business object the column belongs to. It plays a fundamental role in the operation of the inplace edit function available in grids.
  • The Definition node contains the column's SQL definition. This must meet the same syntactic rules as an SQL column expression. It may contain not only a column name but also more complex subqueries, however, in this case the result must be given an "alias" name.

       <Column name="EventDB">
           <BusinessObject>BusinessObjectProjec</BusinessObject>
           <Definition>Count(e.EventId) as EventDB</Definition>
       </Column>
    

Referencing other columns

By setting, under the Column node, the IsComposite optional node assuming a logical value, we can indicate the system that we are going to reference another column of the DataDefinition (or rather its value) in the definition of the given column. The replacement will be done once the query is complete. Referencing can be done in the following format: [##Column.Fieldname##].

<Column name="ColumnA">
    <Definition>ColumnA</Definition>
</Column>
<Column name="ColumnB">
    <IsComposite>true</IsComposite>
    <Definition>'The value of Column A: [##Column.ColumnA##]' AS ColumnB</Definition>
</Column>

Using FileInterface to download files

A common service called FileInterface carries out the file operations. If, for instance, we would like to download the document by clicking on a Link the following configuration should be used:

<Column name="FileInterfaceID">
    <UseFileInterface>true</UseFileInterface>
    <Definition><![CDATA[CAST(d.DocumentID  AS VARCHAR(20)) as FileInterfaceID]]></Definition>
    <IdColumn>DocumentID</IdColumn>
    <OutFilter>
        <Type>Param</Type>
        <Alias>FileInterfaceID</Alias>
    </OutFilter>
</Column>
<Column name="FileLink">
    <IsComposite>true</IsComposite>
    <Definition><![CDATA['<a href="FileInterface?p=[##Column.FileInterfaceID##]&a=download" target="_blank">' + ISNULL(d.RenamedFilename,'') + '</a>' AS FileLink]]></Definition>
    <IdColumn>DocumentID</IdColumn>
</Column>

In the DataDefinition column called FileInterfaceID we set the file’s unique ID used in the Document table, and by setting the value of the UseFileInterface node to true, we command the system to generate a unique key for the given document, which key will be passed on to the DataDefinition column called "FileLink" due to the fact that the value of the IsComposite node is set to true and the column called "FileInterfaceID" is referenced in its definition.

Defining and attaching filters

As it has been mentioned before, the notion of Filter indicates the structure and mechanism allowing for the communication of panels and screens in the system. In respect of its configuration, DataDefinition plays a role of key importance. The displays know from this display definition file what filters the layer beneath them can handle as output and input.

Communication(Filters)

Each filter has a type and a name (Alias). The system interprets the communication taking place via the connections based on these characteristics. Filters can be interpreted and processed, or in some instances simply let go by and sent toward the next component. These behaviors can easily be modified with configuration.

  • Alias: An important property of any filter is its Alias name. A given filter is identified by this name in the communication between panels and screens, and the carried value (Filter reference) can also be accessed using this name.
  • Type: Filters can be of Out or Param types.
    • There can be only one active Out type filter.
    • The Param type filters often take part in the evaluation of a control’s default value rule or other rules on the EditForm. The filters beginning with the Template_ Alias name have a special meaning. It will be discussed in greater depth later.

Configuring filters

To configure filters, we need to change settings at various locations.

First of all, we have to decide weather the given column is an identifier. If so, a filter can be configured to it, with which its value can be sent to other components. If the data is not of identification type, we can define an ID field to it. This definition can be done using the Column/IdColumn node.

  • We treat the DataDefinition column set in the IdColumn node as and identifier, and the column set here we will be an Out filter-type among the outgoing filters. The IDColumn of the other columns will also appear but only as a parameter.
  • Using the OutFilter node, we can set the Alias name of the outgoing filter, while using the Type node, we can set its type.

       <OutFilter>
           <Type>Out</Type>
           <Alias>Company_ID</Alias>
       </OutFilter>
    

Example

The following example features a properly configured outgoing filter. In this case, the column itself represents in identifier and it will use this identifier as in outgoing filter during the appropriate user interaction (generally clicking on the column).

<Column name="CompanyID">
    <BusinessObject>BusinessObjectCompany</BusinessObject>
    <Definition>c.CompanyID</Definition>
    <IdColumn>CompanyID</IdColumn>
    <OutFilter>
        <Type>Out</Type>
        <Alias>Company_ID</Alias>
    </OutFilter>
</Column>
<Column name="CompanyName">
    <Definition>c.Name AS CompanyName</Definition>
    <IdColumn>CompanyID</IdColumn>
</Column>

Now that we have outgoing filters, we can set up incoming filters. These are the filters the displays using DataDefinition can interpret in usage.

The incoming filters can be set using the InFilter node of the /DataDefinition/InFilters collection. The incoming filters listed here will filter the result rows define by the DataDefinition. Here we usually expect the unique ID of a table. The WHERE clauses generated using the filters listed here will replace the 1=1 expression of a query.

<InFilters>
    <InFilter>
        <Alias>Company_ID</Alias>
        <ConnectedColumnDefinition>c.CompanyID</ConnectedColumnDefinition>
    </InFilter>
    <InFilter>
        <Alias>Created_By_ID</Alias>
        <ConnectedColumnDefinition>c.CreatedbyID</ConnectedColumnDefinition>
    </InFilter>
</InFilters>
  • The Alias node defines the name of the incoming filter. The display will be able to interpret the parameter with the same name of Out type, and it will look for the appropriate incoming filter based on this.
  • The ConnectedColumnDefinition node creates the connection between the incoming filters and the columns of the DataDefinition. Here we have to set the value contained by the Definition. The DataDefinition will filter the query based on this value.

We have the option to set up a permanent forward list, allowing that the incoming filters with the predefined Alias will be forwarded toward the outgoing filters.

<ForwardedFilters>
    <ForwardedFilter>
        <AsType>Param</AsType>
        <Alias>Company_ID</Alias>
    </ForwardedFilter>
    <ForwardedFilter>
        <AsType>Param</AsType>
        <Alias>Project_ID</Alias>
    </ForwardedFilter>
</ForwardedFilters>

The value of the Alias node will be the name of the outgoing filter, which must be the same as the name of the incoming filter. The value of the AsType node defines the type of the filter, which may be Out or Param. There can be only one outgoing filter of Out type, therefore the system will modify the type to Param if more than one filter of Out type is defined either as a forwarded filter or in the definition of columns.

The filters with the name Template_* are special, these carry the sub-type of the chosen business objects. If the edit form to be displayed features a derived BusinessObject, this filter regulates which subtype of the given element be open for editing. (For instance, in case of the BusinessObjectProjectInfo the Template_Project filter will receive the value Info.)

  • Last update: 2 weeks 5 days ago
  • Effector