It is possible to connect XperienCentral to one or more external databases. The word ‘external’ is used to indicate that it is different from the internal database: The database that maintains XperienCentral’s internal content & administration. It is possible that the tables with external data are located in the same database as XperienCentral’s internal tables.
Because XperienCentral can be connected to other databases, it is, for example, possible to request data from the back office and show these on the website.
In This Topic
Use of Queries
Views on Database Content
By means of queries you can configure views on database content, see the example below:
Overview Versus Detail View
You can view database content on two levels:
- The overview level shows a list of records from the database.
- The detail view level shows one specific record if that record is clicked.
In the screenshot above, the upper part shows an overview and the lower part shows a detail view. Note that you can also place the detail view on another (special) page.
Sorting by Column
For the overview level, you may use "Sorting by column". By clicking on a column heading, a website visitor can toggle sorting between ascending and descending order. For each column in the overview, you can enable or disable "Sorting by column" separately.
Query Definitions
A query is a question posed to a database in a language referred to as SQL (Structured Query Language). The answer is information returned from the database, which then can be shown on the website. An example of an SQL query:
SELECT <fields> FROM <tables> WHERE <conditions> ORDER BY <field>
In XperienCentral, you manage your query definitions at a central point. Each query definition has a name and except for the actual query code, it also has some additional data such as the name of the database, the presentation format of the retrieved data, which fields of the retrieved data are to be shown in which columns and the use of query parameters.
To show the retrieved data on a web page, you insert a query content element on a page. In the content element you select the desired query definition.
Query Parameters
To be more flexible with queries, you can use parameters in the query code. For instance, you may use a parameter to filter the data to be retrieved on certain characteristics. Then, to change the filter characteristics, you only have to assign another value to the parameter without changing the query code. The parameter is put between ‘at’-signs in the WHERE clause.
SELECT <fields> FROM <tables> WHERE <field> IN (@myParameter@) ORDER BY <field>
You can assign values to a parameter at two levels:
- With the query content element
- With the query definition
About the Example Database
In this document, the database "Who is Who" is used to illustrate examples. In this database, the "whPerson’"table is the central table containing most of the personal data. The other tables are extensions ised to store the department, job and location.
Connecting an External Database
You can connect one or more databases of the type MySQL, MSSQL and Oracle. A database is contained on a database server, which may accommodate one or more databases. Prior to configure a database connection the database server must have been installed and started up properly. For each database connection, you have to set the name and some connection related attributes like the URL, a valid user name and a password.
To connect an external database, perform the following steps:
- Make sure a filled external database is available and that you know the connection related attributes.
- Navigate to Configuration -> Database Maintenance.
- Select the [Database connections] tab.
- Select [New database connection] from the pull-down menu (top left). A blank dialogue pane with connection related attributes is shown.
- Enter the connection related attributes.
- Press [Apply]. If XperienCentral can make the connection, the product and driver information is shown as well as a table content list.
Using Queries
In this section, we setup a basic view on the whPerson table by showing the following fields: lastname, prefix, firstname and email. This section will not elaborate on all the fields in the XperienCentral screens; go to section 4 for a detailed description on each field of the different panels. For this section we start with this query:
SELECT whPerson.lastname, whPerson.prefix, whPerson.firstname, whPerson.email FROM whPerson ORDER BY whPerson.lastname
Defining an Overview Query
Select menu Configuration > Queries (Query tab):
- To create a query, select ‘New query’ from the drop-down menu (see A).
- To copy a query, select that query and click [Copy] (see B).
- To delete a query, select that query and click [Delete] (see C).
- To add a column to the overview for any field in the SELECT clause, click [All fields] (see D). Then enter the column names (headings).
- To enable sorting by column, check the ‘Sort’ box] (see E).
Defining a query content element
After defining the overview query, you can place the content element ‘Query’ on a page.
Þ Navigate to the desired page.
Þ Select menu Insert > Overview > Query to place the content element.
Þ Select the desired overview query from the pull-down list.
Showing the basic overview
The result may look like this. Sorting by column has been enabled for ‘Last name’ and ‘First name’. By clicking on it, you can toggle sorting between ascending and descending order:
Note: For this type of content element with this presentation format, the title in the content element is not shown.
Overview with Parameter
Introduction
In this section, we introduce a query parameter. However, first we extend the overview with a column ‘Location’. In the query code, the ‘AS’ statement renames a field named ‘name’ to ‘locname’. This is used to avoid possible confusion with fields in other tables that are also named ‘name’ (in example further on in this document):
SELECT whPerson.lastname, whPerson.prefix, whPerson.firstname,
whPerson.email, whLocation.name AS locname
FROM whPerson, whPersonLocation, whLocation
WHERE whPerson.id=whPersonLocation.person
AND whPersonLocation.location=whLocation.id
ORDER BY whPerson.lastname
To be able to filter on names of different locations, we use a parameter ‘@place@’. A parameter substitutes a comma-separated list and thus it can adopt more than one value at the same time.
SELECT whPerson.lastname, whPerson.prefix, whPerson.firstname,
whPerson.email, whLocation.name AS locname
FROM whPerson, whPersonLocation, whLocation
WHERE whPerson.id=whPersonLocation.person
AND whPersonLocation.location=whLocation.id
AND whLocation.id IN (@place@)
ORDER BY whPerson.lastname
Defining an overview query with parameter
Þ Select the desired overview query (menu Maintain > Queries, tab [Query]).
Þ Enter the query with a parameter.
Þ Press [Apply]. A ‘Parameters’ section is automatically added at the bottom of the screen, see the red-outlined area below.
Þ Set the parameter options:
- Set the type to ‘Integer’ to let it match to the type of a table ID field.
- Check ‘Edit in element’ to be able to assign values to the parameter on the query content element.
- Check ‘List’ to be able to assign more than one value to the parameter on the query content element.
Connecting an options table to a parameter
The goal is to let the Editor choose from a list of options for the ‘place’ parameter at the Query content element. The options in the list can be obtained from another table from the database.
Þ Click ‘Connect to table’ (or ‘Edit table’ if a table already exists).
Þ Enter the name of the table and the names of the ID and name fields. Press [Apply].
Þ Press [Close]. You can now select a default value for the parameter. This list is also available with the query content element now.
Defining a query content element with parameter
After defining the overview query, you can place the content element ‘Query’ on a page.
Þ Navigate to the desired page.
Þ Select menu Insert > Overview > Query to place the content element.
Þ From the upper pull-down list, select an overview query that includes a parameter and save. A parameter pull-down box is added to the content element.
Þ Select one or more parameter values on which you want to filter your view.
If you selected ‘Use search pop-up’ (see 3.2.3 Connecting an options table to a parameter), the following screen pops up when setting the locations on the query element:
Showing the overview with parameters
The result only shows records in which the location is Amsterdam or Nijmegen:
Overview with link to detail view
Introduction
In this section, first we define a detail view and then from an overview we set a link to it. A detail view is defined by three query types:
- Get information query.
- Get query
- Search query
Get information query
This query is used to retrieve all the details of one specific record (the record that was clicked on in the overview). The record is identified by a parameter that is referred to as ‘@dbid@’ and which is typically used in the WHERE clause. When you click on a link of a specific record in the overview, the ‘@dbid@’ parameter gets the ID value of the record after which the query is executed. In our example, we use the following query:
SELECT whPerson.lastname,
whPerson.prefix,
whPerson.firstname,
whPerson.telephone
FROM whPerson
WHERE whPerson.id=@dbid@
Get query
This query is used to retrieve the title of the detail view. This title is typically shown in a larger font on the page. The query must contain an ‘id’ and a ‘name’ in the SELECT clause. In our example, we use the following query code:
Search query
This query is used to retrieve data for search functions that are present in XperienCentral itself. The query must contain an ‘id’ and a ‘name’ in the SELECT clause. In addition, it needs a ‘@search@’ parameter in the WHERE clause. In our example, we use the following query code:
Defining a detail view
Þ Select menu Configure > External databases.
Þ Enter the queries and define other settings, like presented in the screenshot below.
Linking an overview to a detail view
In our basic overview example, we add a link from the ‘Last name’ field to a person’s detail view. However, to be able to link to a detail view, an integer field with the unique record ID must be present in the SELECT clause. Any other type of ID than an integer type of field will not work.
So, in our overview the overview query code will be:
SELECT whPerson.lastname, whPerson.prefix, whPerson.firstname,
whPerson.email, whPerson.id AS personid
FROM whPerson
ORDER BY whPerson.lastname
This record ID field must be selected in the ‘Columns settings’ as well. More than likely, it is not the intention to show this integer field at the website. So, we set it to ‘Do not show’.
Þ Select the desired overview query (menu Maintain > Queries, tab [Query]).
Þ Under ‘Column settings’, add a column for the record ID field and check ‘NT’ for ‘Do not show’.
Þ Under ‘Column settings’, for the field to be linked, click ‘New link’ (or ‘Modify link’ if a link already exists).
Þ From the ‘Field’ pull-down list, select the ID field (in this example ‘personid’).
Þ From the ‘To’ pull-down list, select the desired detail view. Press [Save].
Þ Press [Close]. The overview query looks like this:
Defining a query content element with detail link
After defining the overview query, you can place the content element ‘Query’ on a page.
Þ Navigate to the desired page.
Þ Select menu Insert > Overview > Query to place the content element.
Þ From the upper pull-down list, select an overview query that includes a link to a detail view.
Showing the overview with link to detail view
In the example below, the upper part shows the overview. The lower part is the detail view, which appears after clicking the last name ‘Groot’.
Note: The default presentation is used here. A different-looking detail view can be created by changing the JSP. Explanation of this falls beyond the scope of this document.
Using a special page for the detail view
By default, the detail view is shown on the same page as the overview. If this is not desired, because one of the views needs a different presentation, you can also place the detail view on another special page. Proceed as follows:
Þ Create the detail page by menu File > New > Page and publish it.
Þ To hide the detail page for the website navigation, navigate to the parent page and in ‘Subsequent pages’ uncheck the box ‘Show in navigation’.
Þ Select menu Configure > Web Initiative configuration, tab [Special pages]
Þ Find the name of the detail view under ‘Database pages’ and press [Search] next to it.
Þ On the pop-up window, select the page on which the detail view is to be placed and press [Apply]
From now on, the detail view is no longer shown on the overview page but on a separate detail page.
More complex example
This section just shows the queries that belong to the introductory example in section ‘1.2.1 Views on database content’. This example has the following characteristics:
- Parameter that filters on locations Amsterdam and Nijmegen.
- Link to detail view, which is shown underneath the overview.
- Three columns (Department, Job and Location) which fields are not retrieved directly from table ‘whPerson’ but indirectly through six other tables. This requires a more complex WHERE clause.
Overview query
SELECT whPerson.lastname, whPerson.prefix, whPerson.firstname,
whDepartment.name AS depname,
whJob.name AS jobname,
whLocation.name AS locname,
whPerson.id AS personid
FROM whPerson, whPersonDepartment, whDepartment, whPersonJob, whJob,
whPersonLocation, whLocation
WHERE whPerson.id=whPersonDepartment.person
AND whPersonDepartment.department=whDepartment.id
AND whPerson.id=whPersonJob.person
AND whPersonJob.job=whJob.id
AND whPerson.id=whPersonLocation.person
AND whPersonLocation.location=whLocation.id
AND whLocation.id IN (@place@)
ORDER BY whPerson.lastname
Detail query – get information
SELECT firstname + ' ' + prefix + ' ' + lastname AS fullname,
title, firstname, prefix, lastname,
whDepartment.name AS depname,
whJob.name AS jobname,
whLocation.name AS locname,
email, telephone, devicenumber, fax, mobile,
convert(char(10), birthdate, 105) AS birthdate
FROM whPerson, whPersonDepartment, whDepartment, whPersonJob, whJob,
whPersonLocation, whLocation
WHERE whPerson.id = @dbid@
AND whPerson.id=whPersonDepartment.person
AND whPersonDepartment.department=whDepartment.id
AND whPerson.id=whPersonJob.person
AND whPersonJob.job=whJob.id
AND whPerson.id=whPersonLocation.person
AND whPersonLocation.location=whLocation.id
Reference information
Database connection screen
Path: Configure -> Database Maintenance, tab [Database connections]
Field | Description |
Pull-down selection box | List of database connections. |
Delete database connection | Delete this database connection. |
Name | Name of the database connection (case sensitive!). |
Connection URL | The URL where an application can access the database. |
Driver class | Java class path of JDBC driver software. |
Username | The user name for logging into the database. |
Password | Associated password. |
Maximum number of connections | The maximum number of connections that may be established between GX XperienCentral and the database for that ‘database pool’. |
Database type | Select the database type: MySQL, Oracle, or Microsoft SQL. |
Product name | Product name of the database server, e.g. ‘Microsoft SQL Server’ |
Product version | Product version of the database server, e.g. ‘08.00.2039’ |
Driver name | E.g. ‘jTDS Type 4 JDBC Driver for MS SQL Server and Sybase’ |
Driver version | Version of the database driver. |
Tables | List of tables that are located on the database. When clicking on a table name, the field definitions of the table are shown at the right. |
2.1.2 Overview query screen
Path: Maintain > Queries, tab [Query]
Field | Meaning |
[Copy] button | Copies the current query. The copy gets the old name, preceded by ‘Copy of’. |
[Delete] button | Deletes the current query. |
Name | Name of the query that should be displayed in the selection lists. |
Title | Title that should appear above the result when the query is submitted on a page. |
Presentation | Select the ‘WM query’ here as layout to show the results of the query. The other presentations are developed for specific purposes. |
Database
| The database the query is submitted to. |
Maximum number of pages | ‘Page size’ x ‘Maximum number of pages’ = maximum number of records retrieved from the database. |
Page size
| The number of records allowed to be shown on a page. |
Show column heading
| Indicates whether column headings should be shown above the query result. |
Show row number
| Indicates whether row numbers should be shown in front of records. |
Type | Type of query: ‘Normal’, ‘Who-is-Who’, ‘Target audience’, ‘Events’, ‘Subjects’, ‘Product overview’, ‘Themes’, ‘Questions’, or ‘Documents’. Depending on the functionality present, this list can include more or fewer types.
By default, ‘Normal’ is selected here. Only ‘Normal’ belongs to the standard functionality of GX XperienCentral. |
Modify query manually | The query can be manually entered here.
Attention: Do not use SELECT *, but name the individual column headings in the SELECT clause.
Note: Enter a variable by entering a word that begins and ends with @, such as ‘@keyword@’. These variables become the parameters of the query. |
[Compose advanced query] link | If the Microsoft SQL Server is used, a table with columns can be assigned using a wizard. The SELECT statement will then be generated. |
[Preview] link | If the Microsoft SQL Server is used, the result of the query can be viewed. If parameters are used in the query, a pop-up window appears where these parameters can be entered. |
Column settings -
| A number that determines the sequence of the columns. |
Column settings - Width
| Width of the column in pixels. If no width value is entered, the browser will determine the width. |
Column settings – Query field
| Database field where the column gets its information. |
Column settings – Column name | Text that should be shown above the column on the page (if the ‘Show column heading’ is set to ‘Yes’). If this field is left blank, the content of the ‘Query field’ will be used. |
Column settings - NT | Indicates whether this column should be shown. This can be handy to still have the primary key columns available when several tables are joined. |
Column settings - Sort
| |
Column settings - Null | Indicates whether a 0 should be shown if a cell in this column is empty or if the value is 0. |
Column settings – 2DB | If ‘Sort’ is checked, indicate here whether the data should be sorted in the database. Otherwise, the data will be sorted in GX XperienCentral. |
Column settings - Delete | The column can be deleted here. |
New link/ Modify link | To create a hyperlink to a database page. Example of pop-up:
‘Field’: Select the property from the pulldown which contains the ID to the detailed view of the object. This property always has to be of the integer type. ‘To’: A selection can be made from the database pages that are defined by Configure > External databases |
[New column] button + number | Add a number of columns. |
[All fields] button | Add as many columns as there are fields in the SELECT clause of the query. |
The following fields are only visible if the query has @parameters@:
Field | Meaning |
Parameters - | A number that determines the sequence of the parameters and the headings. |
Parameters - Parameter | The name of the parameter, as it occurs in the query, but then without the enclosing ‘at’ symbols (@). |
Parameters - Description | In the case of a parameter, the name of the parameter appears here. In the case of a headline, the text of the headline appears here. |
Parameters - Type
| The data type of the parameter (‘Date’, ‘Integer’, or ‘Text’.) |
Parameters - List | Indicates whether it is allowed to enter more values for this parameter. If this option is checked, several values can be selected on the query content element:
|
Parameters - Optional | Indicates whether this parameter is optional or required.
If a parameter has no value, GX XperienCentral removes the row where this parameter is used from the query. Therefore, set this type of WHERE parts in separate rows. |
Parameters – Edit in element | Indicates whether the value of the parameter may be entered on the content element or whether the parameter is filled, based on the value in the query string. |
Parameters – Default value | The default value of the parameter if a value is not entered. |
Parameters –Add headline | Enter a new headline here. Headlines are texts that can be set on the query element between groups of parameters. This is done to enhance usability. |
Connect to table/ Edit connected table | This allows connecting a parameter to a column from a table to show a list of selections on the query element. Example:
|
Parameters - [Delete] button | Only present if a headline exists. Deletes the headline. |
2.1.3 Detail query screen
Path: Configure > External databases
Field | Description | |
Select | List of database page models (detail views). | |
[Delete] button | Delete this database connection. | |
Description | Name of the database page that should be displayed in the selection lists. | |
Database | List of database connections. | |
Presentation | Select ‘WM Details’. This is the default value in GX XperienCentral.
Other values (such as ‘WM Agenda’, ‘WM Person’, and ‘WM Product’) are added to the list if certain functionalities are imported in GX XperienCentral. | |
Value | A unique value used by the search engine for indexing. | |
Get information query | This is the query to be run if the detail view has to be displayed. This query is connected with @dbid@ to the record that was clicked through.
The variable @dbid@ contains the primary key in the table and can be used to retrieve the correct record.
Example: SELECT employee_name, salary, commission FROM employees WHERE employee_id = @dbid@ | |
Show settings - | A number that determines the sequence of the columns to be shown. | |
Show settings – Query field | Name of the column in the SELECT clause. This can be a column name or alias (behind the keyword ‘AS’). | |
Show settings – Column name | Text that should be shown above the column on the page (only if the ‘Show column heading’ is set to ‘Yes’). If this field is left blank, the content of the ‘Query field’ will be used. | |
Show settings – Don’t show | Indicates whether this column should be shown or not.
This can be handy to still have the primary key columns available when several tables are joined. | |
Show settings – Always index | A column that is not shown is not indexed by default. To index this column, a check mark can be placed here. This setting is, however, ignored if ‘Index for search’ is set to ‘No’. | |
Show settings - Delete | The column to be shown can be deleted here. | |
Show settings - [New column] button + number | Add a number of columns. | |
Get query | Query to retrieve the title of the database object. This title is shown on the page in a larger font. The query has to contain an ID and a NAME in the SELECT clause. | |
Search query | The search query is used in two places:
The query has to return an ID and a NAME and can use the ‘search’ parameter to find the proper records in the database. An example: SELECT whPerson.id AS id, whperson.lastname AS name FROM whPerson WHERE lastname LIKE '%@search@%' | |
Link query | Using this query, the links related to this table can be retrieved from a specially created link table.
The ‘Link query’ is only used for the product catalog and for meetings that have been created in the ‘Meetings and Papers’ component. | |
Index for search | Indicates whether this type of page should be indexed and, therefore, be shown in the search element. | |