changes in tt_news 3.0.0

changes in tt_news 3.0.0

Copyright 2009, Rupert Germann, <[email protected]>

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

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).

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 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.

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.

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

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

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)

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):

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

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.

displayList.subheader_ stdWrap

stdWrap 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.

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/extension-manuals/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>

Property: Data type: Description: Default: enableConfigValidation boolean # validate some configuration values and display a message if errors have

been found

enableConfigValidation = 1

1

defLangLabel string # label for the default language (language uid = 0) defLangLabel = English

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-amenu-item-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

string/stdWrap list of page IDs where the categories for the menu are stored (overrides GRSP if given)

displayCatMenu.recursi

ve string/stdWrap 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 {

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.

1 noListWithoutCatSelect

ion

boolean If this is set, the list shows only a result if a category has been selected from the tree.

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. 50 [page: mod.web_txttnewsM1.list; beuser: mod.web_txttnewsM1.list]

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

Example (UserTSConfig):

page.tx_ttnews.singlePid = 133

[page: tx_ttnews; beuser: page.tx_ttnews]

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.

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)

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.

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">|&nbsp;</p></div>|*| <p class="news-single-imgcaption">|&nbsp;</p>|| <p class="news-single-imgcaption">|&nbsp;</p> ) } }