TODO

################################################################################
#                        Structures_DataGrid TODO File                         #
################################################################################
CSV file id: $Id$

Remarks about this file : 
- each entry should be separated by a "-" line
- each entry should have a title formatted as :
  TODO <number> - <summary> (<pear user name>) - Priority: High|Medium|Low
- once an entry is fixed, I recommend not to remove it. Mark it as "Done" instead
  and move it to the "Done Items Archive" (at the bottom of this file).

--------------------------------------------------------------------------------
TODO 1 - SQL sort expression support (olivierg) - Priority: Medium

Ensure that when one sets Column::orderBy with an SQL expression (like an
SQL function etc...)  the SQL based drivers properly pass this expression
to the backend

--------------------------------------------------------------------------------
TODO 2 - SQL sort expression / field name mapping (olivierg) - Priority: Medium

if Column::orderBy is an SQL expression then it does not make sense for
this expression to make the trip to and back from the browser. Let's
the take the following example :

$column->setOrderBy("REPLACE(title, '\"', '')");

A such expression allows to sort titles properly, whether they start by 
a double-quote or not (I already needed this is in a real-world case).

With the current implementation, this expression is likely to
be printed directly into the html links, with something like :
<a href="...?orderBy=REPLACE%28title%2C+%27%22%27%2C+%27%27%29">

It might work, but it raises a security issue, because we can't properly
escape that string before including it into our SQL query.  In this
context, when one supplies a value with setOrderBy(), it should be
required to also have something set with setField()

Example : 
$column->setLabel("The Bar");
$column->setField("bar");
$column->setOrderBy("REPLACE(title, '\"', '')");

Should produce links like : 
<a href="...?orderBy=bar">

And when generating SQL, this "bar" value should be mapped to the 
orderBy value : SELECT ... ORDER BY REPLACE(title, '\"', '')

--------------------------------------------------------------------------------
TODO 4 - Ensure protection against SQL injection (olivierg) - Priority: Medium

- Are orderBy, direction and page HTTP arguments properly escaped before
they are included in SQL queries ?

--> Answer: they are NOT (at least with DBDO). I just changed this for the 
direction argument, but securing the orderBy value(s) is a bit more 
challenging. The best way to fix this IMO is explained in TODO 2

- Could we write security tests that try to perform SQL injection ?
  
--------------------------------------------------------------------------------
TODO 5 - Don't fetch data if it not needed (wiesemann) - Priority: Medium

- renderers like Pager or HTMLSortForm don't need all data: Pager needs
only the number of records, HTMLSortForm needs only the field names

- Olivier's (agreed and accepted) idea for this from a bug report:
<<<
In this regard, I think that
a mechanism similar to the DataSource "features" (hasFeature(),
setFeatures(), etc...) could be needed.
There could then be features like "renderLimits",
"renderContent" (both true by default) and the DataGrid would
"ask" with : 
if ($renderer->hasFeature('renderLimits')) {count the rows}
if ($renderer->hasFeature('renderContent')) {fetch the rows}
>>>

--------------------------------------------------------------------------------
TODO 7 - Using Datasources out of SDG (olivierg) - Priority: Medium

Document how to use the DataSource layer out of SDG, as an abstract way to fetch
tabular data from a variety of sources.

--------------------------------------------------------------------------------
TODO 8 - "Custom renderers" manual page (olivierg) - Priority: Medium

This manual page is not finished.

--------------------------------------------------------------------------------
TODO 9 - Debugging (?) - Priority: Medium

Add some debugging possibilities, e.g. similar to the way DBDO does it.

--------------------------------------------------------------------------------
TODO 11 - Allow access to the record set (?) - Priority: Medium

Users should be able to access the record set. This can be achieved either by
a new method in the core class or by a new (rather trivial) array renderer.
(Idea/request from Gregor Gramlich)

--------------------------------------------------------------------------------
TODO 15 - Custom DataObjects (olivierg) - Priority: Medium

For a customer I've been asked to provide a faster replacement for DB_DataObject.
My DataObject class has the same interface as DB_DataObject, however SDG won't bind
it, even if I force the type in DataGrid::bind(). This is because
SDG_DS_DataObject::bind() does an intrusive test to ensure that the source is a
DB_DataObject.

--------------------------------------------------------------------------------
TODO 16 - Write mode (olivierg) - Priority: Medium

In order to eventually allow users to edit the data, the DataSource layer now 
has new insert(), update() and delete() prototypes (see DataSource.php CVS 
revision 1.24)

- design the abstract writeMode DataSource interface - Done
- make DataSource drivers support writeMode
    - Array:        Irrelevant (arrays are not persistent)
    - CSV:          Todo
    - DB:           Won't fix 
    - DBQuery:      Won't fix
    - DBTable:      Done
    - DataObject:   Todo
    - MDB2:         Todo
    - RSS:          Todo
    - XML:          Todo
- implement DataSource::filter() to be able to retrieve a specific row
  by its primary key (see TODO 19)
- test these drivers out of SDG
- code GET/POST arguments parsing into DataGrid.php
- create a new Renderer_HTMLEditForm driver
- couple it all together (that's the funny part ;) 

Also see the TODO 20 for a way to couple an HTMLTable with an HTMLEditForm.

--------------------------------------------------------------------------------
TODO 17 - HTMLDetailView Renderer (olivierg) - Priority: Medium

In the .NET DataGrid/GridView, there's a thing called "DetailView". It
is rather useful. It is primarily meant for displaying one record at a
time with all details, while the grid has less details by definition.

We need a such thing that's for sure. And it shouldn't be that hard to
code. Additionally, it implies coding some routines to handle passing
a unique record identifier, which we'll need for TODO 16.

--------------------------------------------------------------------------------
TODO 19 - DataSource::filter() (olivierg) - Priority: Medium

Implement the filter(array(field => value, ...)) method in some DataSource drivers
to filter the data by one or more fields values.

Ex : 
filter(array('f1' => 'foo', 'f2' => 'bar' )
	=> SELECT ... WHERE f1 = 'foo' AND f2 = 'bar' ...

--------------------------------------------------------------------------------
TODO 20 - Column::link() (olivierg) - Priority: Medium

The Link method would help linking two datagrid instances, as in:
http://www.samalyse.com/code/pear/linked_grids

Calling (pseudo-code):
$column = new Column();
$datagrid1->addColumn($column);
$column->link($datagrid2, array('f1', 'f2'))

should format the column to contain links like: ?f1=<value>&f2=<value>
(where values would differ from row to row, like with normal formatters)

The $datagrid2 instance could be rendererd as an HTMLTable or anything else, 
including an HTMLEditForm.

This is related to TODO 16 and 19

--------------------------------------------------------------------------------
TODO 21 - Unit tests improvements (?) - Priority: Medium

Improve the unit test suite, especially with the following items
* class Structures_DataGrid_DataSource_SQLQuery: test subquery handling in
  combination with ORDER BY detection (c.p. Bug #13339) 
* (to be continued)

####################### Done Items Archive #########################

--------------------------------------------------------------------------------
TODO 3 - XML attributes set from the Column object (olivierg) - Priority: Medium - Done

The HTML driver renders the Column::atribs, but attributes are also
valid with XML, and should also be rendered by the XML renderer.

--------------------------------------------------------------------------------
TODO 6 - Predefined column formatters (olivierg) - Priority: Medium - Done

There are common formatting needs such as date, numbers. These could be achieved
with predefined column formatters.

 
--------------------------------------------------------------------------------
TODO 10 - Remove constants (wiesemann) - Priority: High - Done

Remove the new constants for Renderers and DataSources (STRUCTURES_DATAGRID_*),
use strings insteads. To be discussed: Renderer file for HTML_Table is named
HTMLTable.php, 'HTML_Table' as parameter for render()/fill() would be more
precise and consistent. Similar for DataObject.php (=> DB_DataObject),
DBTable.php (=> DB_Table), Console.php (=> Console_Table) and others.

--------------------------------------------------------------------------------
TODO 12 - Let renderers access Column objects directly (olivierg) 
        - Priority: High - WON'T FIX

When refactoring the rendering layer, I thought Column objects were like Records
objects: a waste of memory. So i tried to minimize their use, thinking we could
suppress them in the future. That's mainly why I chose to make renderers completely
ignore the existence of these Column objects.

But I now realize they're very useful, and the $_columns property is now what wastes
memory by duplicating all of the informations contained in $_columnObjects.

Additionally, such options as columnAttributes are redundant with the informations
contained in Column objects, etc...

We should change this ASAP, so that it does not cause too many BC breaks for
people who are writing their own renderers.

I propose to remove the $_columnObjects property, and put Column objects references
directly into $_columns

=> WON'T FIX, because :

- It does work the way it is. It is not perfect and it will never be.  
- I tried several times to "fix" this, and it is far from
  trivial. Everytime it has raised several other quite complex issues.

Conclusion: 
With the current design a Rendering driver is not supposed to know
anything about Column objects, and this strict separation seems to be
useful as far as I can tell (separating layers usually helps when
handling complexity). 

However, on the user-side, there's no reason to minimize the use of
Column objects. The Renderers just do not know anything about them directly.

--------------------------------------------------------------------------------
TODO 13 - Add a FAQ to the documentation (wiesemann) - Priority: Medium - Done

One FAQ would be: "How can I use multiple grids on one page?" (cp. bug #8392)

--------------------------------------------------------------------------------
TODO 14 - Repair handling of numbers in mkmanual.sh (wiesemann)
        - Priority: Medium - DONE

The current version of mkmanual.sh breaks phpDoc comments like the one of
getCurrentRecordNumberStart(). The '0' after 'or:' gets lost and is missing
in the manual, therefore.

--------------------------------------------------------------------------------
TODO 18 - Easy HTML link maker (olivierg) - Priority: Medium - WON'T FIX

I wrote the prototype of SDG_Column::makeHtmlLink() but it still needs to be 
implemented. It's a rather straight-forward idea :

$column->makeHtmlLink("Edit", "product_id", "edit.php");

More in makeHtmlLink()'s docblock

WON'T FIX: the new Column::format() method is flexible enough to replace 
makeHtmlLink()

--------------------------------------------------------------------------------
TODO 21 - new SQLQuery DataSource driver (wiesemann) - Priority: Medium - Done

The current DBQuery and MDB2 DataSource drivers should be merged into a
new SQLQuery DataSource driver. The old drivers should then be marked
as deprecated.

The new driver could also support PDO and/or the PEARified Doctrine
package.

=> Implementation: new PDO DataSource driver; all SQL query based drivers use
   now a common base class (SDG_DS_SQLQuery); new driver (e.g. for Doctrine)
   can easily be added, without having to duplicate large parts of code