.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ================================= EXT: Tag Pack-based Data Provider ================================= :Created: 2010-02-18T17:33:18 :Changed: 2012-06-26T14:56:02 :Classification: tagpackprovider :Description: The keywords help with categorizing and tagging of the manuals. You can combine two or more keywords and add additional keywords yourself. Please use at least one keyword from both lists. If your manual is NOT in english, see next tab "language" ---- forEditors (use this for editors / german "Redakteure") forAdmins (use this for Administrators) forDevelopers (use this for Developers) forBeginners (manuals covering TYPO3 basics) forIntermediates (manuals going into more depth) forAdvanced (covering the most advanced TYPO3 topics) see more: http://wiki.typo3.org/doc_template#tags ---- :Keywords: forAdmins, forIntermediates, tesseract :Author: François Suter :Email: typo3@cobweb.ch :Info 4: :Language: en |img-1| |img-2| EXT: Tag Pack-based Data Provider - tagpackprovider .. _EXT-Tag-Pack-based-Data-Provider: EXT: Tag Pack-based Data Provider ================================= Extension Key: tagpackprovider Language: en Keywords: forAdmins, forIntermediates, tesseract Copyright 2010-2012, François Suter, 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 .. _Table-of-Contents: Table of Contents ----------------- `EXT: Tag Pack-based Data Provider 1 <#__RefHeading__6469_1494229217>`_ **`Introduction 3 <#__RefHeading__6471_1494229217>`_** `What does it do? 3 <#__RefHeading__6473_1494229217>`_ `Screenshots 3 <#__RefHeading__6475_1494229217>`_ `Credits 3 <#__RefHeading__6477_1494229217>`_ `Questions? 3 <#__RefHeading__6479_1494229217>`_ `Keeping the developer happy 3 <#__RefHeading__6481_1494229217>`_ **`Installation 4 <#__RefHeading__6483_1494229217>`_** `Dependencies 4 <#__RefHeading__6485_1494229217>`_ `Compatibility 4 <#__RefHeading__5030_66368504>`_ **`Users manual 5 <#__RefHeading__6487_1494229217>`_** `Warning 7 <#__RefHeading__343_859150360>`_ **`Behind the scenes 8 <#__RefHeading__6489_1494229217>`_** **`Known problems 9 <#__RefHeading__6491_1494229217>`_** **`To-Do list 10 <#__RefHeading__6493_1494229217>`_** .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ This extension is part of the Tesseract Project. It relies on tags from the Tag Pack extension to select records from various tables. Acting as a secondary Data Provider, it can feed these records to a primary Data Provider. Tags can be selected manually or using expressions. .. _Screenshots: Screenshots ^^^^^^^^^^^ Here's a view of a typical tag selection: .. _img-3-Credits: |img-3| Credits ^^^^^^^^^^^^^^^ This extension makes use of the excellent Tag Pack extension developed mostly by Joey Hasenau. If you don't know what Tag Pack is, go and check it out in the TER (key: “tagpack”), it is a brilliant tool! .. _Questions: Questions? ^^^^^^^^^^ If you have any questions about this extension, please ask them in the TYPO3 English mailing list (typo3.english), so that others can benefit of the answers. .. _Keeping-the-developer-happy: Keeping the developer happy ^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you like this extension, do not hesitate to rate it. Go the Extension Repository, search for this extension, click on its title to go to the details view, then click on the “Ratings” tab and vote. Every new vote keeps the developer ticking. So just do it! You may also take a step back and reflect about the beauty of sharing. Think about how much you are benefiting and how much yourself is giving back to the community. .. _Installation: Installation ------------ Installing this extension is pretty straightforward. Just download it from the TER and activate it. You will be requested to create a new table in the database, which will be used to store tag selections. After installation, this extension provides a single configuration option: **Tagged Tables** : this is a comma-separated list of tables for which tags can be selected. This is meant to reduce the choice faced by the user when creating a tag selection. It can be left empty, in which case the list of available tables will match the list of tables that can be tagged with the Tag Pack. .. _Dependencies: Dependencies ^^^^^^^^^^^^ Obviously this extension depends on “tagpack”. It also requires the “expressions” extension, since expressions can be used to select tags. And of course it is meant to operate as a Tesseract Data Provider. It is probably rather useless outside of that scope. .. _Compatibility: Compatibility ^^^^^^^^^^^^^ As of version 1.2.0, TYPO3 4.5 or more is required. .. _Users-manual: Users manual ------------ The Tag Pack Provider makes it possible to restrict a recordset to a selection of records made by using tags from the Tag Pack extension. Here's an example of a content element tagged with the tag “test”: |img-4| To create a selection of content elements based on that tag, let's create a new Tag Pack Selection and enter the following information: |img-5| This is the simplest selection one can make: a table and a tag. With this information the Tag Pack provider will find all content elements that were tagged with tag “test”. This selection can then be used as a Secondary Provider in a Display Controller content element: |img-6| The “Content elements” Data Query is a simple SELECT statement without any condition, which means it will retrieve all content element records. Coupled with the Tag Pack Selection – however – it will be restricted to the list of content elements found by the Tag Pack Provider. Expressions can also be used to select tags. The example below retrieves a tag id from a GET/POST variable named “tag” (another expression is commented out): |img-3| Here's a list of all the fields that can be defined in a Tag Pack Selection: .. ### BEGIN~OF~TABLE ### .. _Name: Name ^^^^ .. container:: table-row Field Name Usage Just the selection's name. .. _Tables: Tables ^^^^^^ .. container:: table-row Field Tables Usage List of tables from which records should be selected. .. _Tags-manual-selection: Tags (manual selection) ^^^^^^^^^^^^^^^^^^^^^^^ .. container:: table-row Field Tags (manual selection) Usage Simple selector for choosing specific tags from the existing ones. .. _Tags-from-expressions: Tags from expressions ^^^^^^^^^^^^^^^^^^^^^ .. container:: table-row Field Tags from expressions Usage This field can be used to enter expressions (one per line) that return uids of existing tags. Accepted values are either single number or comma-separated lists of uids. .. _Override-manual-selection: Override manual selection ^^^^^^^^^^^^^^^^^^^^^^^^^ .. container:: table-row Field Override manual selection Usage By default this box is checked. It means that tags gotten from expression will override manually-selected tags. Uncheck this box to tags from both fields. .. _Logical-operator: Logical operator ^^^^^^^^^^^^^^^^ .. container:: table-row Field Logical operator Usage By default, the Tag Pack Provider will return all records that match at least one tag (OR). It can be forced to return only records that match **all** the selected tags (AND). Note that this operation requires additional calculations so it more performance intensive. .. ###### END~OF~TABLE ###### .. _Warning: Warning ^^^^^^^ The Tag Pack Provider currently does **not** support Data Filters. So do not be surprised if you define a Data Filter and it does not seem to have any influence. .. _Behind-the-scenes: Behind the scenes ----------------- This chapter describes what the Tag Pack Provider does from a more technical point of view. First all tags from the manual selection are taken and then all tags resulting from expressions. If the override parameter is set, only the tags resulting from expressions (if any) are taken into account. Otherwise both lists of tags are merged together. The Tag Pack Provider then takes care that every tag appears only once. Next all records from the selected tables that match at least one tag are fetched. If the logical operator is “OR”, there's nothing more to do. If it is “AND” some more processing takes place. The Tag Pack Provider loops on all records and restrict its choice records that match **all** the selected tags and not just one of them. When done the Tag Pack Provider returns a Standardized Data Structure of type “idList”, which will contain the list of the primary keys (uid's) of all records that were found. This list of keys is fed into the primary Data Provider to restrict its results. In the case of Data Query, for example, the list of primary keys is transformed into a SQL WHERE condition using the IN() clause. .. _Known-problems: Known problems -------------- There is a weird border case when a Tag Pack Selection on several tables returns nothing for the table that is the main table in a join in the Primary Provider. Let's take an example: imagine selecting (using a Data Query) image- type content elements and joining them to the DAM records they refer to. This query is restricted by a Tag Pack Selection that selects records from both of these tables. Now if the Tag Pack Provider returns nothing for the tt\_content table, but something for the tx\_dam table. If you have check the “Display nothing” flag you would expect the result to be empty, because no content elements were found by the Tag Pack Provider. But since there were some tx\_dam records found, the Tag Pack Provider is not seen as empty, the query goes ahead and selects all content elements, since there was no uid list given. If you find other bugs, please report them in the Forge bug tracker (http://forge.typo3.org/projects/extension-tagpackprovider/issues). .. _To-Do-list: To-Do list ---------- Nothing is planned for now. If you have feature requests, please open a report in the Forge bug tracker (http://forge.typo3.org/projects /extension-tagpackprovider/issues). 10 .. ######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 .. :align: left .. :border: 0 .. :height: 469 .. :id: graphics1 .. :name: graphics1 .. :vspace: 8 .. :width: 669 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 210 .. :id: graphics2 .. :name: graphics2 .. :vspace: 8 .. :width: 433 .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :height: 476 .. :id: graphics3 .. :name: graphics3 .. :vspace: 8 .. :width: 536 .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :height: 432 .. :id: graphics4 .. :name: graphics4 .. :vspace: 8 .. :width: 625