MVC Framework/ResultBrowser

From TYPO3Wiki

Jump to: navigation, search
Teams Committees This project/information is related to the Extension coordination team
 List Projects The MVC Framework aka lib/div-project
list pages 		See Current Project Members, Wishlist 
    you can help if you like!
}}

The Resultbrowser is the first MVC-widget, and a part of lib.

Contents

[edit]

Info

News todo: write about PAC widget example ResultBrowser messageID | info-text
News todo: write about Finally a result browser messageID | info-text

[edit]

Status

The MVC library lib (lib) (contact: elmar.hinz) contains a resultbrowser now, to use within the extension. A service wrapper for external extensions is planned for the beta branch of lib. (August 2007)

[edit]

Result Browser Service - Concept

See Glossary. This concept are the Coding Guidelines for new MVC ResultBrowser - implementations.

[edit]

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.

[edit]

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, the offset, the amount of hits per view, parameters for the links, etc. The getters of the resultbrowser offer strings of XHTML, that is the pager itself and at least one additional status message.

[edit]

Configuration of the resultbrowser

Because of the broad variant of possible resultbrowser implementations, it's up to the resultbrowser itself, to manage necessary configurations.

Note So an extension-developer could use it like this:
  • get the service-reference for a result-browser
  • no rendering for a result-browser what just has an outdated interface-version
  • light rendering by a simple version
  • full rendering by a super-duper version

for example "resultBrowserAjax"? When that special is not available a standard rendering-service should be given as reference.

Defining the selection criteria of the service if multiple implementations are available.


[edit]

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.

Note flexible - brainstorming

I (Franz Koch) think the possible types should not be limited. I'd suggest a view service or something like that which can be easily extended with new view-types. If the views are limited there will soon be the same problem with pagebrowsers in TER than with gallerys, calendars etc.

I could also think of such a view: 

< next pages 1 ... 5 6 7 8 ... 43 previous >

or any other variation maybe with Ajax, XML (for flash?) or whatever.


Note (from Franz Koch)

In addition a guideline/rule (Coding Guidelines) should be set, that in extensions the view-type is NEVER hardcoded and must be configurable with TS or be overriden by a global preset for view-types in the service itself (or whatever). It'll also be nice if the configuration of the pagebrowser could be the same in every extensions flexform - but TYPO3 lacks for such intelligent features (hope that's better in v5).

Even better would be that no extension would have to be aware of the existence of the pagebrowser as long as it uses special coding guidelines (or maybe lib/div queries) for the result-handling. Wouldn't it be nice if extensions of general interest (pagebrowser, rating, commenting) could be attached to any other extension just by activating a checkbox that is instantly provided everywhere as soon as the extension (e.g. pagebrowser-MVC) is installed?


[edit]

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.

[edit]

API

The API is composed of 3 parts:

  • Interface between extension and result browser
  • Recommended result browser configuration
  • Specific result browser configuration
[edit]

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. 

required getInterfaceVersion()
Note What is a good standard how interfaces should be versionized? --

PEAR has the human-readable syntax "1.2.3" but for if-comparisons an integer is much better -- like the TYPO3 compatibility-version: 

$TYPO3_CONF_VARS['SC_OPTIONS']['ext/install']['compat_version']['cms'] =
array(
'version' => 4000000,
);

So an interface 1.4.327 is no problem: 

if ($s.getInterfaceVersion() >= 1004000) {
# OK
} else {
# very old
}



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.

[edit]

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

[edit]

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

[edit]

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.

[edit]

Problems with Coding Guidelines

For the pagebrowser this "special Coding Guidelines" is not that simple, because 2 SQL queries are required, one to find the total result count and one for the current results. However, I would say that this API we currently discuss not far from this "special coding guideline". If you implement it, resultbrowsers can plugged in as a service.

Retrieved from "http://wiki.typo3.org/index.php/MVC_Framework/ResultBrowser"
Personal tools
content
help 'N' beginners