[TYPO3-ect] RFC: Result Browser Service for lib/div - part 1 + 2

[Elmar Hinz]

Elmar Hinz wrote:

> 
> 1. Implementation as a service
> 
> The resultbrowser should be implemented as a service. Extensions that want
> to display a resultbrowsser call this service. Different
> classes/extensions can offer this service, so that the user can build a
> specific resultbrower.
> 
> 
> 2. Overview of the API
> 
> The calling extension communicates with the resultbrowser by setters and
> getter methods. The setters set different values of the resultbrowser like
> the total number of hits or parameters for the links, etc. The getters of
> the resulbrowser offer strings of XHTML, that is the pager itself and at
> least one additional status message.
> 
> 
> 3. Configuration of the resultbrowser
> 
> Because of the broad variant of possible resultbrowser implementations,
> it's up to the resultbrowser itself, to manage necessary configurations.
> A set of recommended configurations is defined to cover the mayor part.
> 
> 
> 4. Resultbrowser types: dropdown and link list
> 
> Example of dropdown:
> 
> ------------
> Hits 1  - 10
> Hits 11 - 20
> Hits 21 - 28
> ------------
> 
> Example of link list:
> 
> << <  5  6  7  8  9  > >>
> 
> The resultviews can be selected out of a dropdown controll or by clicking
> on links of a linklist. The dropdown list can have speaking labels that
> either show the alphabetic range of the view like "ab - be" or the offset
> number like "Hits: 50 - 60". As a link list we often find a list of links
> that have a incremental view counter " 1 2 3 4 5 ...". Technically
> dropdown and link list can have all of the named types as label, so that
> they can use an identical API.
> 
> 5. View offset (pointer) vs. result offset
> 
> The resultbrowser of tslib_pibase works with a parameter called "pointer".
> It is the incremental number of the views. When such a link is clicked, a
> list of results is queried and shown determined by the result offset and
> the number of results per view. To determine the result offset the pointer
> has to be multiplied with the numbers of results per view.
> 
> The evaluation from result offset to pointer and vice versa can be saved
> by using the offset directly instead of the pointer. So that should be the
> preferred technique. To also be usable for extensions of the tslib_pibase
> type imlemantations are free to additionally support the pointer
> technique.

6. API

The API is composed of 3 parts:

* Interface between extension and result browser
* Recommended result browser configuration
* Specific result browser configuration

7. Interface between extension and result browser

required: setResultCount(mixed $totalResultCount)  

This is the total amount of results. It is an integer, array or iterator
object (SPL). If it's an array or object the elements are counted.

required: setConfiguration(mixed $configuration)  

This is an array of key/value pairs containing the configuration. It can
also be an ArrayObject (SPL). 
 
required: setDesignator(string $designator)

The designator or the parameters.

optional: setParameters(mixed requestParameters)

This is an array of key/value pairs containing parameters. It can also be an
ArrayObject (SPL). If not used, all parameters of the current request will
be reused.

optional: setLables(mixed labels)

This is an array of offset/label pairs containing speaking labels typically
used for dropdowns (see above). If not provided, plain numbers are used.

8. Recommended result browser configuration

This is not needed from the beginning and will be defined after the first
implementations of resultbrowsers have been done. 

See the PEAR Pager as example:
http://pear.php.net/package/Pager/docs/2.4.3/Pager/Pager.html

9. Specific result browser configuration

This is to be defined by the specific implemantation. See the PEAR Pager as
example: http://pear.php.net/package/Pager/docs/2.4.3/Pager/Pager.html

10. Other

If the offset technic is used, the parameter should be called "offset":

 &tx_extension[offset]=123

The no_cache=1 parameter is not implemented, because of it's many
disadvantages.