.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt =================================== Display Comma Separated Lists (CSV) =================================== :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed by: Jens-Wolfram Eipel :Changed: 2010-08-11T17:10:54 :Classification: cag_longlists :Description: Searchform and browsable searchresult page for searching in CSV-Files :Keywords: CSV, Searchable, Search Engine :Author: Dipl.-Ing. Jens-Wolfram Eipel :Email: j.eipel@connecta.ag :Info 4: connecta AG Wiesbaden, www.connecta.ag :Language: en |img-1| |img-2| Display Comma Separated Lists (CSV) - cag\_longlists .. _Display-Comma-Separated-Lists-CSV: Display Comma Separated Lists (CSV) =================================== Extension Key: cag\_longlists Language: en Keywords: CSV, Searchable, Search Engine Copyright 2000-2008, Dipl.-Ing. Jens-Wolfram Eipel, 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.org `_ Developed by Connecta AG Wiesbaden ( `www.connecta.ag `_ ) Manual by Jens-Wolfram Eipel (Connecta AG) and Martin Sauter (Futurecom interactive AG, `www.futurecom.ch `_ ) .. _Table-of-Contents: Table of Contents ----------------- `Display Comma Separated Lists (CSV) 1 <#1.Display%20Comma%20Separated%20Lists%20(CSV)|outline>`_ **`Introduction 3 <#1.1.Introduction|outline>`_** `What does it do? 3 <#1.1.1.What%20does%20it%20do_|outline>`_ `Screenshots 3 <#1.1.2.Screenshots|outline>`_ **`Users manual 5 <#1.2.Users%20manual|outline>`_** `Overview 5 <#1.2.1.Overview|outline>`_ `Preparing your CSV file 5 <#1.2.2.Preparing%20your%20CSV%20file|outline>`_ `Installing the cag\_longlists extension 5 <#1.2.3.Installing%20the%20cag_longlists%20extension|outline>`_ `Creating a page containing the cag\_longlists plugin 5 <#1.2.4.Creati ng%20a%20page%20containing%20the%20cag_longlists%20plugin|outline>`_ `Adapting the HTML template to your CSV file 6 <#1.2.5.Adapting%20the% 20HTML%20template%20to%20your%20CSV%20file|outline>`_ `Setting the parameters in the plugin flexform 8 <#1.2.6.Setting%20the %20parameters%20in%20the%20plugin%20flexform|outline>`_ **`Reference 11 <#1.3.Reference|outline>`_** `Default HTML Template 11 <#1.3.1.Default%20HTML%20Template|outline>`_ **`FAQ 12 <#1.4.FAQ|outline>`_** `How do I define the order of the table columns? 12 <#2.How%20do%20I%2 0define%20the%20order%20of%20the%20table%20columns_|outline>`_ `Is there a rule when to use UPPERCASE, Mixedcase or lowercase letters for column names? 12 <#3.Is%20there%20a%20rule%20when%20to%20use%20UPP ERCASE,%20Mixedcase%20or%20lowercase%20letters%20for%20column%20names_ |outline>`_ `How can I set the default sorting (Column and Sort-Direction)? 12 <#4.How%20can%20I%20set%20the%20default%20sorting%20(Column%20and %20Sort-Direction)_|outline>`_ `Is there a static template to be included in the TypoScript template? 12 <#4.0.1.Is%20there%20a%20static%20template%20to%20be%20included%20i n%20the%20TypoScript%20template_|outline>`_ **`Changelog 13 <#4.1.Changelog|outline>`_** `2010-03-16 13 <#4.1.1.2010-03-16|outline>`_ `2009-10-18 13 <#4.1.2.2009-10-18|outline>`_ `2009-06-12 13 <#4.1.3.2009-06-12|outline>`_ .. _Introduction: Introduction ------------ .. _What-does-it-do: 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: Screenshots ^^^^^^^^^^^ |img-3| |img-4| .. _Users-manual: Users manual ------------ .. _Overview: 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: 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: 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: 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): |img-5| 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): |img-6| **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: 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 |img-7| 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. .. _Links: Links """"" At the beginning of the ###HEAD### subpart you will find the following code: :: A,B,C The interesting part is of course the marker ###SORT\_URL\_COL1\_ASC###. Let's have a look a the elements of this marker: .. ### BEGIN~OF~TABLE ### .. _SORT-URL: **SORT\_URL** ~~~~~~~~~~~~~ .. container:: table-row a **SORT\_URL** b This is the keyword for a sortable column. .. _COL1: **COL1** ~~~~~~~~ .. container:: table-row a **COL1** b This is the column name. Change this to match the column name in your CSV file, but use UPPERCASE LETTERS (even if the column name in your CSV file is Mixedcase or lowercase). .. _ASC: **ASC** ~~~~~~~ .. container:: table-row a **ASC** b This is the sort order. There are three different options for this as shown in the following examples: - ###SORT\_URL\_COL1\_ASC### (ascending sort order) - ###SORT\_URL\_COL1\_DESC### (descending sort order) - ###SORT\_URL\_COL1### (alternating sort order for every click) .. ###### END~OF~TABLE ###### .. _Dropdown-menues-autofilters: Dropdown menues (autofilters) """"""""""""""""""""""""""""" If you go further in the HTML template you will find the following code: :: ###LIST_TOPIC### ###LIST_TOPIC### Although this code looks a little bit more complex, adapting it to your needs is easy: You only have to change the column name (which is “TOPIC” in the above example) according to the column name in your CSV file. There are three occurrences of the column name: ###LIST\_TOPIC### (at the beginning of the subpart; use UPPERCASE LETTERS here) name="tx\_caglonglists\_pi1[topic]" (as a parameter in the SELECT tag; use lowercase letters here) ###LIST\_TOPIC### (at the end of the subpart; use UPPERCASE LETTERS here) In addition you have to make sure that the ID of your SELECT tag is unique in your template. This means that if you use id="cag\_longlist\_sel1" here your next dropdown menu should have id="cag\_longlist\_sel2" and so on. .. _Setting-the-parameters-in-the-plugin-flexform: 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. .. _Common-section: “Common” section """""""""""""""" |img-7| **Data Source Mode** Source of the data to be displayed on the frontend page. Choose between “CSV” and “Database”. Depending on this selection you have to set additional parameters in the “CSV” or “Database” tab respectively. **Debug Mode** Whether or not to show debug information. **Show Searchform** Whether or not to show the search field in the frontend to allow fulltext searches in your data. **Template File** Path to the HTML-Template file to be used. By default this setting refers to the HTML template provided with the extension: :: EXT:cag_longlists/example/cag_longlists.html If your HTML template resides in the fileadmin directory the path will look somehow like this: :: fileadmin/templates/cag_longlists.html **Results per Page** The number of table rows to be displayed per page. If the total number of rows exceeds this number the table will be split into multiple pages and the page browser will be displayed. **URL Parameter to Process** A comma-separated list with the names of all sortable columns plus all autofilter columns as they are defined in your HTML template. Please make sure to set all column names to lowercase. If you are using the search form you must add “allfields” as an additional value in this flexform field. This list tells the extension basically what variables in the query string should be processed. **Default Values in Searchform** Default search term for the search field plus default values for the autofilters. Example: :: city=Zurich,type=Restaurant,allfields=Santa Lucia The keyword “allfields” refers to the search field while all other keywords in this example are column names. Please note: This option only sets the values but does not execute the filtering or searching process, so the website visitor has to do this manually. **Filter on Fields** A comma-separated list with the names of all autofilter columns as they are defined in your HTML template, plus (if you are using the search form) the keyword “allfields”. Please make sure to set all column names to lowercase. Example: :: city,type,kitchen,rating,allfields Please note: Make sure to enter all autofilter columns in the flexform field “URL Parameter to Process” as well (see above). **Display which Columns** A comma-separated list with the names of all columns in your CSV file to be displayed on the frontend page. Please make sure to set all column names to lowercase. Example: :: name,city,address,type,kitchen,rating,comments .. _CSV-Section: “CSV” Section """"""""""""" Your data source may either be a CSV file or the database. If you set Data Source Mode to “CSV” in the “Common” section (see above) then you must configure the following parameters. |img-8| **CSV File** Path to the CSV file, typically somewhere in the fileadmin folder. Example: :: fileadmin/documents/swiss_restaurants.csv **CSV Delimiter** The character that was used to separate the column values when creating the CSV file (see chapter “Preparing your CSV file” in this manual). This is usually a semicolon (;) or sometimes a comma (,). **Fields to Make Selectbox** A comma-separated list with the names of all autofilter columns. Please note: This flexform field must contain the same column names as the flexform field “Filter on Fields” in the “Common” section. .. _Database-Section: “Database Section” """""""""""""""""" Your data source may either be a CSV file or the database. If you set Data Source Mode to “Database” in the “Common” section (see above) then you must configure the following parameters. **Please note: Using the database as your data source requires advanced knowledge about TYPO3, databases and SQL. Choose this option only if you know what you are doing – otherwise you may loose your data or destroy your TYPO3 installation. This manual does not cover the process of creating your own table in the database and of entering data.** |img-9| **Query** SQL statement used to select the data to be displayed on the frontend page. **Fields to Make Selectbox of** A comma-separated list with the names of all autofilter columns. Please note: This flexform field must contain the same column names as the flexform field “Filter on Fields” in the “Common” section. .. _Reference: Reference --------- .. _Default-HTML-Template: Default HTML Template ^^^^^^^^^^^^^^^^^^^^^ :: ###SECTION_SEARCHFORM###
###SECTION_SEARCHFORM### ###SECTION_RESULT###
###TABLE### ###HEAD### ###HEAD### ###ROWS### ###ROW######ROW### ###ROWS###
A,B,C ###LIST_TOPIC### ###LIST_TOPIC### ###LIST_TERM### ###LIST_TERM### My Column 4
###COLUMN###
###TABLE###
###SECTION_RESULT### ###SECTION_PAGELIST###

###PAGES### ###ROW### Page ###NUMBER### |###ROW### ###PAGES###

###SECTION_PAGELIST### .. _FAQ: FAQ --- .. _How-do-I-define-the-order-of-the-table-columns: 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: 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: 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: 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. |img-10| .. _Changelog: Changelog --------- .. _2010-08-11: 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: 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: 2009-10-18 ^^^^^^^^^^ Manual completely rewritten .. _2009-06-12: 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 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. |img-2| image:: img-2.png .. :border: 0 .. :height: 21 .. :hspace: 9 .. :id: Grafik2 .. :name: Grafik2 .. :width: 87 .. |img-3| image:: img-3.png .. :border: 0 .. :height: 614 .. :id: graphics1 .. :name: graphics1 .. :width: 533 .. |img-4| image:: img-4.png .. :align: bottom .. :border: 0 .. :height: 435 .. :id: graphics2 .. :name: graphics2 .. :width: 405 .. |img-5| image:: img-5.png .. :align: bottom .. :border: 0 .. :height: 38 .. :id: Grafik1 .. :name: Grafik1 .. :width: 405 .. |img-6| image:: img-6.png .. :align: bottom .. :border: 0 .. :height: 435 .. :id: Grafik4 .. :name: Grafik4 .. :width: 669 .. |img-7| image:: img-7.png .. :border: 0 .. :height: 362 .. :id: Grafik5 .. :name: Grafik5 .. :width: 580 .. |img-8| image:: img-8.png .. :align: bottom .. :border: 0 .. :height: 169 .. :id: Grafik7 .. :name: Grafik7 .. :width: 347 .. |img-9| image:: img-9.png .. :align: bottom .. :border: 0 .. :height: 196 .. :id: Grafik8 .. :name: Grafik8 .. :width: 519 .. |img-10| image:: img-10.png .. :align: middle .. :border: 0 .. :height: 177 .. :id: Grafik3 .. :name: Grafik3 .. :width: 580