DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: Select Pro

Author:Kasper Skårhøj
Created:2002-11-01T00:32:00
Changed:2005-06-11T21:47:46
Author:Dr. Pascal Grüttner
Email:p.gruettner@gst-im.de
Info 3:
Info 4:

EXT: Select Pro

Extension Key: gst_selectpro

Copyright 2003-2005, Dr. Pascal Grüttner, <p.gruettner@gst-im.de>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.com

Table of Contents

EXT: Top Content 1

Introduction 1

What does it do? 1

Screenshots 2

Users manual 2

Configuration 3

Reference 5

Tutorial 7

Known problems 8

To-Do list 8

Changelog 8

Introduction

What does it do?

Select Pro extends the SELECT features of Typo3. With Select Pro you are able to dynamically generate sql queries and display their results. The queries are stored in the MySql database of Typo3. Each result column can be customized, e.g. by defining wrap-functions. The column definitions are stored in the database also.

For the result display Select Pro uses HTML templates with dynamic marks depending on the amount of result columns of your query.

Select Pro comes with many examples wich are included in the 'Tutorial' of this documentation.

Users of Select Pro are supposed to be experienced in SQL. So this plugin is interesting especially for developpers who want to have an easy and non-restricted access to the database tables of Typo3.

These are some of the main features of Select Pro :

  • building your own SELECT statements
  • customizing each result column
  • storing queries and column-definitions in the database
  • dynamical result display by HTML template files
  • handling features like 'hidden/visible', 'start/end time' and 'user group access' automatically (if requested by the user)
  • extensive documentation including tutorial cases

etc.

One of the most interesting applications for Select Pro is to act as a kind of “all-in-one”-frontend plugin. If you get familiar with Select Pro , you will learn that it is easy to generate queries and HTML templates to display which records ever. You can show address-lists as well as actual news or top content. You are free to build your own link lists or calendar displays.

Even though Select Pro is a powerful tool to select and display data from Typo3, you must not forget, that most of the extensions mentioned above come with very special features, that you have to remember, if you like to use Select Pro to replace the associated frontend plugins.

For a better understanding of these thoughts please refer to the 'Tutorial'.

The languages actually supported are: english, german, french, finnish, italian, romanian.

Screenshots

This screenshot demonstrates an example of Select Pro simulating a Top Content-Plugin output. The result records are ordered by their timestamp in a descending way. Select Pro in this example shows teaser text of the most actual content of the website.

img-1

For more screenshots, please refer to the sections 'Users manual', 'Administration' and 'Tutorial'.

Warning

You may probably ask yourself, if Select Pro could not send other commands than SELECT to the database. In fact this would be possible...

It is highly recommended not to use Select Pro for UPDATE, INSERT, DROP, ALTER, CREATE or other modifying statements! You could destroy single data, relations between records or even whole tables or databases. For those reasons Select Pro will not allow sql strings, beginning with these five commands.

Any modifying command you try to use with Select Pro is at your own risk!

Users manual

((generated))

About this section

To use Select Pro you need to build sql queries and column definitions. In this section you will learn about:

making a new sql query with Select Pro

defining the result columns of the query

Please refer to 'Administration' for general information about setting up Select Pro .

Query

A new query should be titled and you may enter a description of what the query does.

The most important thing is to build the query. You are free to generate what SELECT ever. If you want to use the ###WHEREADD###-marker of Select Pro , you have to insert it with the WHERE (or HAVING) clause.

You have to enter the fieldname of the column which contains the PID value. You have to indicate tablename and fieldname. If the query has no PID field, just enter some characters in this field.

Passing GET-variables to the query:

A very special feature is to pass variables to the query by URL (GET- parameters). There is a way the GET-variables have to be named: selectpro_[columnname].

http://www.myurl.org/index.php?selectpro_examplecol1=1234&selectpro_examplecol2=abcd

To include the GET-variables into the query, markers have to used, that are named in the same way: ###SELECTPRO_[COLUMNNAME]###.

select column1, column2, ... columnn from table
where ...
and column1 = ###SELECTPRO_COLUMN1###
and column2 like '%###SELECTPRO_COLUMN2###%'

img-2

You can automatically activate the Typo3 'enabledfields' feature, which will handle 'hidden/visible', 'start/end time' and 'user group access' for the table indicated. Multiple tables can be named. Just enter them comma-separated.

The same is for the system language. If you enter the name of the system language field of the table, your query will be automatically extended by that.

If you want to restrict the considered pages, enter the allowed doktypes in the appropriate field. Again a comma-separated list is used. (Please refer to the documentation of Typo3 to learn about doktypes.)

img-3

The ###WHEREADD###-marker will be replaced by

  • 'enabledfields' restrictions
  • 'system language' restrictions
  • 'PID' restrictions

If you don't want to use those automatic features of Select Pro , just leave the ###WHEREADD###-marker andset the whereadd-override- option.

There is another feature you can apply: If you enable the override- option in combination with [sql_enablefields] and/or [sql_syslanguage] and set the ###WHEREADD###-marker, Select Pro will only activate the 'enabledfields' and/or 'system language' restrictions.

img-4

The following tables shows all possible combinations and results:

SET

###WHEREADD###

SET

sql_whereadd_override

SET

Result

Only the enabledfields and/or system language restriction(s) will be used.

SET

###WHEREADD###

SET

sql_whereadd_override

NOT SET

Result

All restrictions will be used.

NOT SET

###WHEREADD###

NOT SET

sql_whereadd_override

SET

Result

No restriction will be used.

NOT SET

###WHEREADD###

NOT SET

sql_whereadd_override

NOT SET

Result

Error: This case is not allowed. (You can't override what is not there.)

The result will be displayed by parsing it through the HTML template. You have to enter the full path and filename here.

img-5

Before starting a new query it is important to know that Select Pro normally would apply your query to a collection of pages. To realize that, you only have to set up a starting point = [start_pid]. Beginning with that PID the whole page tree will be the basis of the query. If no startingpoint is set, Select Pro chooses the page where the plugin is located

If you want to exclude pages from the query, you may enter them in the [exclude_pids]-field (comma-separated). It is also possible to exclude pages recursively by using the [exclude_pids_r]-field (comma-separated).

img-6

For the result browser you can enter the maximum amounts of result records and the amount of records displayed on each page. Remember that you have to

enter both values and

keep [recs_max] > [recs_pp]

to get an appropriate result.

img-7

You can let Select Pro automatically generate a link to a source record. To realize that you have to add at least one column to your query:

... [tablename.pid] AS selectpro_pid ...

If your link should point to a special record you can add another column also:

... [tablename.uid] AS selectpro_uid ...

The link built by Select Pro would then look like this:

h t t p :// www.my_page.com/[selectpro_pid].html#[selectpro_uid]

If you enter a linktext and/or a linkicon, Select Pro will try to generate a link and display it with the text and/or icon you specified. There is a default icon that will be used, if you enter a non-existing file.

If you want to specify a link target, use the HTML format (e.g. _blank). The default value is _top

img-8

A very special way of linking is possible by activating useContUid. The query could look like this:

... RIGHT(tt_content.header_link,
LENGTH(tt_content.header_link) - LOCATE('#', tt_content.header_link))
AS selectpro_uid,
LEFT(tt_content.header_link,
LOCATE('#', tt_content.header_link) - 1)
AS selectpro_pid ...

From the link column of the contents header the pid and the uid are already isolated by SQL commands. The activated contUid-feature then generates a link with the additional parameter contUid=[uid]. All about contUid including example-code can be found in the documentation of the extension “ Top Content ”.

Note: If in that case a target is included, this target overrides the column [item_linktarget].

Column definition

A new column definition first of all has to be connected to a query (1:n-relation).

The column name is free at your choice.

The column number is important. It has to match the position of the column in the query!

Concerning the column type there are four possiblities. Depending on your selection the result will be parsed through different display functions.

img-9

The column types are: TEXT, IMAGE, DATE/TIME, LINK/MAIL.

Rendering sequence TEXT: text crop >> wrap >> standard wrap

Rendering sequence IMAGE : width/height >> wrap >> standard wrap

Rendering sequence DATE/TIME : strftime >> wrap >> standard wrap

Rendering sequence LINK/MAIL : link/target >> wrap >> standard wrap

img-10

The wrap property applies to all column types. It is used in the way Typo3 applies the standard wrap property.

In case of a TEXT column, you can crop the result value to a length of [col_text_crop] characters.

img-11

In case of IMAGE column, you can set the width and/or the height of the image. Be careful if you set both parameters (image proportions).

If the result contains multiple images, all images will be displayed. You may enter a separator to devide the result images.

img-12

A column can link to a page that you choose.

img-13

You may specify a column name (which has to be in the SELECT statement also) that contains link information. There is for example the column tt_content.image_link. If this parameter is set, Select Pro tries to establish a link using the content in the named field. Important: Do not use tablenames here, only the fieldname is required! You can also use the virtual columns (i.e. selectpro_pid) here.

img-14

If you want to specify a link target, use the HTML format (e.g. _blank or page). The default value is _top. The target value also applies, in case of LINK/MAIL column type.

img-15

You can override empty values. In case of IMAGE column type, this value will be interpreted as a full filename.

A separate CSS-stylsheet class can be assigned to each result column.

img-16

Administration

For Select Pro some initial configurations are required. In this section you will learn about:

  • the folder structure needed for Select Pro
  • how to make a new query record
  • how to add a column definition record for a query
  • how to add a new frontend plugin

Please refer to 'Users manual' for detailed information about queries and column definitions. Please refer to 'Tutorial' for examples.

((generated))

Folders

First of all it is recommended to add a separate folder structure. For the “root” of the extension make a new hidden page, which is named “ Select Pro ” in this example. Then you need one additional page for each new query. You can use systemfolders for that.

Example: The hidden page “Select Pro” contains three systemfolders.
|img-17|
New Query

First of all it is recommended to add a separate folder structure. For the “root” of the extension make a new hidden page, which is named “ Select Pro ” in this example. Then you need one additional page for each new query. You can use systemfolders for that.

Each query has to be stored in a new page. Go to this page and choose 'new record'. You will see two new record types, which are provided by Select Pro . For the query you have to select the 'maintable' item (1.).

Example:
Selecting a new table 'maintable' for “Select Pro” (red arrow 1).
New Columndefinition

Each query can have column definitions for each column returned by the query. It is not a must to define the columns. If columns have no entry in the Select Pro columns table, default settings (type=TEXT) will be used instead. Nevertheless it is recommended to define each column, because this is the only way to specify the columns.

In the page where the query is stored you choose 'new record'. Again you will see the two new record types, which are provided by Select Pro . For the columndefinitions you have to select the 'columndefinitions' item (2.).

Example: Selecting a new table 'columndefinitions' for “Select Pro” (red arrow 2).
|img-18|

Configuration

((generated))

Installation

Select Pro has to be installed with the Extension Manager. Remark: Database updates are required. Two new tables will be generated. Finally the cache has to be cleared also.

New frontend plugin

To make a new Select Pro frontend plugin element a few steps, according to the common way plugins are inserted in Typo3, have to be done.

Choose a new content element.

Then select the Select Pro plugin.

There you may enter a headline. You have to set the startingpoint (red box), which refers to the page containing the query and column definitions records. If you don't want to use a frontend plugin, you will have to connect to the query by setting the value “queryPid” in your template (ref. 'Reference Constants').

img-19

Reference

Reference TypoScript (Constants)
debugSQL

Property

debugSQL

Data type

integer

Description

Set this value (1) if you want the plugin only to display the final SQL querystring.

Default

0

useResForTempl

Property

useResForTempl

Data type

integer

Description

Set this value (1) if you (always) want the res folder of the plugin to be the folder for your html templates.

Normally the template file would be specified by setting [templatefile] (query definition).

Default

0

useParseFunc

Property

useParseFunc

Data type

integer

Description

Set this value (1) if you want the content to be parsed through the Typo3-parseFunc-function. Applies to column type TEXT.

Default

0

useStripTags

Property

useStripTags

Data type

integer

Description

Set this value (1) if you want the content to be parsed through the PHP strip_tags-function. Applies to column type TEXT.

Default

1

queryPid

Property

queryPid

Data type

integer

Description

This is the PID where the query is located. Normally this value will be set using the startingpoint of the plugin.

If you want to use Select Pro within a template and not as a frontend plugin, you will have to connect to the query by setting this value.

Default

directories.path

Property

directories.path

Data type

string

Description

If you are using tables other than the default tt_content (eg. in extensions) add the directories (comma-separated list) where your images are stored in. Usually: uploads/pics. With extension: uploads/tx_yourextensionname.

Default

directories.all

Property

directories.all

Data type

integer

Description

If set (1), all directories listed in directory uploads/ will be searched through (not recursively!).

Default

1

unsetLastSeparator

Property

unsetLastSeparator

Data type

integer

Description

Set this value (1) if you want the last separator part of the HTML- template to be unset. Useful to have separators only between the content elements and not at the end.

Default

0

useContUid

Property

useContUid

Data type

Integer

Description

Set this value (1) if you want the the links to be generated like ...php?id=[pid]&contUid=[uid]. For more information about contUid refer to the manual of the extension "Top Content".

Default

0

classTdBrowse

Property

classTdBrowse

Data type

string

Description

CSS-class for the <TD>-tag of the page browser.

Default

[tsref:plugin.tx_gstselectpro_pi1]

Hint: The constants can be edited with the constants editor of Typo3.

Reference TypoScript (Setup)
text_parseFunc

Property

text_parseFunc

Data type

array

Description

Typo3 parseFunc properties for the display of TEXT type. Each column can be configured separately. Use the column numbers within the TypoScript-array.

Example:

Columns number 1 and 2 are configured:

text_parseFunc {
  1 < tt_content.text.20.parseFunc
  2 < someobject.parseFunc
}

Default

text_stdWrap

Property

text_stdWrap

Data type

array

Description

Standard wrap properties for the display of TEXT type. Each column can be configured separately. Use the column numbers within the TypoScript-array.

Example:

Columns number 1, 2 and 3 are configured:

text_stdWrap {
  1 {
    innerWrap = <h2>|</h2>
    spaceAfter = 15
  }
  2.innerWrap = <p>|</p>
  3.spaceBefore = 5
}

Default

image_stdWrap

Property

image_stdWrap

Data type

array

Description

Standard wrap properties for the display of IMAGE type. Each column can be configured separately. Use the column numbers within the TypoScript-array.

Example: refer to text_stdWrap

Default

date_stdWrap

Property

date_stdWrap

Data type

array

Description

Standard wrap properties for the display of DATE/TIME type. Each column can be configured separately. Use the column numbers within the TypoScript-array.

Example: refer to text_stdWrap

Default

Example

Your query has got three text columns which are columns number 2, 3 and 6. The columns number 4 and 5 are image columns. This example will wrap each text and image column in a special way. (Don't care about the stdWraps used. This is only an example.)

plugin.tx_gstselectpro_pi1 = USER
plugin.tx_gstselectpro_pi1 {

text_stdWrap {
  2 {
    innerWrap = <h2>[Example] |</h2>
    spaceAfter = 10
  } // end 2
  3.innerWrap = <p>|</p>
  6.innerWrap = <p><i>|</i></p>
} // end text_stdWrap

image_stdWrap {
  4.wrapAlign = right
  5 {
    prepend = TEXT
    prepend.value = [Nice image]<br>
    space = 10|10
  } // end 5
} // end image_stdWrap

} // end plugin.tx_gstselectpro_pi1
Reference TypoScript (Languages)

The available language variables (pi1/locallang.php) are:

dateFormat

Property

dateFormat

Data type

string

Description

Formatting date/time according the rules of strftime().

(Engl.) Default

%A, %m-%d-%Y

PI_noTemplate

Property

PI_noTemplate

Data type

string

Description

This text is shown if no HTML template file was found.

(Engl.) Default

HTML template not found.

PI_noUpdateInsert

Property

PI_noUpdateInsert

Data type

string

Description

This text is shown if modiying commands like UPDATE or INSERT were found at the beginning of the query.

(Engl.) Default

Neither UPDATES nor INSERTS are permitted.

PI_noPidfield

Property

PI_noPidfield

Data type

string

Description

This text is shown in case of empty [sql_pidfield_fullname]-field.

(Engl.) Default

You have to set the full name of the PID field [sql_pidfield_fullname].

PI_nostartingpoint

Property

PI_nostartingpoint

Data type

string

Description

This text is shown if the startingpoint of the plugin has not been set (=a valid record from the tx_gstselectpro_main table).

(Engl.) Default

No startingpoint set in plugin. You have to select a valid record from tx_gstselectpro_main as startingpoint for the plugin.

PI_notx_gstselectpro_main

Property

PI_notx_gstselectpro_main

Data type

string

Description

This text is shown if no tx_gstselectpro_main record is corresponding to the startingpoint.

(Engl.) Default

No valid record found in tx_gstselectpro_main as startingpoint.

PI_nowhereAddMarker

Property

PI_nowhereAddMarker

Data type

string

Description

This text is shown if the required marker ###WHEREADD### is missing in the select statement.

(Engl.) Default

Marker ###WHEREADD### missing in SELECT statement.

PI_noQueryResult

Property

PI_noQueryResult

Data type

string

Description

This text is shown if the final query has no result.

(Engl.) Default

Your query returned no result.

browsePage

Property

browsePage

Data type

string

Description

This word will be put in front of the pagenumber. If you leave it empty, only the pagenumber will be displayed.

(Engl.) Default

Page

browseSeparator

Property

browseSeparator

Data type

string

Description

If the result consists of several pages, this characters will separate them.

Example:

Page 1-Page 2-Page 3-Page 4

(Engl.) Default

browseActPageWrap

Property

browseActPageWrap

Data type

string

Description

The actually displayed page can be wrapped with this parameter. This works like the stdWrap-function of Typo3: the pipe will be replaced by the value of the actual page.

Note: The result will be parsed through PHP-function htmlspecialchars().

(Engl.) Default

>>|<<

browseFromTo

Property

browseFromTo

Data type

string

Description

This displays a message to indicate the actual position within the recordset. There are three markers that will be replaced by the original values.

Syntax:

###FROM###: starting record
###TO###: ending record
###COUNT###: record count

Example:

Results 6 to 10 out of 25

(Engl.) Default

Results ###FROM### to ###TO### out of ###COUNT###

[tsref:plugin.tx_gstselectpro_pi1]

Example

In the setup part of the template it is possible to set the language variables without changing 'locallang.php'. The section is disabled by default, but you may wish to use it.

/* -disabled by default-
// Change local language variables.
  _LOCAL_LANG.default.dateFormat = %A, %m-%d-%Y
  _LOCAL_LANG.de.dateFormat = %A, %d.%m.%Y
  _LOCAL_LANG.fr.dateFormat = %A, %d/%m/%Y
*/
Reference HTML template

The HTML templates are arranged in a totally dynamic manner. For each result column two markers are generated:

###MARK[col_number]### where [col_number] is the number of the result column: This marker contains the column value.

###CSSCLASS[col_number]### where [col_number] is the number of the result column: This marker can be replaced by a CSS-class to define the properties e.g. of the <TD>-tag of the column result.

Example:
<tr><td colspan="2" class="###CSSCLASS1###">###MARK1###</td></tr>

The CSS-markers ###CSSCLASS... are not necessarily required to be <TD>-tag styles. You can define HTML templates where you use for example the <SPAN>-tag.

Example:
<tr><td colspan="2" widht=”200”>
  <span class="###CSSCLASS1###">###MARK1###</span>
</td></tr>

You can use the subpart ###SEPARATOR_ITEM### to separate each result record from the other:

Example using a separating row:
<!-- ###SEPARATOR_ITEM### -->
<tr><td><img alt="" src="clear.gif" width="1" height="10"></td></tr>
<!-- ###SEPARATOR_ITEM### -->

In combination with unsetLastSeparator you are able to build very special Select Pro results. The following image shows an example of a HTML table with five columns (<TD>-tags). There are (in the example always) three content results which should be rendered like: CONTENT / SEPARATOR. Normally you would have a last separator outside the table (column number six). Using unsetLastSeparator you can suppress the last separator.

img-20

If you want to learn more about the HTML templates and Select Pro , please refer to the three example templates that are included in the res-folder.

Tutorial

Case 1 - Top Content

This tutorial will show you how to generate a new query and column definitions in a way that the output will be an extended version of the Typo3 extension Top Content. That means that we want to select and display the newest articles from tt_content.

You will learn how to

  • genrerate a new query
  • handle more than one source table
  • define definitions for each query result column
  • configure the column types: DATE/TIME, TEXT and IMAGE
  • add a link to the original content element
  • add a column link determined by a tableentry
Case 1: Query

We call our query TT_CONTENT. The SELECT statement contains some fields from tt_content and the page title from pages which is connected by the INNER JOIN. We use the ###WHEREADD###-marker, because we want to restrict our query to a defined part of the pagetree. To get the newest content first, we ORDER BY tstamp descending. Remember the sequence of the tablefields in the SELECT for later use. (tt_content.tstamp is column 1, pages.title is column 2 etc.). The filed image_link won't get its own columndefinition but would be used in the image column to act as a link.

[sql_select]: SELECT tt_content.tstamp, pages.title,
tt_content.header, tt_content.bodytext, tt_content.image,
tt_content.image_link, tt_content.uid AS selectpro_uid, tt_content.pid AS selectpro_pid
FROM tt_content
INNER JOIN pages ON tt_content.pid = pages.uid
WHERE 1=1 ###WHEREADD###
ORDER BY tt_content.tstamp DESC

For the pages-restriction we need to now the exact fieldname of the pid field. It is tt_content.pid. In the final query this will lead to a part of the WHERE clause like: ... AND tt_content.pid IN ([list_of_pids]) ...

[sql_pidfield_fullname]: tt_content.pid

We also add the 'enabledfields' and the language restriction by entering the values in the appropriate fields. Both tt_content and pages shall be included.

[sql_enablefields]: tt_content,pages
[sql_syslanguage]: tt_content,pages

Then we set the allowed 'doktype's to 1 and 2, which will exclude for example hidden pages etc.

[sql_allowed_doktypes]: 1,2

The ###WHEREADD###-marker is used as shown above. So we don't override it.

[sql_whereadd_override]: unchecked

Now we specify the HMTL template file. (Note: Only in the tutorial cases or if useResForTempl is set the path is not necessary with the filename!)

[templatefile]: gstselectpro_template_tutorial1.tmpl

The start PID has to be set and will be the root of the website where the plugin is installed.

Some single PIDs shall be excluded from the final PID list. These will be the PIDs 706,728,729 and 1354, which contain not so interesting stuff.

The PID 1252 hosts a news plugin. This page and recursively all pages below shall be excluded also, because we don't want the news plugin in our result.

[start_pid]: gruettner.de
[exclude_pids]: 706,728,729,1354
[exclude_pids_r]: 1252

We only want 15 records as a result and we want to split the result into pages of 5 records each.

[recs_max]: 15
[recs_pp]: 5

Finally a link to the original content element shall be generated automatically. This link will be shown as a combination of text and the default linkicon of Select Pro . The linktarget is by default _top.

Note: The default linkicon will be shown, because the entry “default” is not a valid path and filename. In those cases, Select Pro uses the default linkicon instead. If you don't want to display an icon, just leave the value empty.

[item_linktext]: Goto&nbsp;record&nbsp;
[item_linkimg]: default
[item_linktarget]:

Example:
|img-21|

Concerning the link you remember that we selected two fields that we don't wanted to display later: “... tt_content.uid AS selectpro_uid, tt_content.pid AS selectpro_pid ...”. Select Pro will use the information of these fields to generate the appropriate links.

Ok, we finished our query record. Save it and then proceed with the column definitions!

Case 1: Column definitions

Each column will get its own definition. Remember it is important to connect each new column to the appropriate query (1:n-relation). In our case this is the query which we called “TT_CONTENT”. So this appplies to all the other columns as well:

|img-22|
Case 1: Column definitions of the field “Date”

Each column will get its own definition. The columns are treated in the same sequence as they appear in the query. So the first column (= [col_number] 1) is tt_content.tstamp (ref. to the query), which we call “Date”.

[col_name]: Date
[col_number]: 1

Now let's define the type of the column which is necessary for the rendering of the result value. We choose “DATE/TIME” as type.

[col_type]: DATE/TIME

The last field we want to define for this column is the CSS-class. In the HTML template file of this case you will see several classes integrated. This is the name of the class we want to be applied to the <TD>-tag of the columns result value: “tutorial1_date”.

[col_cssclass]: tutorial1_date
Case 1: Column definitions of the field “Pagetitle”

We call the second column (= [col_number] 2), which is pages.title (ref. to the query), “Pagetitle”. The column type is TEXT.

[col_name]: Pagetitle
[col_number]: 2
[col_type]: TEXT

In the final result we want the pagetitle to appear in front of the content title. For that reason we set the wrap option. And finally as we did above, we choose a separate CSS-class for the results <TD>-tag.

[col_wrap]: |:
[col_cssclass]: tutorial1_pagetitle
Case 1: Column definitions of the field “Header”

The third column (= [col_number] 3) will be named “Header” and is tt_content.header (ref. to the query). The column type is TEXT.

[col_name]: Header
[col_number]: 3
[col_type]: TEXT

Empty values will be overridden and a separate CSS-class shall be used.

[col_empty_override]: [No title]
[col_cssclass]: tutorial1_header
Case 1: Column definitions of the field “Bodytext”

The next column (= [col_number] 4) will be named “Bodytext” and is tt_content.bodytext (ref. to the query). The column type is TEXT.

[col_name]: Bodytext
[col_number]: 4
[col_type]: TEXT

The properties we set are wrap and crop. The [col_wrap] prepends and appends some text and the [col_text_crop] reduces the result to a maximum of 150 characters.

[col_wrap]: Text snippet: |...
[col_text_crop]: 150

Again we use the feature of overriding empty values and again we apply an own CSS-class.

[col_empty_override]: [No text]
[col_cssclass]: tutorial1_bodytext
Case 1: Column definitions of the field “Image”

The last displayed column (= [col_number] 5) will be named “Image” and is tt_content.image (ref. to the query). The column type is IMAGE (screenshot in german: BILD).

[col_name]: Image
[col_number]: 5
[col_type]: IMAGE

The height of each image shall be 40 pixels. We only set the height to save the proportions of the images.

The image field of tt_content can contain multiple images. If multiple images are found, they would be separated by two HTML breaks (<br><br>).

[col_img_width]:
[col_img_height]: 40
[col_img_multiseparator]: <br><br>

The image shall act as a link, if there is a corresponding entry in the tt_content table (filedname image_link). Have a look at the query, where tt_content.image_link is selected also. In the column definition do only use the fieldname!

[col_linkcolname]: image_link

Now end the column with the CSS-class.

[col_cssclass]: tutorial1_image

Ok, we have finished all relevant column definition records. The final result looks like this:

Select Pro Maintable

TT_CONTENT

Select Pro Columndefinitions

  • Date
  • Pagetitle
  • Header
  • Bodytext
  • Image
Case 1: Inserting a frontend plugin

Please refer to the chapter 'Configuration' of this documentation. Remember that you have to set the startingpoint, which in this tutorial case should point at the page, that we called “Tutorial 1” before.

*Congratulations, you finished the tutorial case 1!*

Case 1: Example
A (german) example of this tutorial case can be found at:
http://www.gst-service.de/index.php?select_pro

Case 2 - Addresses

This short and easy to realize tutorial will show you how to generate a new query and column definitions in a way that the output will be a simple list version of the Typo3 extension table tt_address. The aim is to select and display all addresses of the actual website.

You will learn how to

  • genrerate a new query
  • define definitions for each query result column
  • configure the column types: TEXT and LINK/EMAIL
Case 2: Query

We call the query TT_ADDRESS. The SELECT statement contains the main fields from tt_address. We will partially use the ###WHEREADD###-marker, because we want to restrict our query according to the enabledfields feature of Typo3. Remember the sequence of the tablefields in the SELECT for later use. (tt_ address.name is column 1, tt_ address.address is column 2 etc.)

[sql_select]: SELECT name, address,
zip, city, country, www, email
FROM tt_address WHERE 1=1 ###WHEREADD###
ORDER BY name

We don't use the pages-restriction (to a defined pagetree) but the [sql_pidfield_fullname] is required. That is why we fill it out.

[sql_pidfield_fullname]: tt_address.pid

We add the 'enabledfields' restriction and ignore the language and doktype restriction.

[sql_enablefields]: tt_address
[sql_syslanguage]:
[sql_allowed_doktypes]:

In this case the ###WHEREADD###-marker is used in a special way: by checking the override-option the pagetree-restriction will be ignored but the 'enabledfields' feature will be applied anyway.

[sql_whereadd_override]: checked

Now we specify the HMTL template file. (Note: Only in the tutorial cases or if useResForTempl is set the path is not necessary with the filename!)

[templatefile]: gstselectpro_template_tutorial2.tmpl

The start PID in this case will not be set, because the pagetree is not relevant (whereadd-override-option). Consequently there is no pid to exclude.

[start_pid]:
[exclude_pids]:
[exclude_pids_r]:

We don't want to limit the result records.

[recs_max]:
[recs_pp]:

The link feature will not be activated.

[item_linktext]:
[item_linkimg]:
[item_linktarget]:

Ok, we finished our query record. Save it and then proceed with the column definitions!

Case 2: Column definitions

Each column will get its own definition. Remember it is important to connect each new column to the appropriate query (1:n-relation). In our case this is the query which we called “TT_ADDRESS”. So this appplies to all the other columns as well:

[tx_gstselectpro_main_uid]: TT_ADDRESS
Case 2: Column definitions of the field “Name”

Each column will get its own definition. The columns are treated in the same sequence as they appear in the query. So the first column (= [col_number] 1) is tt_address.name (ref. to the query), which we call “Name”. The type of the column, which is necessary for the rendering of the result value, is “TEXT”.

[col_name]: Name
[col_number]: 1
[col_type]: TEXT

The properties we also set are wrap and the CSS-class for the result column.

[col_wrap]: Name:&nbsp;|
[col_cssclass]: tutorial2_name
Case 2: Column definitions of the field “Address”

The second column (= [col_number] 2) is tt_address.address (ref. to the query), which we call “Address”. The type of the column, which is necessary for the rendering of the result value, is “TEXT”.

[col_name]: Address
[col_number]: 2
[col_type]: TEXT

The final property we set are is and the CSS-class for the result column.

[col_cssclass]: tutorial2_address
Case 2: Column definitions of the field “ZIP”

The third column (= [col_number] 3) is tt_address.zip (ref. to the query). The name is “ZIP”. The type is “TEXT”. Finally we set a separate CSS-class.

[col_name]: ZIP
[col_number]: 3
[col_type]: TEXT
[col_cssclass]: tutorial2_zip
Case 2: Column definitions of the field “City”

The next column (= [col_number] 4) is tt_address.city (ref. to the query). The name is “City”. The type is “TEXT”. Finally we set a separate CSS-class.

[col_name]: City
[col_number]: 4
[col_type]: TEXT
[col_cssclass]: tutorial2_zip
Case 2: Column definitions of the field “Country”

The fifth column (= [col_number] 5) is tt_address.country (ref. to the query). The name is “Country”. The type is “TEXT”. Finally we set a separate CSS-class.

[col_name]: Country
[col_number]: 5
[col_type]: TEXT
[col_cssclass]: tutorial2_country
Case 2: Column definitions of the field “WWW”

The next column (= [col_number] 6) is tt_address.www (ref. to the query). The name is “WWW”. The type is “LINK/MAIL”.

[col_name]: WWW
[col_number]: 6
[col_type]: LINK/MAIL

For the website we always want a new windows as target (_blank). Again we set a separate CSS-class.

[col_linktarget]: _blank
[col_cssclass]: tutorial2_link
Case 2: Column definitions of the field “Email”

The last column (= [col_number] 7) is tt_address.email (ref. to the query). The name is “Email”. The type is “LINK/MAIL”.

[col_name]: Email
[col_number]: 7
[col_type]: LINK/MAIL

Empty values will be replaced by the text “[No email]”. For this column we use the same CSS-class as for the column WWW.

[col_empty_override]: [No email]
[col_cssclass]: tutorial2_link

Ok, we have finished all relevant column definition records. The final result looks like this:

Select Pro Maintable

TT_ADDRESS

Select Pro Columndefinitions

  • Name
  • Address
  • ZIP
  • City
  • Country
  • WWW
  • E-mail
Case 2: Inserting a frontend plugin

Please refer to the chapter 'Configuration' of this documentation. Remember that you have to set the startingpoint, which in this tutorial case should point at the page, that we called “Tutorial 2” before.

*Congratulations, you finished the tutorial case 2!*

Case 2: Example
A (german) example of this tutorial case can be found at:
http://www.gst-service.de/index.php?select_pro

Case 3 - News

This tutorial will show you how to generate a new query and column definitions in a way that the output will be a list version of the Typo3 extension tt_news. That means that we want to select and display the actual news from tt_news.

You will learn how to

  • genrerate a new query
  • define definitions for each query result column
  • configure the column types: DATE/TIME, TEXT
  • add a link to the original news element
Case 3: Query

We call the query TT_NEWS. The SELECT statement contains the main fields from tt_news. We will use the ###WHEREADD###-marker, because we want to restrict our query automatically. Remember the sequence of the tablefields in the SELECT for later use. (tt_ news.name is column 1, tt_ address.address is column 2 etc.)

As you will see, there is a little tricky part in the SELECT statement. If you want to apply a direct link to each news, you have to know, how the news extension works. (And of course you need a working instance of the plugin.)

The CONCAT part does several things:

Building a link to the “Single-News-Display-Page”, which in this case has got the PID 456.

Adding “&tt_news=” to the URL.

Appending the uid of the actual news item.

Defining this as “selectpro_pid” which is the link command for Select Pro.

In addition to that we have to remember the archive feature of tt_news, which is tested by the first criteria of the WHERE clause.

The result is a regular link to each single news item.

[sql_select]: SELECT datetime, title, short, author,
CONCAT('http://www.mysite.com/index.php?id=456&tt_news=', uid)
AS selectpro_pid
FROM tt_news
WHERE (NOT archivedate OR archivedate > UNIX_TIMESTAMP(NOW()))
###WHEREADD###
ORDER BY datetime DESC

For the pagetree-restriction the full name of the tables PID field has to be entered.

[sql_pidfield_fullname]: tt_news.pid

We add the 'enabledfields' restriction. There is no language fields in the tt_news table. Concerning the doktype we set it to systemfolder, which is 254.

[sql_enablefields]: tt_news
[sql_syslanguage]:
[sql_allowed_doktypes]: 254

The ###WHEREADD###-marker is used as shown above. So we don't override it.

[sql_whereadd_override]: unchecked

Now we specify the HMTL template file. (Note: Only in the tutorial cases or if useResForTempl is set the path is not necessary with the filename!)

[templatefile]: gstselectpro_template_tutorial3.tmpl

The start PID in this case has to be set to the folder containingthe news we want to consider. Normally the news plugin is arranged in a way, that no PID has to be excluded.

[start_pid]: [my_news_folder]
[exclude_pids]:
[exclude_pids_r]:

We don't want to limit the result records to five. The display shall be at the right side of the website, so we don't need page browsing options.

[recs_max]: 5
[recs_pp]:

The link feature will be activated.

[item_linktext]: &nbsp;[more]
[item_linkimg]:
[item_linktarget]:

Ok, we finished our query record. Save it and then proceed with the column definitions!

Case 3: Column definitions

Each column will get its own definition. Remember it is important to connect each new column to the appropriate query (1:n-relation). In our case this is the query which we called “TT_NEWS”. So this appplies to all the other columns as well:

[tx_gstselectpro_main_uid]: TT_NEWS
Case 3: Column definitions of the field “Datetime”

Each column will get its own definition. The columns are treated in the same sequence as they appear in the query. The first column (= [col_number] 1) is tt_news.datetime (ref. to the query), which we call “Datetime”. The type of the column is “DATE/TIME”. The last field we want to define for this column is the CSS-class.

[col_name]: Datetime
[col_number]: 1
[col_type]: DATE/TIME
[col_cssclass]: tutorial3_datetime
Case 3: Column definitions of the field “Title”

We call the second column (= [col_number] 2), which is tt_news.title (ref. to the query), “Title”. The column type is TEXT. And finally as we did above, we choose a separate CSS-class for the results <TD>-tag.

[col_name]: Title
[col_number]: 2
[col_type]: TEXT
[col_cssclass]: tutorial3_title
Case 3: Column definitions of the field “Short”

We call the third column (= [col_number] 3), which is tt_news.short (ref. to the query), “Short”. The column type is TEXT. And finally as we did above, we choose a separate CSS-class for the results <TD>-tag.

[col_name]: Short
[col_number]: 2
[col_type]: TEXT
[col_cssclass]: tutorial3_short
Case 3: Column definitions of the field “Author”

We call the last column (= [col_number] 4), which is tt_news.author (ref. to the query), “Author”. The column type is TEXT. We wrap some text around the result value and finally we choose as CSS-class “tutorial3_author”.

[col_name]: Author
[col_number]: 2
[col_type]: TEXT
[col_wrap]: (Author: |)
[col_cssclass]: tutorial3_author

Ok, we have finished all relevant column definition records. The final result looks like this:

Select Pro Maintable

TT_NEWS

Select Pro Columndefinitions

  • Datetime
  • Title
  • Short
  • Author
Case 3: Inserting a frontend plugin

Please refer to the chapter 'Configuration' of this documentation. Remember that you have to set the startingpoint, which in this tutorial case should point at the page, that we called “Tutorial 3” before.

*Congratulations, you finished the tutorial case 3!*

Case 3: Example
A (german) example of this tutorial case can be found at:
http://www.gst-service.de/index.php?select_pro

Known problems

Page browser (result browser) has difficulties with frames.

Location of the HTML templates [templatefile]: There is one report about an installation where webroot and typo3 installation path were different. There was no chance to give a fitting path and filename for the HTML template. (1 Report, still working on that theme.)

To-Do list

Optimization of the included page browser or exchanging the page browser with pi_list_browseresults (planned for 03/2004).

Optional result display with combobox.

Checking the template localisation problem mentioned above (planned for: later).

Changelog

Version 1.0.0 (BETA)

Version

Version 1.0.0 (BETA)

Changes

Passing GET-variables to SQL-query.

Date

06-11-2005

Version 0.9.1 (BETA)

Version

Version 0.9.1 (BETA)

Changes

UseContUid added.

Date

02-28-2004

Version 0.9.0 (BETA)

Version

Version 0.9.0 (BETA)

Changes

All modifications of 01-12-2004 go to new subversion.

Date

01-12-2004

Version 0.9.0 (BETA)

Version

Version 0.9.0 (BETA)

Changes

New subpart ###SEPARATOR_ITEM### and new parameter unsetLastSeparator.

Date

01-12-2004

((Unknown Property))

Version

Changes

Subpart ###TOPCONTENT_TABLE### renamed to ###SELECTPRO_TABLE### (bugfix).

IMPORTANT NOTE : If you have created own HTML templates, then replace all subparts ###TOPCONTENT_TABLE### by ###SELECTPRO_TABLE###.

Date

01-12-2004

Version 0.9.0 (BETA)

Version

Version 0.9.0 (BETA)

Changes

Performance update in case of sql_whereadd_override-parameter set. (Thanx to Martin Joisten!)

Date

01-12-2004

Version 0.9.0 (BETA)

Version

Version 0.9.0 (BETA)

Changes

Each column can be linked by tablefields ([col_linkcolname]).

Date

01-12-2004

Version 0.9.0 (BETA)

Version

Version 0.9.0 (BETA)

Changes

Some bugfixes.

Date

01-12-2004

Version 0.9.0 (BETA)

Version

Version 0.9.0 (BETA)

Changes

Typo3-parseFunc for columns of the type TEXT implemented.

Date

01-12-2004

Version 0.9.0 (BETA)

Version

Version 0.9.0 (BETA)

Changes

Using stdWrap as an array. Each column now can be separately configured.

IMPORTANT NOTE : Modifications in your TypoScript are required, if you are using stdWrap! Please refer to this documentation to see how to do.

Date

01-12-2004

Version 0.8.1 (BETA)

Version

Version 0.8.1 (BETA)

Changes

Italian and romanian language added. Thanx for that!

Date

12-03-2003

Version 0.8.0 (BETA)

Version

Version 0.8.0 (BETA)

Changes

New treatment of images: Reading the default path from the TCA and allow users to add via TypoScript some other folders. For this function I wish to thank Dominic Brander, who coded that!

Date

12-03-2003

Version 0.7.6 (BETA)

Version

Version 0.7.6 (BETA)

Changes

Some documentation bugs (i.e. Tutorial Case 3) removed.

Date

07-07-2003

Version 0.7.5 (BETA)

Version

Version 0.7.5 (BETA)

Changes

New parameter useResForTempl. Code optimization concerning hidden or deleted pages. Treating the case of forgotten recsMax parameter.

Date

07-07-2003

Version 0.7.4 (BETA)

Version

Version 0.7.4 (BETA)

Changes

Several live tests successful, so switching to BETA-state. Polish language added. Thanx for that!

Date

05-06-2003

Version 0.7.3 (ALPHA)

Version

Version 0.7.3 (ALPHA)

Changes

Finnish language added. Thanx for that!

Date

05-04-2003

Version 0.7.2 (ALPHA)

Version

Version 0.7.2 (ALPHA)

Changes

New parameter queryPid. Link code optimization. Further testing. Live implementations. Tutorials finished.

Date

05-04-2003

Version 0.7.1 (ALPHA)

Version

Version 0.7.1 (ALPHA)

Changes

Code optimization. Documentation updated.

Date

05-03-2003

Version 0.7.0 (ALPHA)

Version

Version 0.7.0 (ALPHA)

Changes

First published version.

Date

05-02-2003

img-23 EXT: Select Pro - 19