DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: th_specialelements

Author:Kasper Skårhøj
Created:2002-11-01T00:32:00
Changed:2007-07-24T12:27:48
Author:Dev-Team Typoheads
Email:dev@typoheads.at
Info 3:
Info 4:

EXT: th_specialelements

Extension Key: th_specialelements

Copyright 2000-2007, Dev-Team Typoheads, <dev@typoheads.at>

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

Table of Contents

EXT: My Extension 1

Introduction 1

What does it do? 1

Screenshots 1

Users manual 1

FAQ 1

Adminstration 1

FAQ 2

Configuration 2

FAQ 2

Reference 2

Tutorial 2

Known problems 2

To-Do list 2

Changelog 2

Introduction

What does it do?

Extends the standard TYPO3 content elements with HTML based content elements.

See podcast “extensions: Special Content Elements” (13.11.2006) for a demonstration.

Features :

  • every element is based on an HTML-template
  • different templates for normal view and print-view can be specified
  • every element has its own directory in fileadmin/ and can therefore be exported and imported from one project to another
  • BE Module for administrating the elements
  • activate elements per column and page-tree
  • multilanguage support
  • switch from one element-layout to a different one without loosing data

Technical features :

  • uses existing fields of tt_content table
  • configuration is made with the TCA-Array (RTE etc....)
  • control caching on element level or directly per element-ID
  • full typoscript control for every element (ext_typoscript_setup.txt in directory)
  • overrule element-TS settings with TS from your main TS-Template
  • IRRE compatible

Screenshots

BE-module showing activated elements:

img-1

BE-module showing non activated elements:

img-2

Users manual

Specialelements can be downloaded and activated per page tree and per column. The extension is delivered without example elements!

Programmers can create their own specialelements, download them as .t3e file and reuse them in the next project.

Target group: Editors, Programmers

FAQ

Q: What's the differences between specialelements and flexform elements?

A: Specialelements are based on the tt_content database-table. Flexform elements data is saved in an XML construct.

Adminstration

After installing the extension you have to specify a path where the specialelements will be installed to. If you want to edit/modify the elements later on, it's recommended to use a directory in /fileadmin/.

Specialelements cannot be installed via the TYPO3 extension manager. They need to be installed with the specialelements BE-module.

FAQ

- Possible subsections: FAQ

Configuration

Extension settings (ext. Manager):

  • t3templates server:This is the server name for the SE online repository – leave this to the default setting.
  • reload cache files for template and:For BE-module only. 0 disables caching of SE online repository.
  • Path to Specialelements directory:Self explaining. Make sure the path exists!
  • advanced BE-viewEach SE can have a special (template based) BE-view. Activate this option for a customised BE-view in TemplaVoila or standard page module.
  • advanced edit icons in BEActivate this option and the standard edit icons for a content element will not be shown – they pop up if you move the mouse over the element header.
  • Development-mode (BE/FE)This enables/disables internal caching of element settings. Enable this option for development – disable it for live websites. Might cost some performance if enabled.

BE-module: Activate the installed specialelements with the specialelements BE-module. Each specialelement can be activated per page-tree and per column (non-TV).

Caching: Specialelements have their own caching mechanism. The cache is not cleared with the standard “clear FE-cache” button. To clear the cache of one element, you have to press the “clear cache” button of the element in the dropdown “activate elements”.Caching can be disabled or defined in minutes for each specialelement.

TypoScript

In case specialelements do not get rendered in the FE, insert the following snippet in your extension-template:

####################################
#  for PRINT-VERSION
####################################
alt_print.includeLibs.th_specialelements = EXT:th_specialelements/pi1/specialelements_functions.php

###################################
# normal specialelements-rendering
###################################
page.includeLibs.th_specialelements = EXT:th_specialelements/pi1/specialelements_functions.php

tt_content.specialelements = TEXT
tt_content.specialelements {
    postUserFuncInt = user_specialelementFunctions->specialelements
    postUserFuncInt.noCacheElementIDs={$specialelements.noCacheElementIDs}
    postUserFuncInt.noCacheElementNames={$specialelements.noCacheElementNames}
}

Constants:

specialelements.noCacheElementNames

Property

specialelements.noCacheElementNames

Description

Optional

Disables the specialelement caching mechanism for the given specialemenents (enter multiple elements seperated by “,”)

Cache duration can be configured in minutes.

Syntax:

[element name]:[duration in minutes(integer)],....

Example:

specialelements.noCacheElementNames = news_uebersicht:2,flash_photo_gallery
specialelements.noCacheElementIDs

Property

specialelements.noCacheElementIDs

Description

Optional

Disables the specialelement caching mechanism for the given element- IDs.

Syntax:

[element-ID],[element-ID],....

Example:

specialelements.noCacheElementIDs = 34,44,234

Setup:

tt_content.specialelements.postUserFunc

Property

tt_content.specialelements.postUserFunc

Description

Optional

Override the TypoScript defined in the special element.

Example:

tt_content.specialelements.postUserFunc.th_left_pic_text_header_subheader.template = mytemplate.html

Developer Guide

How to create a special element (basics)

The most basic special element consists of a HTML template which can be filled dynamically with the use of markers.

The markers are named like the database fields of the tt_content table. For more flexibility you can use TypoScript to manipulate the values of the markers eg. Rendering the “title”-field as picture, calling user functions,....

How to create a special element (detailed)

Filestructure:

A special element consists of the following directory/file structure:

  • a main direcotry – this is also the unique specialelement key (like extension-key)
  • the following files within the main direcotry:
    • ext_tables.php: you can change the TCA array of tt_content for the element. eg. Headline for “title” field should be named “enter title here” instead of “title”
    • ext_tables.sql: if your element extends the tt_content database, enter the SQL statement here
    • ext_typoscript_setup.txt: rendering definition (TS) for markers used in HTML-template
    • icon.gif: specialelement icon shown in the “create new content element” wizard and in the BE-module
    • locallang.php: translation of texts used in the specialelement
    • template_normal.html, template_print.html, template_[whatever].html: HTML-templates used for rendering
    • locallang_csh.php (optional): to override default help-messages

If one of the files is missing, it's highlighted in the BE as shown here:

img-3 Example files:
ext_tables.php

Instead of using a hardcoded path to the specialelement you should use the placeholder “ {elementPath} ” because the path can be different from installation to installation. Attention:{elementPath} includes already a / at the end.

If you are tired typing the element name, you can use the placeholder “ {elementName} ”.

<?php
# overrides the standard bodytext label for this specialelement
$temp_tca['columns']['bodytext']['label'] = 'LLL:{elementPath}{elementName}/locallang.php:bodytext';

# sometimes TCA settings won't be overridden correctly because of array-merge.
# In this case type the fields seperated with “,” here
$clearColumns = 'header_layout,bodytext';
?>

Using IRRE functionality within a SpecialElement?

You need to define a DB-field for storing the relation to the IRRE elements.

example:

$temp_tca['columns'] = array(
                "th_specialelements_programs" => Array (
                        "exclude" => 1,
                        "label" => "LLL:EXT:irre_hotel/locallang_db.xml:tx_irrehotel_hotel.programs",
                        "config" => Array (
                                "type" => "inline",
                                "foreign_table" => "tx_irrehotel_program",
                                "foreign_field" => "parentid",
                                "foreign_table_field" => "parenttable",
                                "maxitems" => 10,
                        )
                ),
        );

In order to make sure, that the IRRE elements are also copied when the SE is copied, you have to define the DB-field in the global TCA array as well:

$TCA['tt_content']['columns']['th_specialelements_programs'] = Array (
                        "exclude" => 1,
                        "label" => "LLL:EXT:irre_hotel/locallang_db.xml:tx_irrehotel_hotel.programs",
                        "config" => Array (
                                "type" => "inline",
                                "foreign_table" => "tx_irrehotel_program",
                                "foreign_field" => "parentid",
                                "foreign_table_field" => "parenttable",
                                "maxitems" => 10,
                        )
                );
ext_tables.sql
#
# Table structure for table 'tt_content'
#
CREATE TABLE tt_content (
        title2 varchar(45) DEFAULT '' NOT NULL
);
ext_typoscript_setup.txt

Instead of using a hardcoded path to the specialelement you should use the placeholder “ {elementPath} ” because the path can be different from installation to installation. Attention:{elementPath} includes already a / at the end.

If you are tired typing the element name, you can use the placeholder “ {elementName} ”.

##################
# TypoScript definitions
##################
lib.image = IMAGE
lib.image {
  file.maxW < temp.width
  imageLinkWrap = 0
  stdWrap.spaceAfter=5
  wrap = |<br>
  altText.field=altText
}

includeLibs.rss_display = {elementPath}{elementName}/userfunc_rss_display.php

# fetch the RSS-feed
lib.rss = USER
lib.rss {
    userFunc = user_rss_display->user_rss_fetch
}


##################
# which HTML-template should be used in page type 0
##################
template = template_normal.html

##################
# which HTML-template should be used in page type 98
##################
[globalVar = TSFE:type=98]
template = template_print.html
[global]

##################
# TS rendering of elements (= fieldnames in tt_content)
# syntax:
#    elements.[fieldname of tt_content] = [TS]
##################
elements.bodytext =< lib.parseFunc_RTE
elements.image < lib.image

##################
# TS rendering of self-defined markers
# syntax:
#    markers.[youown markername] = [TS]
markers.rss < lib.rss
##################
# element/markers for print template
##################
98 {
    elements < elements
}

Special TypoScript:

includeCSS.[name] = path

possible to add more than one stylesheet

icon.gif:

Guidelines for icons:

  • green: normal text
  • orange: photo
  • green border: headline
  • blue: links
  • lila: flash
  • yellow: HTML/phpscript output
  • loops are symbolised with a + (eg. Several images below each other)

Examples:

img-4 img-5 img-6 img-7 img-8 img-9 img-10 img-11 img-12

locallang.php

(specialelement title is defined here in “be_title”)

<?php
$LOCAL_LANG = Array (
        "default" => Array (
                # be-title of this specialelement
                'be_title' => 'RSS display',
                # be-description of this specialelement
                'be_description' => 'displays RSS newsfeeds on your webpage',

                # overruled TCA label for “header” field
                'header' => 'default URL (.xml, .rdf)',
        ),
        "de" => Array (
                'be_title' => 'RSS Anzeige',
                'be_description' => 'zeigt RSS in Listendarstellung an',
                'header' => 'default URL (.xml, .rdf)',
        ),
);
?>
template_normal.html

use ###db_[db fieldname of tt_content table]### for raw output of the value as it's stored in the DB

use ###[db fieldname of tt_content table]### for TS rendered value (must be defined in TS as element.[db fieldname] = [TS]

<table border="0" width="100%">
<tr>
<td align="left">
<b>###db_header###</b><br>
<i>###db_subheader###</i><br>
###bodytext###<br>
</td>
</tr>
</table>

Loops (image, media):

In fields like “images”, “media” multiple files are stored seperated by “,”. To loop through these files in your HTML-template you have to use the following syntax:

HTML-template example for image-loop :

<table border="0" cellspacing="0" width="20" cellpadding="0">
<!-- ###image### begin -->
<!-- ###LOOP_image### begin-->
<tr>
 <!-- ###image0### begin--><td style="padding:5px 12px 5px 0px;">###image_0### ###altText###</td><!-- ###image0### end-->
 <!-- ###image1### begin--><td style="padding:5px 12px 5px 0px;">###image_1### ###altText###</td><!-- ###image1### begin-->
</tr>
<!-- ###LOOP_image### end-->
<!-- ###image### end -->
</table>

TS-snippet for image-loop :

lib.small_image = IMAGE
lib.small_image {
  file.maxW = 215
  imageLinkWrap = 1
  imageLinkWrap {
    enable=1
    JSwindow = 1
    width=800m
    height=600
    bodyTag = <BODY bgColor=white>
    wrap = <A href="javascript:close();"> | </A>
    JSwindow.expand = 17,20
  }
  stdWrap.spaceAfter=0
  altText.field=imagecaption
  # special TS for use in specialelements:
  altText.marker.wrap = <br>|
}
elements.image < lib.small_image
locallang_csh.php

Overwrites the default help-texts in the help-popup for the specific field.

$LOCAL_LANG = Array (
    'default' => Array (
                # “header” field
                'header.description' => '11111111111111111111111.',
                'header.details' => '22222222222222222222.',
                'header.image' => '',
                'header.seeAlso' => '',
                # “pages” field
                'pages.description' => '3333333333333333333333.',
                'pages.details' => '444444444444444444444444',
                'pages.image' => '',
                'pages.seeAlso' => '',
    ),
);
BE-View for Elements

How to adjust the backend view of a special element

create a folder "be" in the folder of the special element

create at least the files "ext_typoscript_setup.txt" and a template file in this folder.

it is possible to call user functions!

for backend view, the typoscript setup gets parsed and the view gets generated.

known Problems :

  • It is not possible to use stylesheet files in BE. Please write your CSS-styles for BE-view inline into the template file
  • image processing in BE does not work

Tipp:

If you are using user-functions, you can call the same function in FE and BE rendering – in case you need some conditions depending on FE/BE rendering, you simply can pass a variable to the user-function so that you know if it's called from FE or BE.

Example:

-- be/ext_typoscript_setup.txt --

# include the userfunction class
includeLibs.somthing = {elementPath}{elementName}/userfunc.php

#userFunc
content = USER
content {

    # call user function
    userFunc = user->doSomething

    # additional parameter because this user function is used to generate both frontend and backend view
    be-mode = 1
}

#set templates
template = template_normal.html

markers.content < content

Tutorial

install the .t3x file via the normal extension manager

in the extension settings (in the ext. manager) you can define a path where the special elements get installed. you can leave it to the default setting or use a path which is accessible via the fileadmin: "fileadmin/specialelements/"

reload the BE interface and you will find the "specialelements" backend module

install one of the elements via the “install elements” mode found in the special element BE module or if you have a “.t3e” file you can upload it with the “browse” button.ATTENTION: the .t3e files can NOT be installed with the extension manager!!

select "install elements" in the SE BE-module

browse your local drive and select one of the .t3e files and click on "upload extension file"

after successfull installation, you have to activate the element

click on a page where you want to use the special element (this setting will be inherited to all subpages)

select "activate elements" in the SE BE-module

you'll find two lists:- a list of activated elements on the selected page (will be empty of course the first time)- a list of non-activated elements (which can be activated now)

check the "default" checkbox of the special element you want to activate

Now you should find the element in the "create new element" wizard when inserting a new content element on the page.

If the special element does not get rendered in the FE, please insert the following line in your root-TypoScript template:

page.includeLibs.th_specialelements = EXT:th_specialelements/pi1/specialelements_functions.php

ATTENTION:

this only works if your "page" element in TS is called "page" like this:

page = PAGE
page.typeNum = 0
page.bodyTag = <body>
page.stylesheet = {$stylesheet}
page.20 = TEMPLATE
page.20 {
...

Known problems

  • NO USER_INT objects in TypoScript supported!!!!
  • Classes in userFuncs must not have the same name as the called functionProblem: The userfunction will be called twice, once with parameters such as $conf-Array and once without.Why? Since this example class lacks an init-function, on makeinstance the function having the same name as the class gets calledSolution:- Use different names for class and function(s)- Define an empty init() in the class.

The following classes are extended by this extension:

  • class.ux_t3lib_tceforms.phphelpTextIcon()getMainFields()
  • class.ux_t3lib_tcemain.phpstart()
  • class.ux_t3lib_transferdata.phpfetchRecord()
  • ux_view_help.phpinit()
  • class.ux_t3lib_tceforms_inline.phpparseStructureString()
  • class.tx_tv_rendering.php (only used if “advanced BE view” is enabled with TemplaVoila)renderPreviewContent_preProcess()
  • class.ux_tx_cms_layout.php (only used if “advanced BE view” is enabled)tt_content_drawHeader()

extension extends the same classes/functions.

To-Do list

  • Nested content elements.
  • Current solution to set the user internally to “admin” if an specialelement gets edited so that every field is shown no matter if the current logged in user has the rights for the field – maybe not a good solution.
  • Better rights management so that you can set rights for specialelements on user or group level.

Changelog

- 1.0: not compatible to previous versions – everything new

img-13 EXT: th_specialelements - 10