Morfik Database Guide - Editing and Searching Data
From Morfikwiki.com
This topic 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 end-user/visitor’s point of view. Now we are going to have a look at how to add and edit the data that drives this application. This topic describes functionalities which are not available in Morfik Browser Application projects. 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.
Contents |
[edit] Managing Content
In our current example, MorfikCMS, we have made some effort to make sure that the end-user/visitor’s view of the content looked like a normal website, despite Morfik’s employment of Ajax everywhere. In this part of this guide maintaining this "normal" website look will not be goal, instead we are going to address this task directly, using as much of the Morfik Framework’s built in functionality as possible.
Another topic in this documentation has already covered the user authentication process for the MorfikCMS project. This process is fundamental in making sure that unauthorized users cannot alter your website’s content, so all that we are going to see in this topic lies behind the authentication barrier of our application. That means that 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 appears in the site’s footer once the user has been authenticated. This link takes the user 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 quite simplified version of the SideBar Form we are using 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, since this portion of the website is more focused on being practical than in design.
Figure 2 shows the AdminSideBar Form. Notice that the color scheme is a bit different from the one used in the SideBar Form due to the different nature of the controls used.
Figure 2 – The AdminSideBar Form in design mode in Morfik Workspace.
On entering Site Management the EditSections Form is displayed in the MainArea SubForm is displayed in the MainArea Form because "Sections" is the first option to appear in the list of the AdminSideBar Form as seen in Figure 2. In this case it is obviously better to display that view than it would have been to maintain the original content which would have been displayed in MainArea since this way it is very clear that the user has entered the Management portion of the application. Figure 3 shows the initial view of the "Site Management" portion of the application.
Figure 3 – Initial view of the Site Management portion of the MorfikCMS project.
[edit] The Data Editing Forms
The MorfikCMS project will have 4 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 lightly customized to achieve the effect we desire.
We will go through the customization done to the EditSection Form, in more detail, to explain what was done and to what effect. The remaining Forms went through exactly the same customization steps, except for the EditSiteInformation Form which requires a slightly different approach due to the unique situation of handling a table which should always have a single record.
[edit] The EditSections Form
As previously mentioned the EditSections Form was automatically generated through the use of the "Create New Form" Wizard and then slightly customized. The more obvious customization which is the Title and images in the Header band is totally cosmetic and has no effect on the usage of the Form, except to make clear to the user what the data which is currently being edited is.
The next customization much more important since it allows us to introduce a Morfik Framework feature which is quite useful in creating data entering and editing forms: the data lookup capabilities of ComboBox control.
Figure 4 shows the EditSections Form in design mode in the Morfik AppsBuilder Workspace. Notice that the last control in the Form is a ComboBox, right besides a TextLabel control which reads "Parent Section".
Figure 4 – the EditSections Form in design mode in the Morfik Workspace.
[edit] 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.
Figure 5 – 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 which is shown in Figure 6.
Figure 6 – Changing the type of a control through the popup menu.
In the picture shown in Figure 6 you can see the control selection for the Id field of the Section table. Since Id is an AutoNumber field and thus automatically handled by the database it was decided that it should be displayed in a TextLabel control so that the user cannot alter its value.
As can be seen in Figure 6 the default control suggestion for The ParentID field is a TextLabel 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 another Section. This control type should then be changed to being a ComboBox.
Once 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 7 – Configuring the Lookup Data properties of the ComboBox bound to the ParentId field of the Section 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 then to manually reconfigure the LookupDataSource to choose where the data lookup 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 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 records ParentId field so we’ve configured these properties as shown in table 1.
| Table 1 – Data related properties for the ComboBox | |
| Property | Value |
| DataField | ParentId |
| LookupDataField | Id |
| LookupDataSource | Section |
| LookupMaxRecords | 50 |
| LookupTextField | Title |
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 which 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 than this value should be appropriately adjusted to reflect your needs.
In Figure 8 you can see the EditSection Form at runtime in the Morfik Debug Browser.
Figure 8 – The EditSection Form at runtime in the Morfik Debug Browser.
The ComboBox control for editing the ParentId field can be seen with its dropdown list visible in the screenshot that is shown in Figure 8. As can be seen from this example the ComboBox control can be extremely useful in editing fields which relate one table to another. We make extensive use of this feature in all the data editing Forms in the MorfikCMS project.
[edit] 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 AppsBuilder "Create New Form" wizard.
[edit] The EditArticles Form
Since we have discussed all the specific detail on how to customize the automatically generated Forms in our discussion of the EditSections Form, we will just quickly mention what customizations were done to the EditArticles Form.
Figure 9 shows the EditArticles Form in design mode in the Morfik AppsBuilder Workspace. The "Create New Form" Wizard automatically suggests the appropriate controls for the date fields and once we have configured, as we did for the EditSections form, will generate ComboBoxes for the SectionId (indicated by the "Section" TextLabel)and CreatedBy Fields.
Figure 9 – EditArticles Form in design mode in the Morfik Workspace.
Once the Form is created it the Lookup data properties of the two ComboBox controls need to be set as to bring up information from the Section table, exactly as done in the EditSections Form and to bring up data from the UserCatalog table where the FullName field will be used in the LookupTextField property so that the users’ full names are displayed in the corresponding dropdown list.
[edit] 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 AppsBuilder "Create New Form" wizard.
[edit] The EditUsers Form
The EditUsers Form is very simple in nature since the table on which it is based is, also, a simple one. Only one special customization, apart from adding the Title and accompanying images to the Header band of the Form is required which is to configure one of the TextEdit controls for password display. In this case, the control will only display small circles in place of actual characters when the user types in a password.
This ensures that a person with access the site management area of the website can change a user’s password but cannot read the previously registered one.
Figure 10 shows the EditUsers Form in design mode in the Morfik AppsBuilder Workspace 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.
In order to configure the TextEdit which is bound to the Password field to mask its content all that is needed is to check the IsPassword property in the Property Window.
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 from the field’s contents.
[edit] 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.
In this Form, since there is always only one record, there is really no reason to have an Id Field visible so after the Wizard created the Form that TextLabel was made invisible. You can see the EditSiteInformation form in design mode in the Morfik AppsBuilder Workspace in Figure 12.
Figure 12 – The EditSiteInformation Form in design mode in the Morfik Workspace.
Note that since this Form should not be able to add new records to the underlying table the NavigatorBar in the Footer Band has been configured to show only the Refresh, Submit and Edit buttons.
Figure 13 – The EditSiteInformation Form at runtime in Internet Explorer.
[edit] 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 AppsBuilder "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 which are not necessary.
[edit] Adding Search Capabilities to a Form
Morfik AppsBuilder and the Morfik Framework offer us several ways to work with database searches in almost transparent ways. Every time we use a stored query as a data source for our Forms we are using the databases intrinsic search features. These features allow us the end-user/visitor to websites managed by our MorfikCMS project to drill down through the site’s content down to the single article level.
Now we are 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 menu 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 menu button is clicked it displays a small popup menu with three options: Filter by Form, Apply Filter and Remove Filter.
Figure 14 – The Search/Filter menu in the NavigatorBar of the EditArticles Form.
In Figure 14 the Filtering menu is highlighted in red. Clicking on the "Filter by Form" option the contents of all fields are cleared and the user can type whatever they want to search for, in the corresponding TextEdit.
Figure 15 shows a user entering data for filtering in the TextBox 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 which 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 "PHP" in the title.
This is because with the filtering activated the Form sees only the one record in the table which does have the word "PHP" in its Title field. This feature allows the developer to quickly add filtering and basic searching into an application without actually writing a single line of code.
In the MorfikCMS sample project, considering the data load that each of the tables will probably have in an average website, only the Article table seems to be a candidate for a search feature as it is the only table which should have a large number of records.
[edit] Editing Data Without a NavigationBar
Up to this point, in this chapter, 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.
[edit] 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. When we are going to alter the data we must work with a table, however. 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 actually 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.
[edit] The EditOneArticle Form
In our current sample application we will be filtering the data presented by the EditOneArticle Form. As just mentioned in this case 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, which is quite simple: one single line of code.
Procedure EditOneArticle.WebFormReady(Var Ready: Boolean);
Begin
ChangeFilter('"Id"='+ParamId);
End;
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. Everything 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.
In the EditOneArticle Form as we are always dealing with a single record, instead of using a NavigationBar, which can display update controls, two normal buttons were used 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;
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;
Both of these even 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.
[edit] Wrapping it up
In this chapter we have seen that providing the end-user/visitor to your website with simple data entry and editing functionality, as well as searching and filtering capabilities can be achieved with minimal coding.
The Morfik AppsBuilder Workspace and the Morfik Framework provide a solid base on which to build data management applications which are intrinsically simple.
