.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt =============================== EXT: Advanced Banner Management =============================== :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed by: Wolfgang Becker :Changed: 2009-12-10T15:09:19.860000000 :Email: wb@macina.com :Info 2: :Info 3: :Info 4: .. _EXT-Advanced-Banner-Management: EXT: Advanced Banner Management =============================== Extension Key: **macina\_banners** Copyright 2000-2002, `wolfgang.becker@visionate.com `_ , < `wolfgang.becker@visionate.com `_ > 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: Advanced Banner Management 1** **Introduction 1** What does it do? 1 Features: 1 Screenshots 2 **Users manual 3** Installation 3 Installation Configuration 3 Add Banner Categories 3 Add Banners 4 Add banner module as content element 5 Add Clicktracking to Flash banners 6 Add banner module to template 6 **Configuration 6** Excludefields 6 TypoScript 7 HTML Template 7 **To Do List 7** **Known problems 7** **Changelog 8** .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ This extension allows Backend users to add banners to the website. .. _Features: Features: ^^^^^^^^^ - Support for Flash files, animated GIFs, images and custom HTML Code - Show banner on all pages, single pages or groups of pages - Show context sensitive banners using get-parameter matching Click tracking for image and Flash banners - Banners with internal or external links - Time-controlled publishing of banners - Display random banners - Localization & versioning of banners - Access limits for Frontend usergroups - Modify appearance by specifying a maximum width and borders - HTML template for each banner group - Configurable locations for banners. - Logging of impressions and clicks - Banner groups in sysfolders - Insert as plugin(content element) or directly into the template by TS .. _Screenshots: Screenshots ^^^^^^^^^^^ |img-1| Screenshot of the banner creation (Image 1) .. _Users-manual: Users manual ------------ .. _Installation: Installation ^^^^^^^^^^^^ |img-2| To use the extension, connect to the Extension Repository through your extension manager and install it by clicking the “plus” Icon (extkey:macina\_banners). .. _Installation-Configuration: Installation Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _img-3-activateDefaultCategories: |img-3| activateDefaultCategories """"""""""""""""""""""""""""""""" If set macina\_banners will provide default categories e.g. top .. _renderMode: renderMode """""""""" |img-4| Decide how the categories should be selected:two\_boxes |img-5| singlebox |img-6| checkbox .. _Add-Banner-Categories: Add Banner Categories ^^^^^^^^^^^^^^^^^^^^^ |img-7| To group your banners, or for better maintenance create a sysfolder:Call it “Banner” and create your banner records in there.Note: Bannercategories can be added only to sysfolders.Note: To use the localization feature in the List Module create a translation of the sysfolder. |img-8| Click the “Create new record” and select Record Type “Banner Category”. Edit the following data in the Categoriy Form .. _img-9-Description: |img-9| **Description** """""""""""""""""""""""" Choose a description for your categorieNote: This field can be used in TypoScript for “placement” .. _Icon: Icon """" Choose an that stands for your categoryNote: The Icon is only rendered in the forms if renderMode is “checkbox” ( See Installation ) .. _Add-Banners: Add Banners ^^^^^^^^^^^ To group your banners and categories, or for better maintenance create a sysfolder:Call it “Banner” and create your banner records in there.Note: Banners can be added to every page, not only to sysfolders.Note: To use the localization feature in the List Module create a translation of the sysfolder. |img-10| Click the “Create new record” and select Record Type “banner”. Edit the folowing data in the FlexForm (see Image 1) .. _Banner-type: Banner type """"""""""" choose file type for your banner (image or swf) .. _Flash-banners: Flash banners: ~~~~~~~~~~~~~~ .. _Flash-banner: Flash banner """""""""""" Point the File wizard to your Flash file. .. _Width-of-Flash-movie: Width of Flash movie """""""""""""""""""" Enter the width of your Flash file.Note: Mandatory entry. .. _Height-of-Flash-movie: Height of Flash movie """"""""""""""""""""" Enter the height of your Flash file.Note: Mandatory entry. .. _Click-count: Click count """"""""""" Auto-incrementing field which counts the clicks of the Banner. (Don't enter anything). .. _Image-banners: Image banners: ~~~~~~~~~~~~~~ .. _Banner-image: Banner image """""""""""" Point the file wizard to your banner file. .. _Image-text: Image text """""""""" Enter the text which will be shown as alttext on the banner .. _HTML-banners: HTML banners: ~~~~~~~~~~~~~ .. _HTML: HTML """" Add your custom HTML Banner Code .. _All-banners: All banners: ~~~~~~~~~~~~ .. _Parameters: Parameters """""""""" Enter a list of parameter names with values, one parameter per line.For Example: RegionID\_cbo = 13,17 will enable the banner if the URL Parameter : RegionID\_cbo has the value 13 or 17.Note: To enable this feature you have to set the TS Parameter enableParameterRestriction to 1. CAUTION! If enableParameterRestriction is set to 1, ONLY Banners with matching Parameters are displayed. If you set enableParameterRestriction, the page will not be cached! .. _Link: Link """" Point the link wizard to an internal or external target .. _Placement: Placement """"""""" Choose the location where banner will appear on websiteNote: (Locations must exist in the Template or banner plugin in order for the banner to be shown!) .. _Show-banner-on-Pages-ONLY: Show banner on Pages ONLY """"""""""""""""""""""""" Point link wizard to the pages where the banner will appear.Note: If no pages are selected, the banner will appear on ALL Pages .. _Including-Subpages: Including Subpages """""""""""""""""" Check this and the banner will be visible on all subpages of the selected pages in “Show banner on Pages ONLY” .. _DONT-show-Banner-on-THESE-Pages: DONT show Banner on THESE Pages """"""""""""""""""""""""""""""" Point link wizard to the pages where the banner will not appear. .. _Customer: Customer """""""" Enter the name of your advertising customer. For maintenance only; will not be shown. .. _Impressions: Impressions """"""""""" Auto-incrementing field which counts the number of impressions of the banner. (Don't enter anything) .. _Start-Stop: Start Stop """""""""" Enter date/times to create a timeframe for the banner to be shown. .. _Access: Access """""" Limit access by entering Frontend groupsNote: Banner will only be shown if this group is logged in! .. _Add-banner-module-as-content-element: Add banner module as content element ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Switch to your Typo3 Backend and point the page module to the page where you want to add the Bannermodule.Click “new content”.Choose Bannermodule from the Plugins section: |img-11| .. _Plugin: Plugin """""" Shows Bannermodule as a plugin .. _Placement: Placement """"""""" Select Plugin PositionNote: With this selection you decide which banners the plugin will show. Select top to show all banners which are assigned to Top. .. _Mode: Mode """" Choose if module shows ALL, or a single random banner or All Banners in random orderNote: If you choose random, the page with the random banner will not be cached! .. _Startingpoint: Startingpoint """"""""""""" Point the link wizard to the pages where your banners are storedNote: The plugin will only show banners from this locations .. _Recursive: Recursive """"""""" Choose the depth to search for banners. .. _Add-Clicktracking-to-Flash-banners: Add Clicktracking to Flash banners ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To add click tracking to your Flash banner, use the 2 Variables “clickTag” and “target” which are passed to the Flash banner via the OBJECT EMBED Tag. Create a MovieClip with the InstanceName “content” and assign the following handler to the onRelease Event: ActionScript 2 Code: :: if (clickTAG.substr(0, 5) == "http:" || clickTAG.substr(0, 6) == "https:") { contentClip.onRelease = function() { getURL(clickTAG, target); }; } Or create a Button and put the following script to your Button: ActionScript 1 Code: :: on (release) { if (clickTAG.substr(0,5) == "http:"| | clickTAG.substr(0, 6) == "https:") { getURL(_root.clickTAG, _root.target); } } Note: The ActionScript in this Flash banner is verifying that the clickTAG URL begins with "http:" or “https:”. This is an important security measure. If you do not take this precaution, a malicious HTML page could source your SWF and pass a clickTAG URL that begins with "javascript:" or another scripting pseudo-protocol. If your ActionScript code were to call getURL with a maliciously crafted JavaScript URL, it would be possible for the site serving the malicious HTML page to obtain the contents of your HTTP cookies or perform other actions on your site's behalf. .. _Add-banner-module-to-template: Add banner module to template ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As an alternative to the plugin method, you can add the banner module with TypoScript to your template.Note: You can add multiple modules to the page to use different locations like left, right, top and bottom. .. _generated: ((generated)) """"""""""""" .. _EXAMPLE: EXAMPLE ~~~~~~~ To add the banner module to your site template, create a marker in your HTML template: ###bannertop###. Add this code to your main TS Template to substitute the marker with the plugin: :: temp.bannertop < plugin.tx_macinabanners_pi1 temp.bannertop { # show banners with this attribute, default options are: "top, left, bottom, right", all Descriptions of Banner Categories can be used placement = top #mode to show banners. Options are: all, random mode = all # list of page IDs where the banners should be taken from (comma seperated. i.e.: 1,5,7) pidList = 18 # levels of recursion to search for banners recursive = 0 # Limit number of banners results_at_a_time = 3 } marks.bannertop < temp.bannertop .. _IMAGE: IMAGE """"" Example how to use the image configuration with GIFBUILDER: :: temp.bannertop < plugin.tx_macinabanners_pi1 temp.bannertop { image { file = GIFBUILDER file { XY = 468,60 10 = IMAGE 10.file = field_image 10.file.maxW = 468 10.file.minW = 468 10.file.maxH = 60 10.file.minH = 60 10.altText = field_alttext 10.align = c,c } } } Note: The Parameters: ***field\_image*** and ***field\_alttext*** are Placeholders for the actual “Bannerimage” and “Image Text” from the Banner Record. .. _Configuration: Configuration ------------- .. _Excludefields: Excludefields ^^^^^^^^^^^^^ The plugin has 6 Excludefields which can be added to user profiles to prevent Backend users from changing these banner settings: - hide - start - stop - access - Impressions - ClickCount .. _TypoScript: TypoScript ^^^^^^^^^^ Reference (TypoScript) .. ### BEGIN~OF~TABLE ### .. _parser: parser """""" .. container:: table-row Property parser Data type string Description Parse function to render images and links Default tt\_content.text.20.parseFunc .. _templateFile: templateFile """""""""""" .. container:: table-row Property templateFile Data type sring Description HTML template to be used for the plugin Default EXT:macina\_banners/pi1/template.htm .. _pidList: pidList """"""" .. container:: table-row Property pidList Data type Commalist of Values Description List of page ids where the banners should be pulled from (comma separated. i.e.: 1,5,7) Default .. _recursive: recursive """"""""" .. container:: table-row Property recursive Data type int Description Levels of recursion to search for banners Default 0 .. _placement: placement """"""""" .. container:: table-row Property placement Data type string Description Show banners with this attribute. Options are: top, left, bottom, right Default top .. _mode: mode """" .. container:: table-row Property mode Data type string Description Mode to show banners. Options are: all, random Default all .. _results-at-a-time: results\_at\_a\_time """""""""""""""""""" .. container:: table-row Property results\_at\_a\_time Data type int Description Limit number of selected banners Default 100 .. _image: image """"" .. container:: table-row Property image Data type IMAGE Description tsref:(cObject).IMAGE The Parameters: field\_imageand field\_alttextcan be used as Placeholders for the actual “Bannerimage” and “Image Text” from the Banner Record Default image { file.maxW = 468 } .. _enableParameterRestriction: enableParameterRestriction """""""""""""""""""""""""" .. container:: table-row Property enableParameterRestriction Data type int Description CAUTION! If enableParameterRestriction is set to 1, ONLY Banners with matching Parameters are displayed. If you set enableParameterRestriction, the page will not be cached! Default 0 .. ###### END~OF~TABLE ###### [plugin.tx\_macinabanners\_pi1] .. _HTML-Template: HTML Template ^^^^^^^^^^^^^ The template is found in the path of your extension directiory: :: typo3conf/ext/macina_banners/pi1/template.htm To change the layout of your banner module, open the template with your favorite HTML editor, and modify it to suit your needs. To prevent the template from being overwritten when you upgrade the extension in the future, place a copy in an appropriate directory (i.e. /fileadmin/template/) and reference it in TS with the templateFile property. .. _generated: ((generated)) """"""""""""" .. _Markers: Markers ~~~~~~~ The Markers (###MARKER###) are replaced by the plugin as follows: - content goes here Wrap your tablecell with these markers.Note: Wrap the row markers around a and the banners will be displayed horizontally.To display banners vertically, place the rowmarkers outsitde of the tags. - content goes here Wrap your content with these markers to link it with the banner link. - ###banner### Displays the banner image with link and alttext - ###alttext### Displays the alttext - ###filename### The image or Flash file name - ###url### The banner's URL - ###impressions### Impressions count - ###clicks### Clicks count - ###edit### Displays a frontend Admin Panel for Backend users .. _To-Do-List: To Do List ---------- - Make a Backend module for banner statistics and maintenance - Keyword-based banner selection to show banners depending on page keywords .. _Known-problems: Known problems -------------- Currently no problems known. Feel free to report any bugs to `wolfgang.becker@visionate.com `_ .. _Changelog: Changelog --------- .. ### BEGIN~OF~TABLE ### .. _Ver-1-5-1: Ver. 1.5.1 ^^^^^^^^^^ .. container:: table-row Version Ver. 1.5.1 Changes Added support for cObject.IMAGE ( thanx toGernot Ploiner/WEBprofil ) .. _Ver-1-5-0: Ver. 1.5.0 ^^^^^^^^^^ .. container:: table-row Version Ver. 1.5.0 Changes Show context sensitive banners using get-parameter matching added HTML Banner Type added Banner Categories added new Mode: show all Banners randomized strict use of typo db functions credits to medialights for 1.5 features .. _Ver-1-4-1: Ver. 1.4.1 ^^^^^^^^^^ .. container:: table-row Version Ver. 1.4.1 Changes fixed SQL Injection vulnerability => credits to Stefan Geithremoved needless server logging .. _Ver-1-4-0: Ver. 1.4.0 ^^^^^^^^^^ .. container:: table-row Version Ver. 1.4.0 Changes Added clicktracking for flash banners. .. _Ver-1-3-1: Ver. 1.3.1 ^^^^^^^^^^ .. container:: table-row Version Ver. 1.3.1 Changes Improved caching => extension is switched to user\_int (non cached) dynamically when mode = random. Thanx to Peter Russ for this improvement .. _Ver-1-3-0: Ver. 1.3.0 ^^^^^^^^^^ .. container:: table-row Version Ver. 1.3.0 Changes Improved external banner links for get Parameters Improved external banner links for the realUrl extension .. _Ver-1-2-0: Ver. 1.2.0 ^^^^^^^^^^ .. container:: table-row Version Ver. 1.2.0 Changes Fixed search engine bug Changed to non-cached user object (USER\_INT) Fixed invalid HTML when no banner is displayed Changed border rendering from table to div .. _Ver-1-0-0: Ver. 1.0.0 ^^^^^^^^^^ .. container:: table-row Version Ver. 1.0.0 Changes Fixed Bug in Limit Results at a Time .. _Ver-0-5-0: Ver. 0.5.0 ^^^^^^^^^^ .. container:: table-row Version Ver. 0.5.0 Changes Added multilanguage support and localization feature. .. _Ver-0-4-0: Ver. 0.4.0 ^^^^^^^^^^ .. container:: table-row Version Ver. 0.4.0 Changes Added feature to attach banners to pages with subpages Added feature exclude banner on pages Added wrap with banner link Added TypoScript variable to limit the number of selected banners .. _Ver-0-3-0: Ver. 0.3.0 ^^^^^^^^^^ .. container:: table-row Version Ver. 0.3.0 Changes Added support for different install path than in document root. Added support for animated GIFs .. _Ver-0-1-1: Ver. 0.1.1: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.1.1: Changes Added Flash banner support HTML code XHTML compliant Banner query improved for better performance .. _Ver-0-1-0: Ver. 0.1.0: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.1.0: Changes Fixed global install bug Now the extension can be installed global AND/OR local .. _Ver-0-0-8: Ver. 0.0.8: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.0.8: Changes “random” mode improved The mode for selecting a random banner should work now.If you choose random, the page with the random banner will not be cached! .. _Ver-0-0-7: Ver. 0.0.7: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.0.7: Changes Changes to clickcount system. I changed the technique to count clicks for external links.Now there is no page refresh anymore after clicking an external linked banner.Affected pages are: class.tx\_macinabanners\_pi1.php and the new class.tx\_macinabanners\_launchpage.php. .. _Ver-0-0-6: Ver. 0.0.6: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.0.6: Changes Added new template markers (###alttext###, ###image###, ###url###, ###impressions###, ###clicks### .. _Ver-0-0-5: Ver. 0.0.5: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.0.5: Changes Fixed bug on selecting banners for pages (example: Page 2 has selected banners for pages 23, 24, 25... too) .. _Ver-0-0-4: Ver. 0.0.4: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.0.4: Changes Maintenance.. .. _Ver-0-0-3: Ver. 0.0.3: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.0.3: Changes Fixed bug on banner link. .. _Ver-0-0-2: Ver. 0.0.2: ^^^^^^^^^^^ .. container:: table-row Version Ver. 0.0.2: Changes Initial Release .. ###### END~OF~TABLE ###### |img-12| EXT: Advanced Banner Management - 9 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.jpeg .. :align: left .. :border: 0 .. :height: 923 .. :id: Grafik1 .. :name: Grafik1 .. :width: 522 .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :height: 52 .. :id: Graphic3 .. :name: Graphic3 .. :width: 355 .. |img-3| image:: img-3.jpeg .. :align: left .. :border: 0 .. :height: 170 .. :id: graphics1 .. :name: graphics1 .. :width: 669 .. |img-4| image:: img-4.jpeg .. :align: left .. :border: 0 .. :height: 93 .. :id: graphics2 .. :name: graphics2 .. :width: 523 .. |img-5| image:: img-5.jpeg .. :align: left .. :border: 0 .. :height: 84 .. :id: graphics3 .. :name: graphics3 .. :width: 269 .. |img-6| image:: img-6.jpeg .. :align: left .. :border: 0 .. :height: 154 .. :id: graphics4 .. :name: graphics4 .. :width: 138 .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :height: 13 .. :id: Graphic5 .. :name: Graphic5 .. :width: 59 .. |img-8| image:: img-8.jpeg .. :align: left .. :border: 0 .. :height: 19 .. :id: graphics5 .. :name: graphics5 .. :width: 144 .. |img-9| image:: img-9.jpeg .. :align: left .. :border: 0 .. :height: 128 .. :id: graphics6 .. :name: graphics6 .. :width: 490 .. |img-10| image:: img-10.png .. :align: left .. :border: 0 .. :height: 11 .. :id: Graphic6 .. :name: Graphic6 .. :width: 68 .. |img-11| image:: img-11.png .. :align: left .. :border: 0 .. :height: 45 .. :id: Graphic4 .. :name: Graphic4 .. :width: 344 .. |img-12| image:: img-12.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102