.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ============= EXT: Tag Pack ============= :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed by: JoH asenau :Changed: 2009-05-30T20:34:20.510000000 :Classification: tagpack :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: Tags, Tagging, Tagged, Metadata, Tagcloud, Resultlist, Folksonomy, forEditors, forAdmins, forDevelopers, forBeginners, forIntermediate, forAdvanced :Author: JoH asenau :Email: info@cybercraft.de :Info 4: :Language: en |img-1| |img-2| EXT: Tag Pack - tagpack .. _EXT-Tag-Pack: EXT: Tag Pack ============= Extension Key: tagpack Language: en Keywords: Tags, Tagging, Tagged, Metadata, Tagcloud, Resultlist, Folksonomy, forEditors, forAdmins, forDevelopers, forBeginners, forIntermediate, forAdvanced Copyright 2000-2009, JoH asenau, 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 1 <#1.EXT:%20Tag%20Pack|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>`_ **`Installation 4 <#1.2.Installation|outline>`_** `Tag Container 4 <#1.2.1.Tag%20Container|outline>`_ `TSconfig to enable tagging 4 <#1.2.2.TSconfig%20to%20enable%20tagging|outline>`_ `FAQ 4 <#1.2.3.FAQ|outline>`_ **`Users manual 5 <#1.3.Users%20manual|outline>`_** `FAQ 5 <#1.3.1.FAQ|outline>`_ **`Administration 6 <#1.4.Administration|outline>`_** `FAQ 6 <#1.4.1.FAQ|outline>`_ **`Configuration 7 <#1.5.Configuration|outline>`_** `FAQ 7 <#1.5.1.FAQ|outline>`_ `Reference 7 <#1.5.2.Reference|outline>`_ **`Tutorial 10 <#1.6.Tutorial|outline>`_** **`Known problems 11 <#1.7.Known%20problems|outline>`_** **`To-Do list 12 <#1.8.To-Do%20list|outline>`_** **`ChangeLog 13 <#1.9.ChangeLog|outline>`_** `Important guidelines 15 <#2.Important%20guidelines|outline>`_ **`HowTo update a manual to the new layout 16 <#2.1.HowTo%20update%20a %20manual%20to%20the%20new%20layout|outline>`_** **`Issues with Open Office documentation for TYPO3 17 <#2.2.Issues%20w ith%20Open%20Office%20documentation%20for%20TYPO3|outline>`_** `Inserting images 17 <#2.2.1.Inserting%20images|outline>`_ `Paragraph styles 17 <#2.2.2.Paragraph%20styles|outline>`_ `Linking 18 <#2.2.3.Linking|outline>`_ `Meta data and updates 18 <#2.2.4.Meta%20data%20and%20updates|outline>`_ `Help by documentation.openoffice.org 18 <#2.2.5.Help%20by%20documentation.openoffice.org|outline>`_ .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ The Tag Pack offers a sophisticated way of tagging records of almost any available table in the TYPO3 database without having to create additional fields for each of them. It uses virtual fields, that will show up in the TYPO3-backend as usual, together with just two tables – one for the tags and one for the relations of tags and tagged items – easily configurable using TSconfig and TypoScript only. Unlike some other tagging extensions, that are available from TER, the Tag Pack doesn't create the tags automatically based on the content itself. Instead the items have to be manually tagged by editors (BE) or users (FE), which can be done very easily because of the slightly improved AJAX supported find-as-you-type-interface we borrowed from the AJAX group search extension. Additionally the current version of the Tag Pack offers 2 Frontend- Plugins and one Backend-Module - Tagcloud (FE) - Resultlist (FE) - Tag Management (BE) The option of having records tagged by frontend users is not yet finished but planned for one of the next releases. .. _Screenshots: Screenshots ^^^^^^^^^^^ S This section will have a link in the EM, so therefore it's very important that it conveys this message. Target group: Mostly Developers and administrators, but should be a non-technical and visual presentation. This section is required and in some cases it basically tells it all. .. _Installation: Installation ------------ You can install the Tag Pack with the TYPO3 Extension Manager as usual. Just import it directly through the TER or download it from typo3.org and then import it manually. Now you can install it by clicking on the grey icon with the plus symbol on it. During the installation you will be asked to enter some information about the tables you want to be taggable and the folder to put the tags in. If you already got the necessary information you can give it now. If you don't know, just ignore the fields, since you can change the values later on by overriding them using *TSconfig* anyway. Be sure to enter the necessary stuff at least once (during the installation or within *TSconfig* ) otherwise you won't be able to tag any record at all! If you already got a folder for the tags and marked at least one table to be taggable you are now ready to go on, else you will have to do some additional work to enable the tagpack. .. _Tag-Container: Tag Container ^^^^^^^^^^^^^ Since TYPO3 always uses pages to identify the location of a record, you will need at least one page in the page tree that can be used as a container for the tags later on. This has to be a page of the type *Sysfolder* so if you haven't got it yet, go and create one now. Try to give it a meaningful name like i. e. *Tag Container* to make sure other people working with the system can easily find it later. .. _TSconfig-to-enable-tagging: TSconfig to enable tagging ^^^^^^^^^^^^^^^^^^^^^^^^^^ Even if you already entered the tables you want to be taggable you can still override these settings using Tsconfig. For those, who didn't enter any tables during the installation, this step is a must to activate at least one table for tagging! You can use both *Page TSconfig* and *User TSconfig* to enable tagging for a table with *User TSconfig* overriding *Page TSconfig* . If you want to enable tagging via *Page TSconfig* the settings will activate tagging recursively for the whole branch unless you disable them again on a higher level. If you enable it via *User TSconfig* , it will be available for all pages of the tree. So be sure to check out the possible scenarios before you decide which way to go. In both cases the settings are the same. Simply go to the *TSconfig* section of either a page or a user and enter some code like this :: tx_tagpack_tags { taggedTables = tt_news,tt_content getTagsFromPid = 4 } Where taggedTablesshould be a comma separated list of available table names and getTagsFromPidshould be the *uid* of the *Sysfolder* containing the tags. This way you can have different sets of tags for different editors or within different branches of the page tree and this is the reason, why tag names don't have to be unique within the whole database but at least within one container. .. _FAQ: FAQ ^^^ *Q: Why aren't there any fields to be created within the tables that should be tagged?* A: Because the Tag Pack is using a different method of saving information about the connection between records and tags. After all it is enough to use a relation table for this purpose, that contains all the necessary stuff instead of creating a field for each table. Even if there was an additional field available, TYPO3 would fill in just the number of relations to this record anyway, which can easily be counted using SQL when necessary. *Q: How do you get the field into the backend form, if it is not available in the database?* A: The Tag Pack uses some hooks provided by the TYPO3 backend to attach some functions that will add the field to the backend form at runtime to make sure you can enter the data exactly the same way you are used to. *Q: How do you save the data when the form is saved by the editor if there is no field available to contain the necessary information ?* A: Again the Tag Pack uses some hooks and functions to save the data into it's own tables before and after the rest of the data contained in the form actually gets saved. This makes sure that all the information about the tagged record will be available during each database operation that can be executed by the editor in the TYPO3 backend. Even deleting, undeleting, moving, copying and translating are taken into account. .. _Users-manual: Users manual ------------ - Documentation of how to use the extension, how it works, how to apply it if it's a website plugin. A user manual. - Language should be non-technical, explaining, using small examples. - Examples: For the "News" plugin this would be a manual showing how to create the news-items, explaining the options etc. - Target group: Users, Administrators or Developers in that priority. Depends on the extension. .. _FAQ: FAQ ^^^ Possible subsections: FAQ .. _Administration: Administration -------------- - Describes how to manage the extension from a superuser point of view. That relates to Page/User TSconfig, permissions, configuration etc. which administrator level users have access to. - language should be non/semi-technical, explaining, using small examples. - Target group: Administrators .. _FAQ: FAQ ^^^ Possible subsections: FAQ .. _Configuration: Configuration ------------- - Technical information; Installation, Reference of TypoScript, configuration options on system level, how to extend it, the technical details, how to debug it. - language should be technical, assuming developer knowledge of TYPO3. Small examples/visuals are always encouraged. - Target group: Developers .. _FAQ: FAQ ^^^ Possible subsections: FAQ .. _Subheadlines: Subheadlines """""""""""" You can produce subheadlines in a section using “Heading 4” or “Heading 5” (normally used for “Examples”) .. _Reference: Reference ^^^^^^^^^ .. _plugin-tx-tagpack-pi1: plugin.tx\_tagpack\_pi1 """"""""""""""""""""""" USER cObject that renders the tag cloud. .. ### BEGIN~OF~TABLE ### .. _userFunc: userFunc ~~~~~~~~ .. container:: table-row Property userFunc Data type function Description The function which is responsible for the output of this plugin Default tx\_tagpack\_pi1->main .. _renderObj: renderObj ~~~~~~~~~ .. container:: table-row Property renderObj Data type cObject Description The TypoScript object used for the output of this plugin Default COA\_INT .. _tagCloudElements: tagCloudElements ~~~~~~~~~~~~~~~~ .. container:: table-row Property tagCloudElements Data type Description A set of parameters to tell the plugin which content elements and which records should be renderedContains two parameters:enabledContent=> a comma separated list of tt\_content elements to be recognized by the tagcloud functions enabledRecords=> a comma separated list of tables that contain records to be found by the tagcloud functions Default .. ###### END~OF~TABLE ###### .. _Example: Example ~~~~~~~ This example would recognize three different types of content elements (Text, Image and Text /w Image) and records from tt\_news as well. All other records, even if they already got relations to tags would be ignored: :: plugin { tx_tagpack_pi1 = USER tx_tagpack_pi1 { userFunc = tx_tagpack_pi1->main userFunc { tagcloudElements { enabledContent = text,image,textpic enabledRecords = tt_news } renderObj = COA_INT renderObj { 10 = USER 10 { userFunc = tx_tagpack_pi1->makeTagCloud } } } } } This way you will be able to render different tag clouds within different branches of the page tree. They will be depending on their TypoScript settings only regardless how many tables and records have already been tagged by the editors in the backend. But of course it will only make sense to render tables containing records that have been tagged ;-) .. _tx-tagpack-pi1-makeTagCloud: tx\_tagpack\_pi1->makeTagCloud """""""""""""""""""""""""""""" USER function that renders the tag cloud within the plugin. .. ### BEGIN~OF~TABLE ### .. _userFunc: userFunc ~~~~~~~~ .. container:: table-row Property userFunc Data type function Description The function which is responsible for the actual tag cloud Default tx\_tagpack\_pi1->makeTagCloud .. _tagPidList: tagPidList ~~~~~~~~~~ .. container:: table-row Property tagPidList Data type List of integers Description A list of the uids of tag container pages Default .. _targetPid: targetPid ~~~~~~~~~ .. container:: table-row Property targetPid Data type Integer Description The uid of the page that contains the result list of tagged items Default .. _minFontSize: minFontSize ~~~~~~~~~~~ .. container:: table-row Property minFontSize Data type Integer Description Minimum font size (in px) for the links shown in the tag cloud Default 8 .. _maxFontSize: maxFontSize ~~~~~~~~~~~ .. container:: table-row Property maxFontSize Data type Integer Description Maximum font size (in px) for the links shown in the tag cloud Default 20 .. _maxNumberOfSizes: maxNumberOfSizes ~~~~~~~~~~~~~~~~ .. container:: table-row Property maxNumberOfSizes Data type Integer Description The maximum number of different font sizes to be used by the tag cloud including minimum and maximum size Default 20 .. _modeSwitch: modeSwitch ~~~~~~~~~~ .. container:: table-row Property modeSwitch Data type Boolean Description Enables/disables the mode selector that gives users the option to switch between the default mode and the filter mode of the tag cloud Default false .. _searchBox: searchBox ~~~~~~~~~ .. container:: table-row Property searchBox Data type Boolean Description Enables/disables the full text search box that can be used to refine the results of the tag cloud Default false .. _calendar: calendar ~~~~~~~~ .. container:: table-row Property calendar Data type Boolean Description Enables/disables the calendar that can be used to refine the results of the tag cloud withint a certain time frame Default false .. _fontColor: fontColor ~~~~~~~~~ .. container:: table-row Property fontColor Data type color Description The default font color of the links used within the tag cloud Default #000000 .. _generalStdWrap: generalStdWrap ~~~~~~~~~~~~~~ .. container:: table-row Property generalStdWrap Data type stdWrap Description The full set of *stdWrap* functions applied to the whole plugin including mode switch, search box and calendar Default Wrap using a div container with the plugin class .. _linkBoxStdWrap: linkBoxStdWrap ~~~~~~~~~~~~~~ .. container:: table-row Property linkBoxStdWrap Data type stdWrap Description The full set of *stdWrap* functions applied to the tag cloud container without mode switch, search box and calendar Default Wrap using a div container with a class and a label .. _linkStdWrap: linkStdWrap ~~~~~~~~~~~ .. container:: table-row Property linkStdWrap Data type stdWrap Description The full set of *stdWrap* functions applied to a single link Default Wrap using a span container .. _modeSwitchStdWrap: modeSwitchStdWrap ~~~~~~~~~~~~~~~~~ .. container:: table-row Property modeSwitchStdWrap Data type stdWrap Description The full set of *stdWrap* functions applied to the mode switch if it has been enabled with the modeSwitchparameter before Default Wrap using a div container with a class and a label .. _searchBoxStdWrap: searchBoxStdWrap ~~~~~~~~~~~~~~~~ .. container:: table-row Property searchBoxStdWrap Data type stdWrap Description The full set of *stdWrap* functions applied to the search box if it has been enabled with the searchBoxparameter before Default Wrap using a div container with a class and a label .. _calendarStdWrap: calendarStdWrap ~~~~~~~~~~~~~~~ .. container:: table-row Property calendarStdWrap Data type stdWrap Description The full set of *stdWrap* functions applied to the calendar if it has been enabled with the calendarparameter before Default Wrap using a div container with a class and a label .. _calendarFrom: calendarFrom ~~~~~~~~~~~~ .. container:: table-row Property calendarFrom Data type string Description Label to be used for the starting date of the calendar Default From .. _calendarTo: calendarTo ~~~~~~~~~~ .. container:: table-row Property calendarTo Data type string Description Label to be used for the ending date of the calendar Default To .. _keepGetVars: keepGetVars ~~~~~~~~~~~ .. container:: table-row Property keepGetVars Data type Set of parameters Description These parameters will be kept additionally to those you might have chosen for config.linkVarsto make sure that stuff like categories or other parameters that might influence the results will still be available after clicking on a tag cloud link. It allows you to add two different variants of GET parameters: :: parametername = 1 will add the value of the parameter with the name *parametername* . :: parametername { keyname = 1 } will add the value of the key with the name *keyname* out of the parameter array with the name *parametername* . Default .. ###### END~OF~TABLE ###### .. _Example: Example ~~~~~~~ :: plugin { tx_tagpack_pi1 = USER tx_tagpack_pi1 { userFunc = tx_tagpack_pi1->main userFunc { tagcloudElements { enabledContent = text,image,textpic enabledRecords = tt_news } renderObj = COA_INT renderObj { 10 = USER 10 { userFunc = tx_tagpack_pi1->makeTagCloud tagPidList = 4 targetPid = 123 minFontSize = 8 maxFontSize = 20 maxNumberOfSizes = 20 modeSwitch = 1 searchBox = 1 calendar = 1 fontColor = #990000 generalStdWrap { wrap =
|
} linkBoxStdWrap { wrap =

Tag Cloud

|
} linkStdWrap { wrap = | } modeSwitchStdWrap { wrap =

Filter Mode

|
} searchBoxStdWrap { wrap =

Search Box

|
} calendarStdWrap { wrap =

Calendar

|
} calendarFrom = From calendarTo = To keepGetVars { tx_ttnews { category = 1 } } } } } } } This resembles most of the default settings of the tag cloud although we enabled the search box, the mode switch and the calendar and added some tt\_news parameters to enable recognition of news categories within the result lists. Actually these settings are triggered by different constants that can easily be modified using the TS Constant Editor. .. _Tutorial: Tutorial -------- A full point-a-to-b-to-c walk-through of an application of the extension. Include screendumps. Language: As tutorials are... Target group: Whatever fits. .. _Known-problems: Known problems -------------- Use this section for important warnings about bugs, problems or performance issues. This is where you should explain shortcomings of the extension, so people are properly warned. Be honest. Target group: Mostly Developers .. _To-Do-list: To-Do list ---------- - A wish list of things you want to add or fix. This includes smaller problems/bugs which are best described as a todo item. - Visions for what the extension could become with more development. .. _ChangeLog: ChangeLog --------- 0.9.2A new test regarding the manual. Should be better than the last one and contains more useful stuff now ;-) 0.9.1A test regarding the manual to make sure it will be rendered as expected 0.9.0Functionality slightly modified to improve usability.Doubleclicking is now possible where users expect it and ENTER will submit the form while merging.CSS slightly changed as well. 0.8.0Fixed ext\_tables.php to match the current versions of plugins and content elements againDowngraded the plugins to the current working versions (sorry for the inconvenience caused by mixed up files)Added the missing static folder again 0.7.1Tag manager module is close to stable now.Merging of tags is now possible while assigning their relations to the replacement tag.”Translate" will be a feature for the 1.x branch though.Bugfix: If one of the tags to be merged and the replacement tag are the same, the tag still was deleted 0.7.0Tag manager module is close to stable now.Merging of tags is now possible while assigning their relations to the replacement tag."Translate" will be a feature for the 1.x branch though. 0.6.2Fixed a small bug (removed JS debug alert from date fields) 0.6.1Fixed a small bug (ext\_tables.php including wrong typoscript statics) 0.6.0The new tag manager module is close to completion now - "Examine" and "Edit" are already available, "Merge" will be finished soon, "Translate" is planned for this summerThere's a new tagpack api class for backend and frontend functionality (thanx to Benjamin Mack)Backend functions have been adapted to work with the new api as far as possible, frontend plugins will follow 0.5.5added a check for an empty enabledRecords section in result list configuration to avoid a TCA bug shown in the frontend 0.5.4removed invalid character from static setup.txt of the tagcloud 0.5.3fixed a bug: TS-Setup for result lists using non existing constants 0.5.2fixed a bug TS-Setup for result lists of tagged records of pages and tt\_content using wrong constant names 0.5.1added example TS-Setup for result lists of tagged records of pages and tt\_contentchanged CSS-classes (they contain the official extension name as a prefix now) 0.5.0added basic settings for the installation with the extension manageradded several constants for the constant editoradded a regular expression for tagnames to get rid of special chars execept space or - (minus) 0.4.2fixed a bug with tags containing the Character - (minus) 0.4.1fixed a bug regarding listing of elements when in tagcrumb-mode 0.4.0added handler for version, inlineLocalizeSynchronize and hidden/unhidden elements with tagsfixed a bug regarding deleting and undeleting of tagged items 0.3.3added some iconsfixed a bug regarding selection of items with multiple tags 0.3.2removed one intval check that prevented new connection of tags if there were no existing tags available 0.3.1removed a debug outputsecured DB queries against possible attacks 0.3.0fixed some bugs with empty datamap entries for the tag fielddatabase operations other than editing don't destroy the relations anymore 0.2.0plugins for the tagcloud and a tagged items list are finalthe tagcloud can be pimped witha searchbox,a switch between filtermode and surfmode as well asa calendar for time frame settingsrecognition for additional URL parameters can be enabled as wellplugin for the nomination of tags still pending 0.1.0Backend works as expectedYou can create Tags and assign them to tables listed inTSconfig 'tx\_tagpack\_tags.taggedTables'no modules or plugins available yet .. _Important-guidelines: Important guidelines ==================== .. _HowTo-update-a-manual-to-the-new-layout: HowTo update a manual to the new layout --------------------------------------- With these steps you get it very fast: - Copy everything from your old manual except the title page and the table of contents - Delete contents from new manual but leave the title page and the table of contents there - Paste your content and check that formatting is correct and images are in place - Update the page properties with your extension key, e-mail-address, name, language, tagging.In the moment the language- and tagging- properties are not in use by the TER, but findable by search. - Reload the table of content (right click update index table) - Insert your extension key below the document title - Ready. Hint: When the header-styles are still in the old layout then **clear** and **re-assign** the new style. Get help from `http://documentation.openoffice.org `_ .. _Issues-with-Open-Office-documentation-for-TYPO3: Issues with Open Office documentation for TYPO3 ----------------------------------------------- There are a few important points to make about writing documentation for TYPO3 in Open Office. Please makes sure to follow these. .. _Inserting-images: Inserting images ^^^^^^^^^^^^^^^^ When you insert images you can either: Make a copy/paste from eg. Photoshop, but it's **REALLY IMPORTANT** that you insert the image into Open Office by the menu “Edit > Paste Special” and then select “Bitmap”. If you don't do it in this way the image cannot be shown (since it will not be stored as a PNG internally in the SXW file) |img-3| Alternatively you can use the traditional way “ **Insert > Graphics > From file** ” and insert an image from your harddrive. In particular use this if the image is photographic (JPG) since the internal storage as PNG is not good for photographs. Generally please use copy/paste only for screendumps with large areas of similar color (good png-compression) and JPG-files for photographic images. Go for small images, 72 dpi, medium quality. .. _Paragraph-styles: Paragraph styles ^^^^^^^^^^^^^^^^ - Use the paragraph style “Text body” for bodytext - Use “Heading 1” to “Heading 5” for headers. “Heading 1-3” will be recognized as “sections” on typo3.org. “Heading 4-5” is subheaders, where “Heading 5” is preferrably for “Examples”. - For code listings, use the style “Preformatted Text” (found under “HTML Styles”). For codelistings in tables there is a custom style called “Table Contents/PRE”. This screenshot shows the only paragraph styles allowed in the documents. The ones grayed out are paragraph styles that are used by default for such as the index table or the footer. The others are the ones you are allowed to use. |img-4| .. _Linking: Linking ^^^^^^^ You can make hyperlinks in the documents as absolute URLs. Use menu “Insert > Hyperlink” .. _Meta-data-and-updates: Meta data and updates ^^^^^^^^^^^^^^^^^^^^^ There are three fields of meta-data you have to fill in. First of all go to “File > Properties...”. In the “Description” screen you enter the title of the document. Extension manuals are prefixed “EXT: [extension title]” In the “User defined” screen you enter your email address as the first field (named “Email” / ”Info 1”) In the “User defined” screen you enter your full name as the second field (named “Author” / ”Info 2”) Finally you should also insert the correct extension key in the text below the document title, but this is not a meta-data field, just regular text. .. _Help-by-documentation-openoffice-org: Help by documentation.openoffice.org ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ See the international portal for help: http://documentation.openoffice.org 18 .. ######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: 129 .. :id: Graphic3 .. :name: Graphic3 .. :width: 224 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 363 .. :id: Graphic2 .. :name: Graphic2 .. :width: 241