Adding data editing and search functionality to your application

From Morfik Wiki

This article will provide you with a general overview of how to maintain data in your application/website. Up to this point we have seen how to create the user interface, but now we are going to look at how to add and edit the data that drives this application. It is important to note that the features described in this topic depend on portions of server-side code from the Morfik Framework, and are thus not available in Morfik Browser Application projects.

Managing content

In our current CMS application example we have aimed to build a user interface that appears normal to the site's visitors despite the extensive employment of Ajax. In this article, maintaining a 'normal' appearance is not our concern as we will be addressing behind the scenes, author and admin tasks using as much of the Morfik Framework's built in functionality as possible.

Everything that we are going to see in this topic lies behind the authentication barrier of our application. The user authentication process is fundamental in making sure that unauthorized users cannot alter your website’s content. Only after the users sign-in will they be allowed to see the link which will take them into the site management section of the application.

Figure 1 highlights the Site Management link which is always visible in the website’s footer. This link takes authenticated users into what might seem to be an entirely different website from the portions which are publicly accessible. The general layout remains the same since, in fact, we are only changing which two Forms are displayed in the two SubForms of the Index Form.

Once the user chooses to enter Site Management, the displayed content in the LeftArea SubForm changes to the AdminSideBar Form and in the MainArea SubForm it changes to the EditSections Form.

Figure 1: The "Site Management" link in the application's footer.

The AdminSideBar Form which handles navigation within the Site Management portion of the MorfikCMS project is actually a simplified version of the SideBar Form used in the public section of the application. AdminSideBar is a fully static Form with no database binding of its own. Though it looks quite similar to the SideBar Form, it employs common buttons instead of the TextLabel + Container scheme used in the SideBar Form. This is because this portion of the website is more focused on practicalities than design.

Figure 2 shows the AdminSideBar Form. Notice that the color scheme is different from the one used in the SideBar Form due to the different nature of the controls.

Figure 2: The AdminSideBar Form in design mode in the Morfik Workspace.

On entering Site Management the EditSections Form is displayed in the MainArea SubForm because "Sections" is the first option to appear in the list of the AdminSideBar Form (Figure 3). This change makes it clear that the user has entered the Management portion of the application.

Figure 3: Initial view of the Site Management portion of the CMS project.

The data editing Forms

The CMS application project will have four data editing Forms within its "Site Management" area: EditSections, EditArticles, EditUsers and EditSiteInformation. All these Forms are automatically generated through the "Create New Form" Wizard and then customized to achieve the effect we desire.

We will go through the customization of the EditSection Form in more detail. The remaining Forms were modified the same way, except for the EditSiteInformation Form which requires handling of a table which always has a single record, and so needed a unique approach to customization.

The EditSections Form

As previously mentioned the EditSections Form was automatically generated through the use of the "Create New Form" Wizard and then customized. Changes were only slight; the more obvious customization of Title and images in the Header band are totally cosmetic. These have no effect on the usage of the Form except to show more clearly which data is being edited.

Figure 4 shows the EditSections Form in design mode in the Morfik development environment.

Figure 4: the EditSections Form in design mode in the Morfik Workspace.

In Figure 5 you can see the EditSection Form at runtime in the Morfik Debug Browser.

Figure 5: The EditSection Form at runtime in the Morfik Debug Browser.

This basic Form is all we really need in order to create and edit sections for the website. The Navigator which can be seen in the Footer band of the Form takes care of all the necessary functions for navigating the records, editing and updating the underlying database. We make extensive use of this feature in all the data editing Forms in the CMS application project.

The EditSections Data Source

The EditSections Form is directly bound to the Section table allowing access to all the records in the table. This is a simple and immediate approach which is easily implemented through the use of the Morfik "Create New Form" wizard.

The EditArticles Form

We have seen how to build the EditSections Form; we will go into more detail with the 'EditArticles and demonstrate how to customize the automatically generated Forms..

Figure 6 shows the EditArticles Form in design mode in the Morfik development environment. The "Create New Form" Wizard automatically suggests the appropriate controls for the date fields. Once we have configured, as we did for the EditSections form, it will generate ComboBoxes for the SectionId (indicated by the "Section" TextLabel)and CreatedBy Fields.

Figure 6: EditArticles Form in design mode in the Morfik development environment.

The next customization is much more important as it allows us to introduce a Morfik Framework feature that is quite useful in creating data entering and editing forms: the data lookup capabilities of ComboBox control.

Choosing control type in the Wizard

When running the "Create New Form" Wizard you can select which types of controls will be created for each of the table fields to which you have selected to bind your Form. It is important to choose the correct type of control in order to provide the best possible experience to the end user.

Figure 7: Option to automatically add controls the Form being created.

Once you choose to automatically add controls to the Form you can use the "Customize" button to specify which controls will be used for each field. This option will bring up the dialog box shown in Figure 8.

Figure 8: Changing the type of a control through the popup menu.

In Figure 8 you can see the control selection for the Id field of the Article table. Since Id is an AutoNumber field and thus automatically handled by the database it should be displayed in a TextLabel control so that the user cannot alter its value.

The default control suggestion for The SectionID field is a TextEdit control which, though usable, does not meet with our requirements for usability since it requires that the user have previously looked up the value of the Id Field of the Section under which he wishes to place his article. This control type should then be changed to being a ComboBox control.

Even after the Form is created by the Wizard, the ComboBox control is not yet ready to be effectively used. The ComboBox's Lookup Data binding properties must be set in order for it to work effectively.

Figure 9: Configuring the Lookup Data properties of the ComboBox bound to the SectionId field of the Article table.

Immediately after the creation of the Form by the wizard, only the DataField property is set to bind the control to the underlying field in the database. We need to manually reconfigure the LookupDataSource to choose where the data will come from, the LookupDataField which is the information we want to copy onto our bound DataField and LookupTextField, which is the field whose values we want to display in the ComboBox control for the user to choose from.

In this specific case we want to display the titles of the sections and once the user has chosen one, store the value of its Id field in the current record's SectionId field. Properties should be configured as shown in Table 1.

Note that in Table 1 we list the value of a property that was not previously mentioned: LookupMaxRecords. This property controls the maximum number of records that will be fetched from the database to populate the dropdown list of the ComboBox. In this case: 50 records.

Since these are topic groups, 50 might be a sufficiently large quantity. If you feel you might have websites with a larger number of sections then this value should be appropriately adjusted to reflect your needs.

Once the Form is created the Lookup data properties of the two ComboBox controls need to be set to bring up information from the Section table—exactly as done in the EditSections Form—and to bring up data from the UserCatalog. The FullName field will be used in the LookupTextField property so that the users’s full names are displayed in the corresponding dropdown list.

The EditArticles data source

Analogous to the EditSections Form, the EditArticles Form is directly bound to the Article table allowing access to all the records in the table. This is a simple and immediate approach which is easily implemented through the use of the Morfik "Create New Form" wizard.

The EditUsers Form

The EditUsers Form is very simple in nature since the table on which it is based is also a simple one. It only requires one customization apart from adding the Title and accompanying images to the Header band of the Form, and this is to configure one of the TextEdit controls for password display by checking the IsPassword property in the Property Window. In this case, the control will only display small circles in place of actual characters when the user types in a password.

Figure 10 shows the EditUsers Form in design mode in the Morfik development environment and Figure 11 shows the same Form at runtime in the Morfik Debug Browser.

Figure 10: The EditUsers Form in design mode in the Morfik Workspace.

Figure 11: The EditUsers Form at runtime in the Morfik Debug Browser.

Note in Figure 11 that the Password field is displaying placeholders instead of the actual characters.

The EditSiteInformation Form

The EditSiteInformation Form is a special case within our content maintenance Forms because it is bound to a table which always contains a single record.

Since there is always only one record, there is no reason to have an Id Field visible. After the Wizard created the Form that TextLabel was made invisible. You can see the EditSiteInformation form in design mode in the Morfik development environment in Figure 12.

Figure 12: The EditSiteInformation Form in design mode in the Morfik development environment.

Note that the NavigatorBar in the Footer Band of this form has been configured to show only the Refresh, Submit and Edit buttons to prevent this Form from adding new records to the underlying table.

Figure 13: The EditSiteInformation Form at runtime in Internet Explorer.

The EditSiteInformation Data Source

Analogous to the EditSections Form, the EditArticles Form and the EditUsers Form, the EditSiteInformation Form is directly bound to the WebsiteInfo table allowing access to all the records in the table. This is a simple and immediate approach which is easily implemented through the use of the Morfik "Create New Form" wizard. The fact that the WebsiteInfo table has a single record does not require any specific action to make the EditSiteInformation Form work perfectly. The only customization necessary is, as previously discussed, a configuration of the NavigationBar so that it does not display any buttons that are not necessary.

Adding search capabilities to a Form

Morfik and the Morfik Framework offer several ways to work with database searches in ways that are almost transparent. Every time we use a stored query as a data source for our Forms we are using the database's intrinsic search features. These features allow a visitor to websites managed by our CMS application to navigate through the site’s content down to the single article level.

We are now going to see a very simple, and totally codeless, way of adding simple search and filtering capabilities to our application. In order to do this we are going to go back to the EditArticles Form and add a new button to its NavigationBar: the Filter button.

This little button is all we need to add to the Form in order to add search and filtering capabilities to it. When the Filter button is clicked it clears all the data-bound controls and places the Form into a sort of data entry mode. While in this mode, you can type in text for each of the fields you would like to filter the data source by. When you click on the button a second time, the filters you have typed in become effective and the data set is filtered. To clear the filter you should click on it once to present a clear filter entry mode and then a second time so that that mode takes effect.

Figure 14: The Search/Filter menu in the NavigatorBar of the EditArticles Form.

In Figure 14 the Filter button is highlighted in red. Clicking on the "Filter" button clears the contents of all fields and the user can type search terms into the corresponding TextEdit controls.

Figure 15 shows data a user has entered in the TextBox control bound to the Title field of the Article table. Once the filtering criteria have been typed in all that is necessary is to click on the "Apply Filter" option of the menu button.

Figure 15: The EditArticles Form in "Filter by Form" mode.

Note that once the "Apply Filter" option is selected the Form displays only the records that match the criteria. Observe in the highlighted portion of Figure 16 that the NavigationBar indicates record 1 of 1.

Figure 16: The EditArticles Form with a filter set for articles with the word "packages" in the title.

This is because with the filtering activated, the Form only sees the one record in the table which does have the word "packages" in its Title field. This feature allows the developer to quickly add filtering and basic searching into an application without writing a single line of code.

In the CMS application sample project the Article table seems to be the only candidate for a search feature as it is the only table which should have a large number of records.

Editing data without a NavigationBar

Up to this point we have seen how to edit information without writing any code, through the use of a NavigationBar. We will now take a quick look at how to edit some of the content of the website, one record at a time.

Filtering data from a table

When we are just displaying data, we can work with all variations of Queries to get exactly the data we want; however, when we are going to alter the data we must work with a table. In order to limit the data which is going to be presented to the user to a specific record we must use a filter. In this case this is done through the use of a single line of code, instead of through the visual interface of the NavigationBar’s Menu button.

Using a filter is quite simple and follows closely what we have been doing with the queries. In this case, however, we must manually create the parameter in the Form in which we will filter the data.

The EditOneArticle Form

In our current sample application we will be filtering the data presented by the EditOneArticle Form. We must manually declare the appropriate parameter and then write the necessary code in the OnReady event, which is triggered when the form completes loading in the Browser. Figure 17 shows the parameter list for the EditOneArticle Form with the added parameter at the end.

Figure 17: Parameter list of the EditOneArticle Form.

The following code snippet contains the entire event handler for the OnReady event of the EditOneArticle Form. It is quite simple—only a single line of code.

Procedure EditOneArticle.WebFormReady(Var Ready: Boolean);
Begin
  ChangeFilter('"Id"='+ParamId);
End;

Published Message Sub WebFormReady(ByRef Ready As Boolean)
     ChangeFilter("""Id""=" & ParamId)
End Sub

published message void WebFormReady(ref Boolean Ready)
{
     ChangeFilter("\"Id\"=" + ParamId);
}

This single line event handler forces the filtering of the records from the Form’s data source as described in the filter expression. In this case the data source for the Form is the Article table.

Figure 18 shows the EditOneArticle Form open as popup for editing the record corresponding to a specific article. Note how everything outside the EditOneArticle is now dimmed. Anthing outside the Form cannot be directly accessed, thus simulating the behavior of a modal dialog in Windows.

Figure 18: The EditOneArticle Form as a popup.

Instead of using a NavigationBar, which can display update controls, we are always dealing with a single record in the EditOneArticle Form and only need two normal buttons to confirm or cancel the changes. The following code snippet contains the event handler for the SubmitBtn button which confirms the edit of the data and sends the modified data back to the server.

Procedure EditOneArticle.SubmitBtnClick(Event: TDOMEvent);
Begin
  UpdateRecord(Event);
  SubmitPage(Event);
  OpenForm('ViewOneArticle', 'Index:MainArea', '"ParamId=' +
                  Control_Id.Caption +'", "openmode=refresh"');
  Close;
End;

Published Message Sub SubmitBtnClick(Event As TDOMEvent)
     UpdateRecord(Event)
     SubmitPage(Event)
     OpenForm("ViewOneArticle", "Index:MainArea", """ParamId=" + 
                     Control_Id.Caption + """, ""openmode=refresh""")
     Close()
End Sub

published message void SubmitBtnClick(TDOMEvent Event)
{
     UpdateRecord(Event);
     SubmitPage(Event);
     OpenForm("ViewOneArticle", "Index:MainArea", "\"ParamId=" + 
                     Control_Id.Caption + "\", \"openmode=refresh\"");
     Close();
}

The following code snippet is the entirety of the event handler for the CancelBtn button which cancels any changes made to the record currently being edited.

Procedure EditOneArticle.CancelBtnClick(Event: TDOMEvent);
Begin
  CancelRecordChanges(Event);
  Close;
End;

Published Message Sub CancelBtnClick(Event As TDOMEvent)
     CancelRecordChanges(Event)
     Close()
End Sub

published message void CancelBtnClick(TDOMEvent Event)
{
     CancelRecordChanges(Event);
     Close();
}

Both of these event handlers close the Form. The event handler for the SubmitBtn button commands the re-opening of the ViewOneArticle Form showing the article currently being edited, forcing its refresh since the data will have been modified.

Wrapping it up

In this article we have seen that only minimal coding is required to provide the end-user/visitor to your website with simple data entry and editing functionality, as well as searching and filtering capabilities.

The Morfik development environment and the Morfik Framework provide a solid base on which to build data management applications that are intrinsically simple to use.

Related Topics

• How is data managed in my application?
• Defining data schema for your application
• Binding data to your application user interface
• Writing code for data manipulation
• Built-in Database SQL Statements - Quick Reference