Testing database integration

In this topic we show you how to check that Arcos and your database work correctly together.

Before following these steps, ensure that you have set up a database.

To test database integration

  1. Modify the configuration file so that it contains the following XML:
    <Configuration>
       <FileInclude File="configuration.database.xml"/>
       <FileInclude File="configuration.pages.xml"/>
    </Configuration>
    
    For convenience, we will include files in the configuration file, rather than using one large configuration file. The included files can be called anything, provided that the file extension is .xml
  2. Create the configuration.database.xml file in the /config directory. The file should contain the following XML (explained later):
    <Configuration>
       <Database Name="website" Type="postgres" Source="localhost" Login="website"
                        Password="website" Verify="1" Modify="1">
          <Table IntTableName="tblFriends" DBTableName="tblfriends">
             <Field Name="FriendID" Type="sequence" Caption="Identifier"/>
             <Field Name="Name" Type="string" Size="80" Caption="Name"/>
             <Field Name="Tel" Type="string" Size="20" Caption="Telephone Number"/>
             <Field Name="Email" Type="string" Size="50" Capton="Email Address"/>
             <Index Name="primary" Field="FriendID"/>
          </Table>
       </Database>
    </Configuration>
    
    
  3. Create the configuration.pages.xml file in the /config directory. The file should contain the following XML (explained later):
    <Configuration>
       <Page PageName="listFriends">
          <DataSource Name="tblFriends">
             <SYS_Recordset_GetAllRecords />
          </DataSource>
    
          <SYS_Display_Template TemplateFile="LOCAL_listFriends">
             <SYS_AutoTemplate_RecordList ComponentName="tblFriends"/>
          </SYS_Display_Template>
       </Page>
    </Configuration>
    
  4. Open a browser and type the URL of the listFriends.html file. The URL consists of the base URL followed by the file name (you do not need to type the .html extension).
  5. The page should appear. If it does not, or if any error messages appear, refer to the "Troubleshooting" topic.

Explanation of configuration.database.xml

In this, and following explanations, we do not explain things that have been dealt with in previous explanations.

We explain only the properties that are used. For a full explanation of all the relevant properties, see the Built-in tag reference.

Note. To make your XML more readable, you can use white space and line breaks. You can insert comments in the code using <!-- and --> to enclose the comment.

<Database Name="website" Type="postgres" Source="localhost" Login="website" Password="website" Verify="1" Modify="1">

Use the Database tag to specify the properties of a database that Arcos will access. The Name, Type, Login, and Password attributes are self-evident; the values match our sample database.

Source. This attribute specifies that the database resides on the local machine.

Verify is a flag that specifies whether or not Arcos should check whether your specification and the physical database match. Modify is a flag that specifies whether or not Arcos can make changes to the structure of the database. When you develop a web site, we suggest that both these flags are set to 1.

<Table IntTableName="tblFriends" DBTableName="tblfriends">

If the table already exists in the database, use the Table tag to tell Arcos of its structure. If the table does not exist, use the Table tag to instruct Arcos to create the table.

IntTableName. This is the internal name known to Arcos. Use anything that is convenient for you. The name does not need to be the same as the table name known to the database application.

DBTableName. This is the name of the table as it is known to the database application.

<Field Name="FriendID" Type="sequence" Caption="Identifier"/>
<Field Name="Name" Type="string" Size="80" Caption="Name"/>

Use the Field tag to specify each field in the database (if a field does not already exist, Arcos can add it to the table if the Modify flag is set to 1). For existing fields, the order specified here does not need to match any implied order in the table. Arcos matches the fields purely on an equivalence of names.

The order of the fields here determines the order of display on all the web pages that use this Table definition. You can change the order using templates and layouts, which is useful if you want different orders on different pages.

Name. The name of a field in the database.

Type. Specifies the field type. Use Sequence for unique key fields.

Size. The size of the field. If the user will input data, this specifies the maximum number of characters (bytes) that can be input. Not used for field type "sequence".

Caption. The field name that will appear on the web page.

<Index Name="primary" Field="FriendID"/>

Use the Index tag to specify an index on the table. It has the following properties:

Name. The name of the index. This can be anything except "primary", which is a reserved word, and is used only to identify the primary index (Primary Key in SQL terms).

Field. The name of the index field. It is possible to specify an index that is composed of more than one key (see Index built-in tag).

Explanation of configuration.pages.xml

<DataSource Name="tblFriends">

Use the DataSource tag to create a datasource that you can use on the web page that you are defining.

Name. This is the name of the recordset that is used by the datasource. Arcos automatically creates a recordset for each table, which has the same name as the table. This means that you do not need to define a recordset (but be aware that even though we use "tblFriends", Arcos treats this as a recordset).

<SYS_Recordset_GetAllRecords />

This is a pre-defined component. The full name of the component is K_Component_SYS_Recordset_GetAllRecords. When you specify a component, you omit the K_Component_ part. This component retrieves all records for the table. For a list of all components see Reference, components.

<SYS_Display_Template TemplateFile="LOCAL_listFriends">

The first of these three lines tells Arcos to use the local template called "listFriends". Compare this SYS_Display_Template tag with the one we used previously, which did not need a closing tag.

<SYS_AutoTemplate_RecordList ComponentName="tblFriends"/>

This is an autotemplate that just lists all the records in a recordset. Here, it lists all records in the recordset called "tblFriends" (recall that Arcos creates a recordset with the same name as the table.) Since we are using an autotemplate, we do not need to write a template. When the page is requested, Arcos automatically creates a template called listFriends.html and puts it in the config/template/auto/ directory.

You can modify an autotemplate by copying it to the config/template/directory. Make the required modifications. When the page is called again, Arcos uses your template, not the autotemplate that it originally created.

When you request the web page, you will see that for each record, each field is on a different line. For a more compact format, in which all the information for a single record is on one line, use the SYS_AutoTemplate_RecordColumnList tag.