.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ======================== 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: EXT: th\_specialelements ======================== Extension Key: **th\_specialelements** Copyright 2000-2007, Dev-Team Typoheads, 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: 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: Introduction ------------ .. _What-does-it-do: 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: Screenshots ^^^^^^^^^^^ BE-module showing activated elements: |img-1| BE-module showing non activated elements: |img-2| .. _Users-manual: 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: 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: 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: FAQ ^^^ \- Possible subsections: FAQ .. _Configuration: Configuration ------------- .. _Extension-settings-ext-Manager: 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: 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: .. ### BEGIN~OF~TABLE ### .. _specialelements-noCacheElementNames: specialelements.noCacheElementNames """"""""""""""""""""""""""""""""""" .. container:: table-row 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: specialelements.noCacheElementIDs """"""""""""""""""""""""""""""""" .. container:: table-row 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 .. ###### END~OF~TABLE ###### Setup: .. ### BEGIN~OF~TABLE ### .. _tt-content-specialelements-postUserFunc: tt\_content.specialelements.postUserFunc """""""""""""""""""""""""""""""""""""""" .. container:: table-row 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 .. ###### END~OF~TABLE ###### .. _Developer-Guide: Developer Guide --------------- .. _How-to-create-a-special-element-basics: 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: How to create a special element (detailed) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _Filestructure: 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: |img-3| Example files: """""""""""""""""""""" .. _ext-tables-php: 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}** ”. :: **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: ext\_tables.sql """"""""""""""" :: # # Table structure for table 'tt_content' # CREATE TABLE tt_content ( title2 varchar(45) DEFAULT '' NOT NULL ); .. _ext-typoscript-setup-txt: 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 = |
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: 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: locallang.php """"""""""""" (specialelement title is defined here in “be\_title”) :: 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: 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] ::
###db_header###
###db_subheader###
###bodytext###
**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** : ::
###image_0### ###altText### ###image_1### ###altText###
**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 = wrap = | JSwindow.expand = 17,20 } stdWrap.spaceAfter=0 altText.field=imagecaption # special TS for use in specialelements: altText.marker.wrap =
| } elements.image < lib.small_image .. _locallang-csh-php: 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: 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: 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 = page.stylesheet = {$stylesheet} page.20 = TEMPLATE page.20 { ... .. _Known-problems: 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() .. so if you have problems with this extension make sure no other extension extends the same classes/functions. .. _To-Do-list: 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: Changelog --------- \- 1.0: not compatible to previous versions – everything new |img-13| EXT: th\_specialelements - 10 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.jpeg .. :align: left .. :border: 0 .. :height: 557 .. :id: Grafik11 .. :name: Grafik11 .. :width: 669 .. |img-2| image:: img-2.jpeg .. :align: left .. :border: 0 .. :height: 400 .. :id: Grafik12 .. :name: Grafik12 .. :width: 561 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 95 .. :id: Grafik1 .. :name: Grafik1 .. :width: 449 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik2 .. :name: Grafik2 .. :width: 150 .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik3 .. :name: Grafik3 .. :width: 150 .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik4 .. :name: Grafik4 .. :width: 150 .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik6 .. :name: Grafik6 .. :width: 150 .. |img-8| image:: img-8.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik7 .. :name: Grafik7 .. :width: 150 .. |img-9| image:: img-9.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik8 .. :name: Grafik8 .. :width: 150 .. |img-10| image:: img-10.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik5 .. :name: Grafik5 .. :width: 150 .. |img-11| image:: img-11.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik9 .. :name: Grafik9 .. :width: 150 .. |img-12| image:: img-12.png .. :align: left .. :border: 0 .. :height: 100 .. :id: Grafik10 .. :name: Grafik10 .. :width: 150 .. |img-13| image:: img-13.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102