Ajaxtable Documentation

1. Warning
2. What is Ajaxtable
3. Installation
4. Why Ajaxtable?
5. Simple Example
6. Full example
7. Input example / Overriding table declaration functions
8. Using the calendar input
9. Other Input Column Types
10. Edit and Delete Columns
11. Theming
12. User Edit and Delete Columns
13. Theming
14. The cluetip.js file
15. Ajaxtable Parameters
16. Search Input Parameters
17. Column Parameters
18. Input Column Parameters

Warning (top)

Warning: A couple of the examples below all you to edit a node via AJAX, including a node delete function. Please exercise caution when using these. There will be a dialog that pops up asking you if you really want to delete the node, but please be careful! I would suggest only enabling the docs module when you are testing. Make sure you back up the database if you're not sure.

What is Ajaxtable (top)

Ajaxtable is a Drupal module that provides an API to generate ajax-sortable and searchable tables based on simple parameters. The module also provides a tool for replacing an input box with a searchable table. It works like an autocomplete field, but with the table view you can have pagination, multiple search parameters, and sorting.

Ajaxtable was developed to provide an alternative to certain uses of Views and the Autocomplete field, thought it does not replace either one.

Installation (top)

After downloading ajaxtable, you will need to update jquery.js in the drupal /misc folder. As of right now, the jQuery-update module will get you to 1.1.4, but the patch for 1.2 hasn't been committed yet. This means that you need to copy the jquery.js in the ajaxtable folder and paste it into the Drupal misc/ folder, which will overwrite the old one. There may be some problems with this, but I haven't run across any yet. The jquery-update module adds some fixes that should smooth the transition.

Why Ajaxtable? (top)

Speed

Ajax-based tables load faster than standard page refreshes. When tracking down a particular record, it can be time consuming to go through several page requests. If you need to re-sort, select a new page, and then possibly do a search to narrow down the records further, you'll be spending at least 15-20 seconds on page reloading. With an ajax-based table, you're looking at a few seconds, max.

Look and feel

How the resulting table is rendered is based completely on themes. Themes are completely CSS-based, so virtually any style of rendering is possible. Themes can be added on the module level, if your module's tables needs their own look and feel, and they can be overridden in a table declaration function.

Simple Example (top)

To generate an ajaxtable, you need two parts: 1) The table declaration function, and 2) a call to that function. In this example, no parameters are specified, which means that all parameters are set to the default value.

To create a table declaration function, you need to create a function name that starts with "ajaxtable_table_" and ends with a unique ID. It is a good idea to prepend your ID with your module name to insure there are no conflicts with other modules. So, or example:

And to render the table, you need to use the ajaxtable_render($id) function, where $id is the unique id you set for your table.

This would result in the following table:

Full example (top)

In this example, we're using most of the parameters so you can see the effects.

Input example / Overriding table declaration functions (top)

You can an axaxtable to replace an input in a form. This requires jQuery 1.2 or higher, since it needs the "replaceWith" jquery function.

To replace an input, you need to do 3 things 1) create a table declaration function like in the above example, 2) add an "input_name" parameter to the table declaration function, 3) one of the columns need to have the parameter "input_value" set to TRUE, and 4) add a line in your module's hook_form_alter() function, and 3)

To demonstrate this example, we will be overriding the table in the previous example. This implementation is useful to reuse the same parameters of one ajaxtable and override select parameters. An override specifies the new parameters, then calls the function for another table.

Notice that there is a parameter called "input_name". This is the value of the "name" attribute for the input you want to replace. You can find this by looking at the code of the rendered form. Also, in the previous example we set the "input_value" parameter on the "nid" column, which doesn't do anything unless it is called to replace an input. Instead of re-setting all of the columns in this override, we're setting it in the previous table' function, which then passes it to the input version.

Next, we need to call the code to actually replace the input with the ajaxtable table. Note that this has only been set up for a text input. In this example, we set the theme to "input", which displays a text input that looks similar to other form inputs, which will auto-generate the table using the phrase in the box, similar to an autocomplete input.

To replace the input, we will add a line to our module's hook_form_alter() function, as in the following which would replace the "title" input with our search input as specified in in the ajaxtable_example3 example (note that you would replace the "ajaxtable_form_alter" with "mymodule_form_alter"):

The input should end up looking like this:

A couple things to note about how Ajaxtable handles the input:

• Ajaxtable replaces the text input with a table that uses radio buttons instead for the value. The radio buttons will display in a column that will be added automatically to a table which has an "input_name" parameter set.
• When used as an input, ajaxtable will hide the table when called on a form with a blank input. If the form has a posted value or default value, ajaxtable will display a table with the radio button in that row already selected.

Using the calendar input (top)

Using the calendar search input or column input requires the JS Calendar maodule, which is part of the jstools module. Here's an example:

Other Input Column Types (top)

Ajaxtable can handle other kinds of input columns, as seen in the following example:

Edit and Delete Columns (top)

You can easily add edit and delete columns but just setting a parameter each. In your query, just you just need to make sure that there is a value for "nid" being returned for each row. As a tip, you can use the user_access() function to set the visibility of the columns.

Adding those two parameters above will result in the following:

Theming (top)

There are two places where you can create themes. The first is in a ajaxtable_theme folder that you add to your module folder, in which case you will need to add a "theme_module" parameter to your ajaxtables. If you look in the ajaxtable module directory, you will see a folder called "ajaxtable_themes". In the folder are the two default themes, one called "default", which is a good general purpose theme, and one called "input", which is compact and good for using the table as an input.

In the theme directory, there is a "theme.php" file, which contains definitions for the theme. You can override these values in your table declaration function, as you can see in the "full" example above (ajaxtable_example2).

By adjusting the theme, you can make an ajaxtable look pretty much however you want. Lots of CSS used, and in places that require actualy HTML templating, the template.php file is used.

User Edit and Delete Columns (top)

If your query returns rows that include a uid column (for user ID), and that column is specified as the "unique" column, you can use the "user_edit" and "user_delete" parameters to add an edit button and delete box for the users. No table is included for this example for safety reasons, but you can get the idea.

Theming (top)

There are two places where you can create themes. The first is in a ajaxtable_theme folder that you add to your module folder, in which case you will need to add a "theme_module" parameter to your ajaxtables. If you look in the ajaxtable module directory, you will see a folder called "ajaxtable_themes". In the folder are the two default themes, one called "default", which is a good general purpose theme, and one called "input", which is compact and good for using the table as an input.

In the theme directory, there is a "theme.php" file, which contains definitions for the theme. You can override these values in your table declaration function, as you can see in the "full" example above (ajaxtable_example2).

By adjusting the theme, you can make an ajaxtable look pretty much however you want. Lots of CSS used, and in places that require actualy HTML templating, the template.php file is used.

The cluetip.js file (top)

The cluetip.js file consists of a function that defines how the hover-overs are displayed. If you don't have the cluetip module installed, normal titles will be used instead.

Ajaxtable Parameters (top)

Search Input Parameters (top)

Column Parameters (top)

Input Column Parameters (top)

The x's in the 'text', 'calendar', 'checkbox' and 'select' columns indicate that the parameters are available in that input column type.