changes in tt_news 3.0.0

changes in tt_news 3.0.0 Extension Key: tt_news Copyright 2009, Rupert Germann, <rupi@gmx.li> 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 changes in tt_news 3.0.0...1 Introduction...1 Highlights...1 Compatibility...1 Update howto...2 Changes...5 Flexform...5 News admin module...7 Constant editor...8 TypoScript Object Browser (TSOB)...8 Changed TypoScript defaults...9 HTML template changes...9 New TypoScript properties...10 TSConfig...11 mod.web_txttnewsm1...11 -> CATMENU...12 -> LIST...12 tx_ttnews...13 OptionSplit...13 Introduction This document contains a quick-update howto which you should read at least once before you're updating your working tt_news 2.5.x installation on your production site with tt_news 3.0.0. Seriously: There are some changes in tt_news that might result in no output or worser things. It is strongly recommanded that you first test the new version on a copy of your site and that you have a backup at hand in case everything goes wrong. The other parts of this document describe the most important new features in detail. Highlights New backend module to manage news records and categories: news admin FE plugin changes: OptionSplit for many parameters (even in flexform) New Display modes (CODEs) and template parts Build-in processing of generic markers (thanks to Ringer Gerorg ;-) ) Easy update: new updater script which fixes the most common migration problems Serious speed improvements: internal caching of processing intensive values Improved usability: reorganized constant editor options, plugin flexform and news record form. Compatibility tt_news 3.0 has work with all currently supported TYPO3 versions: 4.1, 4.2, 4.3 (the news-admin module is not visible in TYPO3 4.1 because it requires core functions that are only available in TYPO3 4.2 or higher). The minimum reqired PHP version is the same as the PHP version required by the TYPO3 version. tt_news 3.0 has been tested with PHP 5.2.x and PHP 5.3.0. changes in tt_news 3.0.0-1

Update howto Did you really make a backup of your site? If yes, then go ahead and update tt_news with the extension manager. The first screen you'll see will look like this: Note the unobtrusive Updater Box in the upper right corner. This box offers a direct link to the new updater script. But first update all required database tables. Then open the updater. Only opening the updater does not change anything in your installation, the script only reads data from the database and from the filesystem to check for setting that should be changed. The updater screen starts with a warning message that you should read at first: changes in tt_news 3.0.0-2

The boxes below the warning message inform you about what checks have been done and what the results are. The following checks are executed: Search for outdated static TS templates Search for non existing HTML templates Search "Startingpoint" ("pages") in FF (flexform settings) Search "recursive" in FF Search "no page Browser" in FF Search "listlimit" in FF If you see only green checkmarks and Nothing to do messages you can stop here and quit the updater (this happens f.e. on a fresh install). In case the updater has found something that needs to be fixed you'll see yellow exclamation marks and DO IT buttons. Let's have a closer look on the Search for outdated static TS templates function. This function searches the database for template records (table: sys_template) with outdated references to the static TS templates from tt_news. The references to static extension templates in field Include static (from extensions) are stored with the path and since I moved the folder for the static templates to pi/static/ the old paths will not fit anymore. To fix those references you could edit all your TS templates, but since there could be quite a lot of these template records (depending on your sites configuration) I thought it'd be a good idea to let a script do this work. If you also think like this, click on the DO IT button. The next screen tells you what the updater did: changes in tt_news 3.0.0-3

Attention: this information is only shown once. If you need it for later purpose copy it now. Clicking the back link will bring you back to the main screen of the updater which should now show a changed Search for outdated static TS templates box: The next function ( Search for non existing HTML templates ) works a bit different from the others because it does not replace a value by a new value it clears the references to HTML-templates which do not exist in the filesystem from Flexforms in tt_news plugin elements (recommanded way is to set the html template in TS). The main reason for writing this function was to get rid of the old tt_news_v2_template.html which was inserted as default in tt_news 2.5.2. This template still existst in tt_news but I moved it to the res/ folder. If the updater finds content-elements with configured HTML templates that actually exist in the filesystem it will not touch this records. If you click on DO IT you'll see which records the updater changed and which templates were missing. changes in tt_news 3.0.0-4

Go through the remaining updater functions until the main screen shows only green checkmarks. Now leave the extension manager and check your websites frontend output. If all works as before great I'm registered at paypal with the email address: rg(at)rupert-germann.de ;-) In case you see only error messages like this one below instead of news there's probably some more work to do. (New feature: tt_news can now display nicely formatted error messages even when there is no static template included!) These messages should give you some hints why there is no output. Since there are almost unlimited combinations of different configuration options especially if you extended tt_news by other extensions it can happen that the configuration validation in tt_news displays false errors. In this case you can disable all config checks in TypoScript: plugin.tt_news { enableconfigvalidation = 0 Changes Flexform Content element, type: plugin tt_news The flexform for the plugin settings changed its look a bit in tt_news 3.0.0: changes in tt_news 3.0.0-5

what to display (code) This field is now a normal drop-down selector which allows only to select one code at once. I don't think that many people did use the possibility to select more than one code here for a simple reason: doing so will group multiple plugins in one configuration container (content elment) disabling the possibility to use different options for each plugin but in most cases you'd need exactly the opposite: f.i. controlling the options of each single item in a list. This is now possible with OptionSplit (see chapter: OptionSplit in this document). Additionally to the known codes like LIST, LATEST, AMENU, SINGLE, CATMENU, SEARCH... there are some new what to display options: LIST2: Advanced list view with 6 alternating template parts LIST3: Standard list view with 3 alternating template parts SINGLE2: Advanced detail view with 3 image markers HEADER_LIST: Reduced list view showing only headers and dates, no images Besides this I moved the following fields to a different sheet (flexform tab) "Startingpoint" ("pages") and "recursive" have been moved to Other Settings (reason: these settings are only needed for the rare case when a plugin content-element needs other values for pid_list and recursive than the values set by TS. Setting these values in each and every news plugin as I saw it in a lot of sites is not recommanded) "no page Browser" and "listlimit" have been moved to the sheet Template The updater script in extension manager takes care of these changed values. Template tab Some fields in the tab Template do now accept also OptionSplit values instead of single values. changes in tt_news 3.0.0-6

Note the values with c after the number: The crop feature of the typoscript IMAGE object is now supported, too. You can find out more about the new possiblities with optionsplit in tt_news 3.0.0 in the chapter OptionSplit in this document. Typoscript for a content element The tab Other Settings offers a new field Typoscript for this content element (plugin.tt_news.[your TS]). Since access to TypoScript for non-admin users is a security risk, this field is only visible for admin users. The Typoscript in this field is merged with the existing TypoScript setup for plugin.tt_news. If you f.i. want to add a wrap to the output of a single plugin simply write this to the TypoScript field: stdwrap.wrap = <div class myclass > </div>. News admin module tt_news 3.0.0 comes with a new backend module offering some features that are missing in the normal list module. Main reason for writing this module was the fact that tt_news allows you to control the editing permissing not only based on pages like the default permission system in TYPO3 since tt_news 2.x it is possible to control editing permissions by assigned categories. These extended permissions are not visible in the list module so an editor had to open a news record to know if he was allowed to edit it or not. Key features of the news admin module: Category tree and news records are shown in the same view The list of news can be filtered by category, by page where the news are stored in and by a text search. The edit icon beneath each news record shows if the record is editable for the current user or not Non editable icons can be filtered out The Category tree offers almost all features of the pagetree like: expand/collapse, context menu and drag & drop of single categories or complete branches of the tree. New news or categories can be created with one click (even with pre-selected category) The module offers many TSConfig options to adapt it to your personal taste (see section. TSConfig in this document) changes in tt_news 3.0.0-7

Constant editor The constant editor offers much more options than in older tt_news versions. The settings are categorized to make it easier to find a certain option (additionally all texts and labels can be localized). TypoScript Object Browser (TSOB) By default the TSOB shows much more options than in earlier tt_news versions. The Typoscript file pi/static/ts_new/setup.txt now contains all possible options that can be used to configure tt_news. All options are commented so you should see a short explanation next to each var when you look to the TypoScript setup of plugin.tt_news in the TSOB (click the ckeckbox Display comments below the option list if you don't see any comments): changes in tt_news 3.0.0-8

Changed TypoScript defaults Property: Data type: Old value: New value: Description: dontusebackpid boolean 0 1 The parameters that are needed to generate a link that points back to page from where the detailview was opened will NOT be added to the singleview link. I strongly recommand to leave this at 1 because those extra parameters caused TYPO3 to cache an enormous amount of versions of the same page, many uneeded realurls are created, indexed search will find multiple version of the same article, google will detect double content... Use either a static backpid (see: plugin.tt_news.backpid) or add a javascript (history.back()) link to your HTML template. usepibasepagebrowser boolean 0 1 By default the pagebrowser will use <div> to format its output and not <table> code string/stdwrap code.field = select_key code = Only effect of this change should be that the former required code > to unset the stdwrap before overwriting it with a string is not needed anymore. general_stdwrap stdwrap parsefunc < tt_content.text.20.parse Func displaylist.subheader_ stdwrap stdwrap empty lib.parsefunc_rte is still applied to fileds like subheader and content (bodytext) but it is done seperately for each field giving you more flexibility to control the tt_news output. The attribute class= bodytext will be stripped by default. Changed the default stdwrap to append the more link directly to the subheader and display it only if the field bodytext contains something. -> see example below HTML template changes tt_news 3.0.0 comes with a new default HTML template (ext/tt_news/res/tt_news_v3_template.html) containing some new tenplate parts and also some new markers. changes in tt_news 3.0.0-9

New template parts ###TEMPLATE_CAT_RELATED### Template which is used to display related news by category in singleview. This template shows only titles and dates of news records and looks very similar to the output of related news. ###TEMPLATE_SINGLE2### Advanced detail view with 3 image markers. ###TEMPLATE_LIST2### Advanced list view with 6 alternating template parts. ###TEMPLATE_LIST3### Standard list view with 3 alternating template parts Removed the ###MORE### marker from all LIST templates It was often requested to have a conditional more-link in list views and also to have this link inside the wrap of the subheader. This was already possible by adding the TS snippet below but now this is enabled by default. The current default TS setup for the subheader looks like this: plugin.tt_news { displaylist.subheader_stdwrap { striphtml = 1 crop = 230... 1 ifempty.field = bodytext # the "more" link is directly appended to the subheader append = TEXT append.data = register:newsmorelink append.wrap = <span class="news-list-morelink"> </span> # display the "more" link only if the field bodytext is not empty append.if.istrue.field = bodytext # wrap subheader AND "more" link in <p> outerwrap = <p> </p> If there are 2 more-links in your output after updating either remove the marker from your html template or comment out the append... part of the subheader_stdwrap. New markers ###NEXT_ARTICLE### ###PREV_ARTICLE### Generic markers see manual of extension ttnewsgenericmarkers : http://typo3.org/documentation/document-library/extensionmanuals/ttnewsgenericmarkers/current/ New TypoScript properties Property: Data type: Description: Default: plugin.tt_news.stdwrap stdwrap stdwrap for the complete output of the tt_news plugin. Example: page { 25 =< plugin.tt_news 25.code = latest 25.stdWrap.wrap = <div class="latest"> </div> changes in tt_news 3.0.0-10

Property: Data type: Description: Default: enableconfigvalidation boolean # validate some configuration values and display a message if errors have been found enableconfigvalidation = 1 deflanglabel string # label for the default language (language uid = 0) deflanglabel = English 1 deflangimage string # flag for the default language (language uid = 0) deflangimage = uk.gif archiveactivemarkerco ntent string content which is filled to the marker ###ARCHIVE_ACTIVE### for the selected archive period archiveactivemarkercontent = class="amenu-act" archiveyear_stdwrap string/stdwrap stdwrap for the year in the archive menu archiveyear_stdwrap.wrap = <li class="news-amenuitem-year"> </li> showyearheadersina menu boolean divide the archive menu to yearly periods showyearheadersinamenu = 1 1 ignorenewswithoutdat etimeinamenu boolean news with zero datetime will cause the amenu to search all periods starting from 1970. Disabling this is not recommanded. ignorenewswithoutdatetimeinamenu = 1 amenustart string start date for the archive menu (php function strtotime() syntax. e.g.: 1.1.2002, -3 months, -10 years, now -3 years amenuend string end date for the archive menu (php function strtotime() syntax. e.g.: 1.1.2002, -3 months, -10 years, now now displaycatmenu.mode string catmenu rendermode: NEW option: ajaxtree = expandable menu with ajax (requires TYPO3 >= 4.1) displaycatmenu.catpid List displaycatmenu.recursi ve string/stdwrap string/stdwrap list of page IDs where the categories for the menu are stored (overrides GRSP if given) extend "catpidlist" by the number of recursive levels nextprevrecsortingfiel d string Field for selecting the next and previous article in the singleview plugin.tt_news.displaysingle { nextprevrecsortingfield = datetime datetime converttouserintobjec t boolean If this is enabled a tt_news plugin can be converted to an USER_INT object on the fly. [tsref: plugin.tt_news] TSConfig mod.web_txttnewsm1 Default Page-TSConfig options for the news admin BackEnd module: mod.web_txttnewsm1 { catmenu { expandfirst = 1 show { cb_showediticons = 1 cb_expandall = 1 cb_showhiddencategories = 1 list { limit = 15 pidfornewarticles = changes in tt_news 3.0.0-11

flist = pid,uid,title,datetime,archivedate,tstamp,category;author icon = 1 nolistwithoutcatselection = 1 show { cb_showonlyeditable = 1 cb_showthumbs = 1 imagesize = 50 defaultlanguagelabel = Property: Data type: Description: Default: catmenu -> CATMENU Configuration for the category tree section of the tt_news BE-module list -> LIST Configuration for the list section of the tt_news BE-module defaultlanguagelabel string Label for the default language (uid=0) shown in the language selector. [page: mod.web_txttnewsm1; beuser: mod.web_txttnewsm1] -> CATMENU Property: Data type: Description: Default: expandfirst boolean Enable this to keep the first level of the category tree expanded. 1 show array Configures which checkboxes should be shown on top of the category tree. By default all checkboxes are enabled: mod.web_txttnewsm1 { catmenu { show { cb_showediticons = 1 cb_expandall = 1 cb_showhiddencategories = 1 [page: mod.web_txttnewsm1.catmenu; beuser: mod.web_txttnewsm1.catmenu] -> LIST Property: Data type: Description: Default: limit boolean Enable this to keep the first level of the category tree expanded. 1 pidfornewarticles int+ Page where the create new article button points to. If pidfornewarticles is not set (default), the current page is taken. The create new article is only visible when the logged in user is allowed to modify the contents of the pidfornewarticles page. flist List of fieldnames List of fields to show in the listview. Can be seperated by comma or semicolon. Example (default): mod.web_txttnewsm1.list { flist ( pid,uid,title,datetime, archivedate,tstamp, category;author regard the different token which is used for category;author. This configures the list to show this fields in one column. Showing 2 or more fields in one column removes sort by this field link for this column. icon boolean Configures if the table icon (with context menu) should be shown in the list. nolistwithoutcatselect ion boolean If this is set, the list shows only a result if a category has been selected from the tree. 1 changes in tt_news 3.0.0-12

Property: Data type: Description: Default: show array Configures which checkboxes should be shown on top of the news list. By default all checkboxes are enabled: mod.web_txttnewsm1 { list { show { cb_showonlyeditable = 1 cb_showthumbs = 1 Exception: The checkbox cb_showonlyeditable is never visible for admin users, because an admin can edit everything. imagesize int+ Configures the size (in pixel) for the image thumbnails. The value is taken for width and height, the aspect ratio of the image will be preserved. [page: mod.web_txttnewsm1.list; beuser: mod.web_txttnewsm1.list] 50 tx_ttnews Property: Data type: Description: Default: singlepid int+ Target page for the save&preview button in editing forms and for the linked record titles in the list view in the tt_news BE module. The target page must contain a tt_news plugin with code SINGLE. Example (PageTSConfig): tx_ttnews.singlepid = 133 [page: tx_ttnews; beuser: page.tx_ttnews] Example (UserTSConfig): page.tx_ttnews.singlepid = 133 OptionSplit OPTIONSPLIT FOR TT_NEWS Yeah :-) I wrote this capitalized to emphasize that this is probably the most important new feature in tt_news since nested categories - and IMHO optionsplit is one of the best inventions ever since sliced bread anyway. (Thanks to Jonas Dübi and cabag.ch for the initial patch using optionsplit for alternating template parts. This inspired me to extend this principle to many more options) Despite it is mentioned right at the beginning of TSRef Optionsplit is not so famous and widely used as it would deserve it. Optionsplit is part of TYPO3 since "ever" but it is used only a few times until now (mainly for the xmenu objects and inside of split objects). You might ask yourself: For what do I need this? Did you ever needed to configure a certain option only for one or a few of the news showing in a list? Until now you'd need one plugin for each different option. Take a look at this page: changes in tt_news 3.0.0-13

The main column shows a news list which is build of several plugin content elements. Since it was not possible until now to use more than one value for e.g. the image size in one plugin you can easily distinguish the plugins by their image sizes. Means: you would need alt least 3 plugins to create a list like this. By using optionsplit it is possible to substitute the 3 plugins by one and this one plugin has far more configuration possibilities than the 3 together had before. Another big advantage of using only one tt_news instance instead of 3 or more is of course that this one plugin will be rendered much faster. Now let's have a look at some details. Consider this: plugin.tt_news { displaylist.image.file.maxw = 300 300 * 200 * 100 80 65 You see that the values are divided by 2 different tokens: * and * divides the parameters to sections: first * middle * last divides a section to subparts. The behaviour of the subparts differs depending on the section: in first and last the values are used in the order as they are listed, in middle the values are cycled. How often the middle section is cycling depends on the amount of items which are shown ( = plugin.tt_news.limit). Assumed the list limit is set to 10 records the displayed news will have the following image sizes: 1. record: 300px (first) 2. record: 300px (first) 3. record: 200px (middle) 4. record: 200px (middle) 5. record: 200px (middle) 6. record: 200px (middle) 7. record: 200px (middle) 8. record: 100px (last) 9. record: 80px (last) 10. record: 65px (last) But not only image sizes are optionsplitted - it's possible to use optionsplit on all parameters in lists! Even wraps can be splitted: changes in tt_news 3.0.0-14

plugin.tt_news { displaylastest.title_stdwrap.wrap ( <h1> </h1> * <h2 class= even > </h2> <h2 class= odd > </h2> * <h3> </h3> <h3> </h3> <h3> </h3> ) That will do the following: the title of the first item will we wrapped in <h1>. The titles of the following records will get 2 alternating <h2> wraps and the last 3 items will get h3 headers. So far so good - but besides articles in lists there are other things in news where the same configuration data is used for multiple items: Template parts and images in the single view. OptionSplit for template parts OptionSplit for template parts (altlayoutsoptionsplit) allows you to directly access certain template parts in a template. Contrary to the good old alternatinglayouts feature the current template part is not determined by a simple counter but by an optionsplitted value. Consider this: plugin.tt_news { altlayoutsoptionsplit = 0 1 * 2 3 4 * 5 5 5 Assumed the list limit is set to 11 the template parts will be choosen in the following order: 1. record: tmpl part 0 (###NEWS###) 2. record: tmpl part 1 (###NEWS_1###) 3. record: tmpl part 2 (###NEWS_2###) 4. record: tmpl part 3 (###NEWS_3###) 5. record: tmpl part 4 (###NEWS_4###) 6. record: tmpl part 2 (###NEWS_2###) 7. record: tmpl part 3 (###NEWS_3###) 8. record: tmpl part 4 (###NEWS_4###) 9. record: tmpl part 5 (###NEWS_5###) 10. record: tmpl part 5 (###NEWS_5###) 11. record: tmpl part 5 (###NEWS_5###) btw: it's also possible not to use all optionsplit sections - something like this: altlayoutsoptionsplit = 3 5 2 1 4 1 5 5 will simply output the template parts in the listed order (if limit is greater than the amount of split items to last value will be repeated). OptionSplit for images in single view With the new parameter "imagemarkeroptionsplit" it's possible to use multiple imagemarkers for images in the single view. Example: plugin.tt_news.imagemarkeroptionsplit = 1 * 2 will render the first image to marker ###NEWS_IMAGE_1### and all others to marker ###NEWS_IMAGE_2### The other image-related parameters are optionssplitted, too. Consider this: page.10.30 =< plugin.tt_news page.10.30 { code = single2 displaysingle { # configures tt_news to use 3 image markers. The first # image is rendered to marker 1, the last 2 images # are renderd to marker 3, the rest will go to marker 2. imagemarkeroptionsplit = 1 * 2 * 3 3 changes in tt_news 3.0.0-15

image.file.maxw = 300 * 90 * 200 200 image.file.maxh = 300 # this configures tt_news to wrap only each "middle" (marker2) image # with <div class="sv-img-small"> (div is closed later) image.wrap = * <div class="sv-img-small"> * # This wraps all images in the first image marker to # <div class="sv-img-big"> </div>. # marker 2 and 3 will be wrapped to # <div class="sv-img-small-wrapper"> </div> imagewrapifany ( <div class="sv-img-big"> </div> * <div class="sv-img-small-wrapper"> </div> ) caption_stdwrap.required = 0 # This wraps the image caption in a <p> tag. have a look at # the "middle" wrap which closes the div from above to surround # the image and its caption caption_stdwrap.datawrap ( <p class="news-single-imgcaption"> </p> * <p class="news-single-imgcaption"> </p></div> * <p class="news-single-imgcaption"> </p> <p class="news-single-imgcaption"> </p> ) weird, isn't it? ;-) changes in tt_news 3.0.0-16