Display Comma Separated Lists (CSV)¶

What does it do?¶

cag_longlist allows you to easily present structured data as a searchable and sortable table in the frontend of a website. The datasource can be either an imported CSV file (text file containing comma separated values) or a SQL query against the TYPO3 database.

Features:

• Full text search
• Alphanumerically sortable columns
• Autofilter per column
• Automatic page browser
• Frontend output based on HTML templates

This extension was originally developed for the TYPO3 agency Connecta AG in Wiesbaden, Germany ( http://www.connecta.ag/produkte/typo3.html).

Screenshots¶

Overview¶

This chapter guides you through the process of setting up cag_longlists, importing a CSV file and displaying its content in the frontend of your website. If you plan to use the database in place of a CSV file as your data source, please read this chapter anyway, since most steps are identical or similar.

The process consists of the following steps:

Preparing your CSV file

Installing the cag_longlists extension

Creating a page containing the cag_longlists plugin

Adapting the HTML template to your CSV file

Setting the parameters in the plugin flexform

Preparing your CSV file¶

CSV is a file format for exchanging data between applications which are using structured data like tables or lists. CSV files are text files containing one table row per line. The first line usually contains the column names. Despite its name the table cells within a row are typically separated by a semicolon and not by a comma. To learn more about the CSV format please refer to http://en.wikipedia.org/wiki/Comma-separated_values .

The most common way to create a CSV file is to export it from a spreadsheet application like Microsoft Excel or OpenOffice.org Calc. If your spreadsheet application offers these options you should choose the following settings:

• Character set = Unicode UTF-8
• Field delimiter = ;
• Text Delimiter = "

Please note: To avoid any problems with cag_longlists p lease make sure that column names in your table don't contain any blanks or special characters before exporting your CSV file.

Installing the cag_longlists extension¶

The process of installing the extension is straight forward: Simply go the the Extension Manager of your TYPO3 installation and import cag_longlists as you would do with any other extension.

There are no configuration parameters for cag_longlists in the Extension Manager.

Creating a page containing the cag_longlists plugin¶

You can insert the cag_longlists plugin on any page you wish, even in combination with other plugins. However, in this manual we assume that you create a new page first and add the plugin as a content element. In the New Content Element Wizard you choose the following entry (listed in the plugin section):

At this point it's a good idea to check whether the extension is working properly so far. Since cag_longlist comes with a demo CSV file and preconfigured parameters it works out of the box. When you call the page with the cag_longlists plugin in the frontend you should see something like this (the formatting will of course be different, depending on your CSS styles):

Please note: If you see markers like ###SOMETEXT### in the frontend of your website during the following process it's very likely that there is a mismatch between your CSV file, your plugin settings and your HTML template. If you follow the rest of this manual carefully you should be able to solve this problem.

It's a good idea to spend a moment looking at this demo table, since understanding its elements will help you setting the parameters in the plugin flexform later.

Just below the page title you can see the search form . You can disable it in the plugin settings if you wish, but obviously this search function is one of the main advantages of this extension.

Below the search form there is the table which displays the content of your CSV file. As you would expect there are column titles – some of them are implemented as links, some as dropdown menues. Clicking on the links will sort the respective column, while using a dropdown menu (we call them autofilter ) will filter the respective column. You probably will be familiar with these concepts from other applications or websites.

At the bottom you can choose a page to be displayed. This part is called the page browser , and its only visible if the page exceeds a certain number of rows (which can be configured in the plugin settings).

Adapting the HTML template to your CSV file¶

To make cag_longlists work properly it's essential to adapt the HTML template to your CSV file. By default the extension is using the HTML template that is stored in the extension directory at

typo3conf/ext/cag_longlists/example/cag_longlists.html

Before making any changes to the template you should copy it to your fileadmin directory and work only on this copy. To see the effect of your changes it's a good idea to change the template path in the flexform of the plugin at this point. In the “Common” tab there is field called “Template File” which is set to

EXT:cag_longlists/example/cag_longlists.html

by default. Change it according to the place where you put your copy of the HTML template, i.e.

fileadmin/templates/cag_longlists.html

Now let's make the necessary changes in the HTML template. Basically this is about how the column heads should look like and in which order they appear. For this purpose you have to edit only the ###HEAD### subpart of the template; you don't have to touch the rest of the HTML template for making the extension working properly.

As we have seen before there are to types of column titles in the default template: links and dropdown menues. Let's start with links which are easier to understand.

<th>
        <a href="###SORT_URL_COL1_ASC###">A,B,C</a>
</th>

<th>
        ###LIST_TOPIC###
        <select onchange="document.getElementById('cag_form').submit();" name="tx_caglonglists_pi1[topic]" id="cag_longlist_sel1">
                ###ROW###
                <option value="###ID###" ###SELECTED###>###VALUE###</option>
                ###ROW###
        </select>
        ###LIST_TOPIC###
</th>

Setting the parameters in the plugin flexform¶

Most parameters in the plugin flexform are preset to match the demo CSV file. To use your own CSV file you have to adapt these settings. It's a good idea to change only a few parameters at a time and to check frequently the result in the frontend. This will help you to understand the details of each parameter.

EXT:cag_longlists/example/cag_longlists.html

fileadmin/templates/cag_longlists.html

city=Zurich,type=Restaurant,allfields=Santa Lucia

city,type,kitchen,rating,allfields

name,city,address,type,kitchen,rating,comments

fileadmin/documents/swiss_restaurants.csv

Default HTML Template¶

###SECTION_SEARCHFORM###
<form id="cag_form" method="post" action="###FORMACTION###">
<!-- The searchform: optional (Can be enabled / Disabled in yourflexform configuration) -->
<input id="searchfield" type="text" maxlength="120" size="15" value="###ALLFIELDS_VALUE###" name="tx_caglonglists_pi1[allfields]"/>
<input id="submitbutton" class="longlistsubmit" type="submit" value="search" name="submitform"/>
###SECTION_SEARCHFORM###

###SECTION_RESULT###
<div class="longlist_result">
    ###TABLE###
      <table>
      <!-- Result Table Head: Please Adapt Head to the columns you are displaying (as configured in your Flexform/Plugin configuration -->
      <tr class="addresshead">
        ###HEAD###
        <th>
            <a href="###SORT_URL_COL1_ASC###">A,B,C</a>
        </th>

        <th>
            ###LIST_TOPIC###
            <select onchange="document.getElementById('cag_form').submit();" name="tx_caglonglists_pi1[topic]" id="cag_longlist_sel1">
                ###ROW###
                <option value="###ID###" ###SELECTED###>###VALUE###</option>
                ###ROW###
            </select>
            ###LIST_TOPIC###
        </th>
        <th>
            ###LIST_TERM###
            <select name="tx_caglonglists_pi1[term]" onchange="document.getElementById('cag_form').submit();" id="cag_longlist_sel2">
                ###ROW###
                <option value="###ID###" ###SELECTED###>###VALUE###</option>
                ###ROW###
            </select>
            ###LIST_TERM###
        </th>
        <th>
           <a href="###SORT_URL_MY_COL4_ASC###"> My Column 4</a>
        </th>
        ###HEAD###
      </tr>

      <!-- Result Table Body: Don't change anything here-->
      ###ROWS###
      <tr class="###ODDEVEN###, longlistrow">
        ###ROW###<td>###COLUMN###</td>###ROW###
      </tr>
      ###ROWS###

      </table>
    ###TABLE###
</div>
</form>
###SECTION_RESULT###

<!-- The page browser (in case you have more results than the configured value "results per pages"  -->
###SECTION_PAGELIST###
<div class="longlist_pages">
    <p />
    <p />
    ###PAGES###
        ###ROW###&nbsp;<a href="###LINK###">Page&nbsp;###NUMBER###</a> |###ROW###
    ###PAGES###
</div>
###SECTION_PAGELIST###

How do I define the order of the table columns?¶

The order of the columns content is defined by the field “Display which columns?” in the plugin flexform.

The order of the columns headers is defined in the HTML template.

Is there a rule when to use UPPERCASE, Mixedcase or lowercase letters for column names?¶

As a basic rule you use UPPERCASE column names in the HTML template and lowercase letters in the plugin flexform.

How can I set the default sorting (Column and Sort-Direction)?¶

The default column to sort by can be set in the via typoscript – for example:# Set the default sorting direction (valid values are “asc” for ascending and “desc” for descending)plugin.tx_caglonglists_pi1.sortDirectionDefault = desc#set the default column to sort byplugin.tx_caglonglists_pi1.sortByDefault = my_column_name

Is there a static template to be included in the TypoScript template?¶

No. There was a static template in earlier versions of the extension, but it was not needed for the extension to work properly. In the most recent version of the extension the static template doesn't exist anymore.

2010-08-11¶

Fixed an issue with alternating row colors / markersThe problem was that ODDEVEN was not replaced/substituted in a HTML/CSS template(Thanks to Daniel Krupke for the patch)

2010-03-16¶

Default Sort direction can be configured now (asc for ascending or desc for descending)

plugin.tx_caglonglists_pi1.sortDirectionDefault = desc

plugin.tx_caglonglists_pi1.sortByDefault = my_column_name

Updated Manual

2009-10-18¶

Manual completely rewritten

2009-06-12¶

Database as datasource fixed

Major improvements to the manual by request

Extension now works out of the box with an included example

13