Document Actions

FilterForm

by lgs — last modified 2005-11-11 22:47

Class that allows easy creation of search forms

Introduction

This class allows to create a page that can send asynchronous queries to the server and displaying the results as a table in the same page. To use if effectively you have to do some previous setup:

Create a web page with a form and give it an id. Example: searchForm
In the same page create an empty div where you want to display the results. Give it another id. Example: resultsArea
Create a server side script/procedure/function/whatever that can handle the queries and reply to them in XML format. See the section Server side to know the details.
Create an instance of FilterForm in your <head> section and register its rules in Behaviour. Finally add a load event with the init method of your FilterForm.

Example of use:

      var columns = ['F. Alta', 'Titulo', 'U', 'E', 'Tecnico', 'F. Res.'];
      var filterForm = new FilterForm('filter', 'results', columns, 'buscarIncidenciasHandler');
      Behaviour.register(filterForm.getBehaviourRules());
      Behaviour.addLoadEvent(filterForm.init.bind(filterForm));

Aditional features are a navigation toolbar and permalink support.

Public API

FilterForm(formId, resultsId, columns, queryUrl)

Constructor. Creates an instance of FilterForm and initializes its internal state. Note that you still need to call the init method in order to make it work properly. But you should call that method only when the body of the page is completely loaded. The arguments of the constructor are:

formId: id of the form that contains the filter fields
resultsId: id of the container used to display the results of the queries
columns: array with the column titles that will be used in the table of results
queryUrl: url of the server method that will be called to get the query results

FilterForm.init()

this method collect all the editable fields of the form. They will be used to compose the query arguments. It also makes the initial query. It is very important for this method to work that the page is fully loaded. To acomplish it this method is usually called from the onload method of the <body> element.

FilterForm.KEY_DELAY

this constant defines the minimun interval of time that must occur before a query is sent to the server. It is useful if you call the requery method each time the user press a key in an input field. This avoid overloading the server. Its default value is 500 milliseconds.

FilterForm.getBehaviourRules()

get a rules array ready to use for the Behaviour object. Basically it says that every time a <select> element changes or a character is modified in a <input> element, the requery method is called.

FilterForm.requery()

call the sendQuery method grouping several requests that were made in a short period of time (KEY_DELAY)

FilterForm.sendQuery()

make an AJAX request to the query URL collecting all the values of the form and composing a URL with the arguments that will be sent using the GET method. It returns false so it can be used from the onclick event of links and the page won't get reloaded.

Server side

The server should give a response with the results of the query in the following format:

    <?xml version="1.0"?>
    <queryResult>
      <navigation>
        <total></total>
        <offset></offset>
        <amount></amount>
      </navigation>
      <data>
        <register>
          <field></field>
          <field></field>
          ...
          <field></field>
        </register>
        ...
        <register>
          <field></field>
          <field></field>
          ...
          <field></field>
        </register>
      </data>
    </queryResult>

As you can see the main section is called queryResult and inside this section there is a navigation and a data section.

The navigation section contains exactly three sections:

The total number of objects that match the query criteria
The offset of the first register that this response contains
The amount of registers that this response contains

The data section contains zero or more register sections depending on the number of objects that matched the query criteria and the amount of objects requested. Inside each register section there are one or more field section that surround the actual data. A field section can have a link attribute if we want that data to be a link that points to the value of this attribute.

This HTTP response should have a content type of text/xml.

Documentacion de SICEm

Sections

Personal tools

Document Actions

FilterForm

Introduction

Public API

Server side