Tutorial3: Introduction to using Tables

 

Documentation home

Introduction. 1

Instructions 1

 

See also:       All Tutorials, Tables, Controls, Form Editor 

 

Introduction

 

In this tutorial we will create a form containing a table. We assume that you have some familiarity with using the Ebase Xi Designer. If not, you are recommended to start with the tutorial Building your First Form.

 

We will build a small application for maintaining a CD collection. It will support the following functions:

 

 

This application will make use of the following database tables which are included in the Ebase Samples Database:

 

  1. MYCDS

this is the main CDs table

  1. CD_CLASSIFICATIONS

main classifications e.g. Popular, Classical, Jazz etc

  1. CD_SUB_CLASSIFICATIONS

sub classifications within the main classification

 

Note:

These three tables already exist in the database EBASE_SAMPLES provided with Ebase Xi.

If you need to create the EBASE_SAMPLES database yourself scripts can be found here: <Ebase_Installation_directory>\UfsServer\databaseSchemas

 

Instructions

 

Check Designer Preferences

Open the Designer Preferences Dialog by selecting File > Preferences from the menu and click the Page Editor tab. At the bottom of the page, check Page Navigation Panel Control. This ensures that the control is added to all new pages. This can be reversed at the end of this exercise, if required.

 

Import the database tables

 

  1. If the Tutorials project doesn’t already exist, create it by right clicking in the tree panel and selecting New > Project, then link the new project to the ebaseSamples project (right click on the project name, then select Properties).
  2. Create a new folder for the tutorial: right click on the Tutorials project and select New > Folder, name the folder Tutorial3.
  3. Select Tools > Resource Wizards > Database Resource Wizard from the menu at the top of the designer window to start the database import wizard.
  4. Click the button to the right of Select Database Connection and select EBASE_SAMPLES from the list. (Database connections are created and maintained using the Server Administration Application).
  5. Click the button to the right of Select the target location for the resource(s) and select the Tutorial3 folder in the Tutorials project. Then click Next.
  6. If you are using Apache Derby (the default), Oracle or SQL Server for the database system, you will need to select the EBASE_SAMPLES schema from the next screen and click Next again. 
  7. Then select the tables CD_CLASSIFICATIONS, CD_SUB_CLASSIFICATIONS and MYCDS (hold down the Ctrl key for multiple selects) and click Next again.
  8. In the next panel click the Tables Only checkbox for the MYCDS table and click on CD_ID in the Columns for Where Clause column, then uncheck CD_ID in the pop-up window and click OK. (This removes the CD_ID column from the where clause for the Database Resource which means we will retrieve all CDs.)
  9. Click Finish to create the resources. The system will create the three Database Resources and open the last one (MYCDS).
  10. Open the CD_CLASSIFICATIONS Database Resource by double clicking on the name in the tree panel.

 

Build the classification dynamic list

This list will be used to classify a CD.

 

  1. Click the Build Dynamic List icon  on the toolbar at the top of the panel and click Next to accept the default name CD_CLASSIFICATIONS_list
  2. On the next window - Create Where Clause, don't select anything, simply click Next
  3. On the final window - Select Fields From Database, select the CLASSIFICATION field and click Finish

 

Build the sub-classification dynamic list

This list will be used to further classify a CD.

 

  1.  Open the CD_SUB_CLASSIFICATIONS Database Resource by double clicking on the name in the tree panel
  2. Click the Build dynamic list  icon, click 'OK' when the warning message appears, and accept the default name CD_SUB_CLASSIFICATIONS_list by clicking Next
  3. On the next window - Create Where Clause , select field CLASSIFICATION and click Next
  4. On the final window - Select Fields From Database , select the SUB_CLASSIFICATION field, then Finish

 

Create the form and set up table display

 

  1. Right click on the Tutorial3 folder in the tree panel, enter New > Form and name the form Cd_Exercise
  2. Click the form properties icon  on the form toolbar at the top of the page, select the Presentation tab, then click the button to the right of the Presentation Template property and select the xiDefault template from the ebaseSamples project
  3. Add the MYCDS Database Resource to the form: in the form editor select the Resources View (usually in the top right-hand corner), click the Add Resource icon  and select the MYCDS Database Resource
  4. In the Tables View, click the New Table icon, select MYCDS from the resource name dropdown list, enter table name cds (over-typing the generated name of MYCDS), then click the Import columns from resource button.
  5. Click Select All in the pop-up window. Then click OK twice.
  6. Drag the cds table from the Tables View onto the page (drag the cds name next to the table icon ), adding it to the Page.

 

In the Outline View, you can see that this has created a Table Control, a Table Page Control and a number of Table Column Controls. The Table Control represents a visible table, a Table Page Control represents a horizontal scroll page within this table (in most cases there is only one of these), and the Table Column Controls represent columns.

 

  1. Delete the cds-REVIEW and cds-DESCRIPTION column controls – by selecting them in the Outline View and press the Delete key
  2. Re-order the columns in the Outline View by dragging them to the order shown below (or any other order you prefer).
  3. Select the Table Control - click on the <no table header set> text then change the following properties in the Properties View:
  4. Select Show Add Row button
  5. Select Show delete column
  6. set No. visible rows to 20 (this change is not visible in the designer – it always shows 3 rows)

 

Hint: initially, these properties are taken from default values configured in the Presentation Template associated with the form.

 

  1. Click on the Toggle designer view icon   on the WYSIWYG View toolbar – this shows the page as it will actually appear in the browser. Before this, the page display was operating in assisted mode where the system makes some small changes to make the design process easier. We can see that the table is too wide and overflows the page – this is because the lengths for the individual columns are too large and exceed the percentage width specifications we have assigned. Maximise the WYSIWYG View by double clicking on the Title Bar – this contains text Page Page_1 on a light blue background. There still isn’t enough space to display the table. Double click the WYSIWYG Title Bar again to return to normal.
  2. To correct this problem, select the table columns in the Tables View one by one, and change the Display Length property in the Properties View (Presentation section) as follows:

 

 

Column

Display Length

cds-ARTIST

25

cds-CLASSIFICATION

10

cds-COMPOSER

15

cds-RATING

1

cds-SUB_CLASSIFICATION

10

cds-TITLE

40

 

  1. Set the CD_ID column display only by right-clicking the CD_ID column in the WYSIWYG View and selecting Display Only.
  2. Click on the Toggle designer View icon  on the WYSIWYG View toolbar again to return to the assisted display.

 

 

Add database integration

Add a script to load the table from database:

  1. Click the table header text <no table header set> to select the Table Control, then right click and select Events, select the Before Table tab (it should already be selected) then click the Script builder wizard icon .
  2. Set Target Folder to the Tutorial3 folder in the Tutorials project (this should be the default)
  3. Set Language to Javascript
  4. Select load a table from resource, click OK.

 

This will create a script to load the table. Click on the Cd_Exercise form in the open items toolbar at the top of the window to return to the form editor. 

 

Add an update table button and a script to perform the updates:

 

  1. Drag a Button Control from the Palette (section General) and add it after the table
  2. Double click on the button in the WYSIWYG View and change the text to Update CD database.
  3. Right click on the button, select Events, then click the Script builder wizard icon .
  4. Set Target Folder to the Tutorial3 folder in the Tutorials project (this should be the default)
  5. Set Language to Javascript
  6. Select update resource with table contents, click OK.

 

This will create a script to update the table. Click on the Cd_Exercise form in the open items toolbar at the top of the window to return to the form editor. 

 

Add a script to assign each new CD a sequence number

 

  1. Select the Table Control, then right click, select Events and click the Add Row tab. Then click the Create new script icon , enter script name addCd, set the Location to the Tutorial3 folder in the Tutorials project and  Language to Javascript. This will create a new script named addCd and open the script editor. Cut and paste the code below into the script window after the existing importPackage statements.

 

tables.cds.CD_ID.value = system.sequenceManager.sequence("CDS");

 

When this script is executed for the first time, the system will create a sequence and start numbering from 1.

         

Set up the classification lists

 

  1. Classification – this is a simple list that shows a list of main classifications
  2. Sub-classification – this list is more complicated: it shows a list of sub-classifications within the main classification. The list is re-built each time the main classification list is changed.

In the Tables View select the cds-CLASSIFICATION column and change the following properties in the Properties View

 

  1. Click the cds-CLASSIFICATION column in the WYSIWYG View and check the Immediate Validation property (Table Column Control section). This means that the server is contacted each time this list is changed, and will result in the rebuilding of the sub-classification list.

 

Test the form

 

  1. Click the run form icon  on the form toolbar.
  2. Click the Add Row button a few times and add some test data. Observe the behaviour of the classification lists.
  3. When you are ready, click the Update CD Database button.
  4. Now re-run the form and the entered CDs should be displayed.

 

Final touches

 

  1.  Set some of the columns as mandatory by holding down the CTRL key then clicking on the column header texts for columns cds-ARTIST, cds-TITLE and cds-CLASSIFICATION. Then right-click and select Set Mandatory.
  2. Enable sorting on cds-CD_ID, cds-ARTIST, cds-COMPOSER and cds-CLASSIFICATION. Click the column header for each of these fields and set the Sortable property. Sort icons are displayed on the right-hand side of the column header text. When we run the form, clicking these icons will sort the table by the appropriate column. Repeating the sort then acts as a toggle to sort in ascending or descending order and the sort icon changes correspondingly.
  3. Sort the initial display by cd id in the database resource. Open the MYCDS Database Resource by double clicking on the name in the tree panel, then add order by CD_ID to the Additional SQL statements box. (We could also achieve the same result by sorting the table using a script). Enter Ctrl S to save the Database Resource or click the  icon on the toolbar.
  4. Return to the form editor by clicking the Cd_Exercise form  in the open elements toolbar at the top of the page.
  5. Add some header texts: double click the table header text - <no table header set> - and enter 'My CD collection'. If you like, enter some instructions in the table info text by double clicking on this. You can also change the column header texts by double clicking on these.
  6. Add validation to the rating column to ensure that any entered number is between 1 and 5. Select the cds-RATING column in the Tables View, double click opposite the Validators property, enter '1' in Inclusive Min. value and '5' in Inclusive Max. value.
  7. Delete the Page Navigation Panel Control at the bottom of the page
  8. Re-run the form and check this new functionality performs as expected. Try selecting the cds Table Control and setting the No. visible rows property lower than the number of CDs in the table. You will then see the default scrolling header panel displayed when you run the form.

 

Optional Further Enhancements

Adding a reviews button column

We'd like to have a button on each row which, when clicked, shows another page which allows the user to enter a review of the CD. This could be done as follows:

 

  1. Select the cds-REVIEW column in the Tables View and change the following properties:

·         Display type property to Text Area,

·         Display length to 60

·         Number of rows to 15.

 

  1. Add the review page

 

  1. Add the review button column to the table

 

  1. Add a script to the new button to send the user to page ReviewPage:

 

form.gotoPage(pages.ReviewPage);

 

·         Save the script.

 

  1. Return to the form editor by clicking the Cd_Exercise form in the open elements toolbar at the top of the page.
  2. Right-click on the new button column, select Events, then click the Add Scripts button and add the gotoReviewPage script.
  3. Re-run the form and check everything performs as expected. Enter some reviews and verify that they are recorded against the correct CD.

 

Making the table searchable

 

  1. Add the input search field

 

  1. Add the DB Search fields

 

  1. Add the script for triggering the search

 

fields.searchFieldForDb.value = "%";

if ( fields.searchFieldInput.value )

{

  fields.searchFieldForDb.value += fields.searchFieldInput.value + "%";

}

tables.cds.fetchTable();

 

·         Save the script.

·         Return to the form editor by clicking the Cd_Exercise form in the open elements toolbar at the top of the page.

·         Right-click on the Search button, select Events, then click the Add Scripts button and add the applySearchCriteria script.

 

  1. Edit Database Resource MYCDS

 

  1. In the Resources View, select the MYCDS Database Resource, then click the  icon on the toolbar to display the mappings.

·         Map the resource field searchFieldForDb to form field searchFieldForDb.

·         Map the resource field whereClause to form field whereClause.

·         Click OK.

 

  1. Re-run the form and check everything performs as expected.

 

So far we have introduced searching the artist column. We could search on all columns by extending the process above.

 

For more information on database resources and Dynamic SQL see the Database Resources documentation.