Understanding the query list

Contents 1 Introduction 2 Facile forms query list creation 3 Settings tab 4 General settings 4.1 Title 4.2 Name 4.3 Ordering 4.4 Published 4.5 Include in logs 4.6 Position X and Y 4.7 Width 4.8 Rows per page 4.9 Page navigation 4.10 Show header 4.11 First column mode 4.12 Border and cell settings 5 Css class 6 Query tab 7 Columns tab 8 Header settings 8.1 Title 8.2 Css class for <th> 8.3 <th> span 8.4 Attributes 9 Data settings 9.1 Name 9.2 Css class for <td(1)> and <td(2)> 9.3 Width 9.4 Attributes 9.5 Value 10 To sum up

Introduction

What is a query list and what does it do?

Put simply a query list is exactly what it says, a list created from a database query. Essentially the query list is an html table with all the settings of a normal table except the rows have been filled by the data in the database instead of being input manually.

A query list can be a very powerful tool allowing you to customise the way data is displayed, for instance you could place your own custom html table within a row to display the data how you wish instead of just rows and columns. You can also place images within rows to replace the written data such as a one or zero, which may mean yes/no or on/off.

A common use of a query list is to display data about someone or something at a glance just the basic information such as name, age and gender, if you want to find out more you can use a couple of methods to enable the query list to do this. The first is making one of the table columns into a radio button or check box allowing you to select the row required and pass that data to a form containing more information or you can use a url to pass a parameter to another form instead, for more advanced concepts of the query list see Understanding the query list (Advanced).

Facile forms query list creation

Facile forms breaks the creation process into three simple stages..

• Settings tab (General and css settings)
• Query tab (The database query)
• Columns tab (Column settings)

Settings tab

Within the settings tab you can set all the general settings of the list plus customise the look and feel to suit your own site by using css, because of this I will explain the settings tab in two parts, firstly general query list settings and secondly the css settings.

General settings

Title

An obvious one this but make sure you give a title that describes the query list accurately and you wont have problems identifying it later.

Name

The name you give to the query list is important it will be identified by this name in future.

Ordering

Sets the position of the form element within the form element list.

Published

Sets the form element published status to yes or no.

Include in logs

This option should be set to yes if you wish submitted data to be saved to your database.

Position X and Y

Positions the query list element within the form using x y coordinates.

Width

Sets the width of the query list element.

Rows per page

Sets the number of rows to display per page of the query list, for example you have a table with eight records and you set rows per page to four you will have two pages as long as you have page navigation active, see below.

Page navigation

This works in conjunction with rows per page and controls the way paging will look in the table footer.

It is important to remember that using paging will not make any difference to performance, all the data from the query will be loaded when the form or page loads meaning very large tables could exceed php execution time.

Show header

Shows or hides the header row of the table.

First column mode

This allows you to change the first column of your table to either check boxes or radio buttons instead of normal text data, this will not add an extra column to the table just replace the first column data with a checkbox or radio button.

When the first column is set to checkboxes or radio buttons the value of the column is still held so when you select a row its value will be returned, this method works best for id but could be use with other columns such as name.

Border and cell settings

Set table border width, cell spacing and padding.

Css class

For those of you that are new to css and joomla/mambo the css document referred to is the css in your website template.

With all FF form elements you will be given at least one option to use css class but for a query list you get a few more allowing you to change the look and feel of the table. All FF form elements will allow you to add a css class for the element <div> below is a css example to set how text will be displayed within the form element <div>.

 .ffdiv {
        font-family: Tahoma, Verdana, Arial, Helvetica, sans-serif;
        font-size: 12px;
        color: #ffffff;
        }

To use the css simply type 'ffdiv' for the <div> css class, easy and it works for all css class options.

The extra css options you get with the query list are..

• <table>
• <tr(header)>
• <tr(data1)>
• <tr(data2)>
• <tr(footer)>
• <td(footer)>

I think its obvious which parts of the table are effected except perhaps the class for <tr(data1)> and <tr(data2)>, these are used to show alternating row effects such as alternating background colours or images, for example..

Class for <tr(data1)>

.sectiontableentry1 {
        background-image: url(/images/shade1.gif);
        font: Tahoma, Verdana, Arial, Helvetica, sans-serif;
        height: 25px;
        font-size: 11px;
        color: #ffffff;
        }

Class for tr(data2)>

.sectiontableentry1 {
        background-image: url(/images/shade2.gif);
        font: Tahoma, Verdana, Arial, Helvetica, sans-serif;
        height: 25px;
        font-size: 11px;
        color: #ffffff;
        }

Called as explained previously using 'sectiontableentry1' and 'sectiontableentry2' its that simple but very effective for customising your table look and feel.

Query tab

Here you are invited to 'Create code framework' if you do this you will see the following code..

global $database;

$database->setQuery(
    "select id, name, username, email ".
    "from #__users ".
    "order by id"
);
$rows = $database->loadObjectList();

This is a pretty standard query that you will be easily able to adapt for your own use, the example queries the users table of your joomla/mambo database. It is very important that the query is saved to the '$rows' variable, if you change this no data will be returned.

The data that the variable '$rows' holds is an array where each element contains a data structure containing all used columns of the query.

Another method and more user friendly..

// load the standard form creation utilities
$this->execPieceByName('ff_InitLib');

//query db
$rows = ff_select("select `id`, `name`, `username`, `email` from `#__users` order by id");

Standard form creation utilities is a library of functions or pieces that can be called using $this->execPieceByName('ff_InitLib'); we need this to use the piece called ff_select.

See Understanding Pieces and Scripts for more information

You can place any php code you like within the query tab as long as it fills the '$rows' variable. It is worth noting because of this you do not really need a query at all, if you wish you could determine the contents of the '$row' variable manually.

Please note you do not need to include the php tags and to avoid using echo as it creates odd results, use return instead.

Columns tab

This is where you set up the columns of the table you can create a new column, copy a column or delete a column.

Header settings

Title

You must provide a header title as this will be displayed in the table header for the specific column.

Css class for <th>

You can set the css class for the header using the method I have explained already.

<th> span

Set the number of table columns spanned (Defaults to 1).

Attributes

Column header alignment options.

Data settings

Name

You must provide a name for the column which must match the database column of the same name, otherwise no data will be displayed.

Css class for <td(1)> and <td(2)>

This works the same way as explained for <tr(data1)> and <tr(data2)> except on a column basis which makes the table even more versatile.

Width

Sets the width of the column either in pixels or as a percentage value.

It is possible for the width to be set to zero, if you do this the column will be invisible however the value of that column could be used in another column of the same table row.

Attributes

Column alignment options.

Value

This will default to..

<?php return $value; ?>

This will show the value of the column as set by the database query.

As with the query tab you can use any php code you like but you must use php tags in this case, this would be where you would place any custom code you may wish to use as I explained in the introduction.

To sum up

Facile forms allows you to create a great looking query list table that is highly customisable using css without having to know lots about php, it also allows for more experienced coders to use custom code in key areas of the query list.

I hope I have gone some way to explaining the features of the query list in greater detail.

--Boldee 19:16, 21 May 2008 (CEST)