The Basics: Creating a Basic Ajax DataGrid

Introduction

In this tutorial we're going to show you how easy it is to insert an Ajax DataGrid into your page. Below is an example of the end result.

The Ajax DataGrid on your page. All the settings in the first tab are also explained in the preview window of the extension.

Make sure you have defined a connection to your database before you start this tutorial.

Building the Ajax DataGrid

1. Create a new page
   Create a new or open an existing HTML, ASP or PHP page and save the page.  We create an ASP page.
   
   
2. Applying the extension
   Choose the  icon from the DMXzone object bar to apply the extension. The following  popup appears:
   
   

3. Setting the Ajax DataGrid Options
   At the HTML tab, the Caption sets the title of the Ajax DataGrid. The title is displayed at the top left of the grid. We set the caption to Classic Cars. Don't use \ in the Caption.
   
    
   
   We leave the Width to 600 so the grid is large enough and can be resized. When the Width is set to auto the grid cannot be resized. We set the Height to 550 to make it high enough for a decent amount of content.
   
   
   
   The Records per page set the number of rows per page, we'll leave it at 15.
   
   
   
   We leave the Column min. width at 30px and the Column min. height to 80px. These are the minimum dimensions of our columns.  We leave the Min. visible columns at 1 to display at least one column when the user deselects the columns in the front end (see the preview to the right).
   
    
   
   Unchecking the Auto load data is convenient when you are working with information that should be loaded consequently.
   
   
   

4. Adding your Content to the Ajax DataGrid
   Select the Content tab. Connection allows you to define what database should be used to populate the grid. Depending on if you have opened an ASP or PHP document, your connection options will differ. We have a database table called bio that we select using the drop down box.
   
   
   
   Optionally you can edit your connection string with the Edit button, we won't do this now.
   
   
   
   Select the Table to choose which table to use from the database.
   
   
   
   After that we select the Columns we want to add to our grid, we choose all Columns in our table.
   
   
   
   You can choose to Filter to filter on a specific value of one of the columns. We filter that we only want cars newer then 1938.
   
   
   
   Use the Sort option to sort on a specific field.
   
   
   
   Choose whether to sort its content by Entered Value which is a static filter or by any of the others which are dynamic filters and are activated by input after the grid is loaded in the browser. We set it to year and Entered Value.
   
   
   
   We press the Test Query button to display a preview of our data.
   
   
   
   Press OK to close the Test SQL Statement.

In the Grid Columns display, you can select any particular column and change their names using the Label option. We we'll leave the Labels at their default value. You can assign formatting properties to its contents from the Format menu.  The AlphaCase options allow you to convert the string to either Lower or Upper case; First Letter Upper capitalizes only the first letter of all words in the string, and Capitalize converts the first letter of the given string to upper case. With the Trim option, you can remove any spaces on the Left, Right or Both sides of the string. Convert – New Lines to BRs converts newline characters to HTML BR tags

The HTML Encodе option for Encode is needed under the following conditions:
HTML has special handling for characters like < and > symbols, so it doesn't work well with those characters where they shouldn't be. This can all be fixed by 'escaping' those characters. This process replacing them with a special character-code that browsers can interpret as the correct symbol, without actually embedding that symbol in your text. For example, the escaped character code for > is &gt;.

The URL Encode option for Encode is needed under the following conditions:

URL links can be made up of only certain characters and a "space" for example cannot be used. Instead,  URL Encode replaces those spaces or unrecognizable characters with ones it recognizes like "%,+, $, etc."

Encode - Raw URL Encode returns a string in which all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits. This is the encoding described in » RFC 1738 for protecting literal characters from being interpreted as special URL delimiters, and for protecting URLs from being mangled by transmission media with character conversions (like some email systems). Decode - URL Decode decodes an URL-encoded string. Decode - Raw URL Decode returns a string in which the sequences with percent (%) signs followed by two hex digits have been replaced with literal characters. HTML - Strip HTML removes all HTML tags and leaves plain text only.

We set the Format to None.

For a PHP document with MySQL connection, the formatting options are significantly more extended than in an ASP document although it is possible to write your own code and by inserting it into the Site/ajax_servers/custom_lib.php file get additional options.

Width sets the Width of the column, we'll leave it at 100. This width excludes the padding and margins that are used in your table, so the full cell width will be a little bit bigger (for example 112 pixels).



Align allows you to set how the data in the column is outlined, we set it to Left.

We want to display the photos in our database as images rather then a text that list the path, to do this we select the photo column and enter <img src="images/rez/ in the Content Before field. We enter " width="80/> in the Content After. The images tag together with the path to the images will make sure the images will be displayed while the width specifies the width of the images.

The Images are now displayed in our grid:

You can enable or disable the sorting of columns by checking or unchecking the Sortable checkbox. We leave it checked.

 

Optionally you can hide columns by default using the Hidden option. We leave it unchecked.

Define whether a column should be searchable or not by checking or unchecking the Searchable option. We leave it checked.  Note that you need to check the Use pager option in the Details tab to use this option. We make all our fields searchable.



If you have more then one Searchable column, you can use the Default Search Field option to specify if the default column that will be searched on. We do this for the year column.



Set the Primary Key to the column that holds a unique identifier for its record. We set it to ID.



Attaching a behavior to a cell allows for additional actions, effects, and links, to name a few, to be executed when a cell is clicked or double clicked for example. We won't specify this now but we'll explain this in another tutorial further on in the manual.

You can use the  to sort the order of the columns. We'll leave the default order.

Setting the Details options
The Details tab allows for DataGrid fine-tuning as it relates to the visual output.  As you click each option, the Preview on the right shows what it pertains to with a red outline.



We check the Apply odd even stripes field to highlight our alternate rows.



Check the Vertical stripe field to highlight the sorted column.



We check the Resizable field to enable the resizing of our columns. You need to set an exact with and height for this option to work.



We select Nowrap to make sure our text is not cut off.

We enable the Use pager option to include a navigation bar to browse to our content. It's also necessary to turn it on to enable the search trough columns we enabled earlier.



We check the Show Toggle Grid Button to display the button on the right top side of the table.



We also check the Use results per page selector field to enable the user how many records should be displayed per page.



We enable the Show "Choose columns" Popup checkbox to allow the user to select which columns he wants to display.



Display Errors lets you choose whether you want errors to be displayed

The option, Initially Show Search Bar displays the search bar when the grid loads, without additional clicking.

Floating Search Bar keeps the grid from resizing when the search bar is displayed. It just shows up on top of the contents.

Results look like this:

Checked Floating Search Bar Option

Unchecked Floating Search Bar Option

Row Behaviors allow you to add Behaviors to the rows in addition to Cell Behaviors which we won't use now but are explained in a separate chapter.



We set leave the Opacity while loading of our grid at 0.5 to make the grid half transparent while it's loading.



The Results Per Page Options allow you to control the allowed choices for the results per page menu

Setting the Translation options
The Translation tab allows translation of the menus in other languages (supports UTF8 scripts) as well as customization of the wording of the text. As you click each option, the Preview on the bottom shows what it pertains to by highlighting it.

The Status test (on Connection Error) is the text that shows up only if a connection error occurs. You can rewrite the message in your own words or language if you choose.

The Status text (default) is the descriptive text that shows up on the bottom right as default.

The Status text (while processing) option lets you change the message the user sees while the data is loading.

You can edit the text displayed if there are no search results with the Status text (if no results) option.

The Text before the pager option lets you change the word before the page numbering.

The Text after the pager option lets you change the word after the page numbering.

The Search Field Label option lets you change the text that appears before the search field.

The Search Button Label allows you to customize the text that appears on the Search button.

The Clear Button Label allows you to customize the text that appears on the Clear button.

If you want to change the tooltip that appears at the Toggle Grid Button you can enter your own text in the Toggle Grid Button Tooltip field.

If you want to change the tooltip that appears at the Hide/Show Columns button you can enter your own text in the Hide/Show Columns Tooltip field.

Press OK to generate the grid. The result should be similar to the one displayed below: