This tutorial will take you through the steps to create a custom module using the EasySite Content Management system. The idea is to create way for users to submit data through a form, and have the data saved to the EasySite database. Then, we also need to be able to search the resulting data, edit or delete the data, and display the data in a logical, well-formatted way.
So what is our "data" for this tutorial? Let's create a system for real estate agents and customers. The agents (brokers, etc.) will be the ones who add properties for our real estate module, and the customers - i.e., the people who want to buy properties - are the ones who will search these listings. This can all be accomplished using a combination of EasySite's "form" and "report" tools.
Here's a summary of the steps that we'll take:
1. Create a form using the form tool for the real estate listings.
2. Test this form by saving the results to the database.
3. Create a simple report to show the submitted data in a clear, well-formatted
manner.
4. Create a search form to allow our customers to easily navigate the data.
In this tutorial, I will skip some of the details of how the form is created. Use the form tool to create a multi-field form with fields for: Steet Name, Unit, County, Zip Code, and any other address information that you would like to associate with your property listings. You're also welcome to add drop-down lists. There is one important thing to note about using the lists tool. The left-side of the lists tool contains the actual values which are used by the system, and the right side contains the labels which the user sees. It's important that the left side contains only numeric values, if the field is numeric. Punctuation and special characters should be omitted.
For example, in the screenshot below, I've created a list to represent the cost of the properties. Since costs are measured in dollars, I wish to display the "$" symbol, with commas, in the list. This is fine for the right-side of the list, which is what the user sees. But for the left-side, only pure numbers should be used, since this is what the system is going to read for purposes of data comparison, and special symbols like $ like cause problems. Also, please note that there is an exact, one-to-one correspondence between the right- and left-side data. For the first row of the list, it usually makes sense to have "- Select .... -" on the right, with a "0" or empty string on the left, as shown below.
Since we are using this form as a data submission form, the "Generate submission reports" option in the form manager must be checked. With this option checked, we will be able to create reports from our saved submission data. Depending on the version of EasySite that you are using these options might be in the Form Settings.
At this point, we can start adding fields to our form. In this example, I want to create a form for residential properties, so I have named this form "New Listing - Residential". Please note that when adding a "Select/List" field type, you should choose a list that you created with the Lists tool. Also, you should be careful about the field types. For example, if you need to represent a date, it is much better to use the "Date" field type, rather than the text field type. This is because Date types are searchable in a numeric manner, but text fields are not searchable numerically - in other words, if we wish to later create a search form to view all properties posted after or before a specific date, this can only be done if the field is a Date field.
Finally, it would probably be useful to have a few images associated with each property, so that customers can get a preview of what the property looks like. In addition, it would be useful to allow a file upload also, since it's sometimes necessary to attached PDF floorplans to the property, or other information about the property. For this reason, let's add a few image fields to the end of the form. In the screenshot below, I'm showing the last image field that I added, with an attachment field.
Finally, to preview your form, click on URL link located at the top of the forms tool. The purpose of this link is to allow you to get an instant preview of the form. It's also so that you may, if desired, use this link embedded in various places throughout your system. For example, you might wish to put this link in a Page Section (page manager tool), or even reference it from other website entirely.
You should notice that when previewing your form, the lists automatically become drop-down menus, and image/file fields contain "Browse..." buttons for uploading files. Also, Date fields automatically become Month / Day / Year drop-down menus.
You'll recall, in the previous step, we checked the "Generate submission reports" option while creating our form. Let's test that now by viewing our report, and submitting it a few times. The screenshot below shows some sample data being submitted using this new form. To load the form, you can either use the URL in the form manager, or link the form to a menu item, and then click on the menu item to load the form.
After submitting a few times, open the form manager to this form, and then click View Report to see that the submissions were successful. This is useful to "spot check" the form submissions, to ensure that the data is being correctly saved. Please note that this link will NOT be used during the actual report creation process... for that, we will use the much more powerful Report system. This link is only for quick viewing of the report data. As you can see, image uploads have been converted to small thumbnails, and uploaded files have been converted to "Download" links.
Ok, now let's get to the meat of this tutorial... we have a form that we can save to the database, but how do we "pretty up" the submission data so that it's presentable to the general public? The answer is the Report tool. Please note that basic HTML knowledge is necessary for this tool. The better your HTML, the nicer your report will look.
First, open the Report tool and create a new report based on the form that you created in step 1. Here's what your screen might look like after this step. Of course, you will base your report on whatever you named your input form. Be sure to save your report, and give it a clear name.
We should also specify how we'd like the data to be sorted. For this example, let's sort by the posting date, with the newer posts coming first. That way, when a user performs a search of the data, they will be able to quickly see the most recent listings. Click on "Add New Sort or Group", then choose to sort by one of the Date fields that you added to your report, like Listing Date. In this example, I chose "Descending Numeric" because dates are treated numerically by the database. Descending, when dealing with dates, means "most recent first". When dealing with integral numbers, it means "9 to 0", and when using letters, it means "Z to A".
Now that we have the sorting in place, let's actually add some data to the body of the report. This is the actual listing data which visitors to the site will see. Click on the "Edit Layout" option, then choose the "Advanced HTML Layout" option in the "Report Layout" combo list. Please note that the fields which appear in the screenshot below might be different from those that exist in your form! The words in curly braces { } indicate a form field which you can add directly to your report layout.
For my example, I used the HTML shown below to create a very simple, 2-column layout. The left-side column contains address information for the properties, while the right-side column shows the image (Image #1) for the property, along with a download and 'Map It' link to MapQuest. When using URL links like the one below, be sure to enclose the http:// address in double quotes so that spaces can be accomodated.
<table border=0 width=400>
<tr><td valign=top>
<table class=normal cellpadding=0 cellspacing=0 width=200>
<tr><td><b>{Street #} {Street Name} {Unit #}</b></td></tr>
<tr><td>{City or Region}</td></tr>
<tr><td>Bedrooms: {Bedrooms}</td></tr>
<tr><td>Bathrooms: {Bathrooms}</td></tr>
</table>
</td>
<td align=center>
{Image #1}<br />
<a target=_blankhref="http://www.mapquest.com/maps/map.adp?country=US&countryid=US&searchtype=address&address={Street
#}+{Street Name}&city={City or Region}&state=CA">Map It!</a>
</td>
</tr>
</table>
Your screen will probably look something like this:
When the report is run this time, it looks a lot nicer with the HTML formatting....
You can also add a simple HTML report header and footer, for example copyright information, page title, etc.
Finally, we need to create a search form for our report, because it's not very useful if users have to sort through thousands of records every single time that they want to find something. To do this, we'll create a new form, and designate this form as the search form for our report.
There are two very important aspects to this new form. First, the "Use as a search form..." option is checked, and the report that we previously created is selected. Next, you'll notice that the "Redirect To" option points to the report which we just created. This means that a user will open this search form, and upon submission, the report of residential listings will show. However, the data that will be displayed will depend on the user's inputs in the form! (thus, it's a "search" form). Note the red arrows below...
Ok, now we have to create the search form. Most likely, you'll want to allow the user to search on several possible fields. For example, you might wish to allow the user to search only for listings posted between certain dates, or perhaps only listings within a certain city or price. For this example, a very simple search form with only 4 fields is used, as shown below (this is what the form looks like when run):
It's important to remember that the field types MUST match. Thus, if you wish to search by # of Bedrooms, and # of Bedrooms is a "select" list, then in your search form, it must also be a select list of the SAME list (from the Lists tool). Likewise for Date fields. You may create as many search forms as you wish for any report.
Now, we must tell the system how the search is to be performed on the report. For this, we will use the "Report Filter Overrides" option in the form manager. Load the search form that you just created, and open this tool. Then, use this tool to tell the system how to map the search form fields to the report fields. Here's the logic behind this:
1. We want to match the city/region exactly, so use "="
2. We want to show all records with AT LEAST as many bedrooms as the user specifies
in the search form, so use ">="
3. We want to show all records with AT LEAST as many bathrooms as the user specifies
in the search form, so use ">="
4. We want to show all records that are AT LEAST AS RECENT than the date specified
in the search form, so use ">="
Now, when you submit this search form, you should see only the report data which matches the filters.
We're all done! We have a form which allows searches, and a form which allows data input. The data is displayed in a nice format using EasySite's powerful report system.