.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ===================== EXT: External PageSet ===================== :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed by: Sebastien St-Laurent :Changed: 2003-05-27T08:34:31 :Classification: external_pageset extension documentation :Keywords: external pageset caching indexing html :Author: Sebastien St-Laurent :Email: sebby@sbcglobal.net :Info 3: :Info 4: .. _EXT-External-PageSet: EXT: External PageSet ===================== Extension Key: **external\_pageset** Copyright 2000-2002, Sebastien St-Laurent, 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? ^^^^^^^^^^^^^^^^ This extension serves the purpose of displaying extrnal html files within a single page. Although a similar result could be achieved through IFrames, this extension allows caching and indexing of the content. The best way to describe the use of this extension is to give an example. Lets say your website contains source code documentation that was generated through the use of an external tool (like Doxygen). This tool will generate hundreds of webpages containing documentation for your source code. At this point, if you want the documentaion displayed within your website, you either have to manually insert hundreds of pages of content or use an IFrame. Adding the content by hand would take a ridiculous number of hours and the use of IFrame prevents the use of caching and especially indexing. This extension will take the content from a page and dynamically merge it to the content of the current page, making sure to remap links and references within the content so that it is mapped relative to the current page. The extension also generates proper cHash values to allow caching/indexing of the content. .. _NOTE: NOTE """" Although we use the term external content, we use this term to refer to content generated by an external source and not content located on an external webserver. .. _Screenshots: Screenshots ^^^^^^^^^^^ Here is a screenshot of the extension in action along with a quick graph giving an idea on the works of the extension. |img-1| .. _Users-manual: Users manual ------------ Nothing perticular , see Administration for usage information. .. _Adminstration: Adminstration ------------- This section will mostly present how to setup and use the extension. .. _Configuration: Configuration ^^^^^^^^^^^^^ Configuration of this extension is easy. Simply add a content element in your page and activate the extension by picking “Insert Plugin” and then “External PageSet”. This content element will then be substituted at rendering time. Currently, 2 options are available to configure the extension. The first option is to use TypoScript to set the configuration values. The second option is to create an extension template on your page and configure the plugin with the constant editor within the template. See the “Reference” section for a description of the parameters. .. _FAQ: FAQ ^^^ Nothing here yet. .. _Reference: Reference ^^^^^^^^^ Here is a reference chart for properties available for this extension .. ### BEGIN~OF~TABLE ### .. _rootFile: rootFile """""""" .. container:: table-row Property rootFile Data type string Description Indicates the homepage of the website to be linked Default .. _remapExternal: remapExternal """"""""""""" .. container:: table-row Property remapExternal Data type boolean Description Indicates wether or not external HTTP:// style links will be remaped through the extension. Default 0 (no remapping) .. _remapRelative: remapRelative """"""""""""" .. container:: table-row Property remapRelative Data type boolean Description Indicates if relative links within the page needs to be remapped. This counts both for links and image paths. Default 1 (remaped) .. _extractBodyTitle: extractBodyTitle """""""""""""""" .. container:: table-row Property extractBodyTitle Data type boolean Description By default, the plugin attemps to use only content within the tag of the source file. In some cases, you may want to use the complete source file (i.e: running a PHP file) Default 1 (content comes from tags) .. _remap: remap """"" .. container:: table-row Property remap Data type boolean Description Turns on/off globally link remaping. If not needed, this can be a tremendous speed increase. Default 0 (remap links) .. _evalResult: evalResult """""""""" .. container:: table-row Property evalResult Data type boolean Description By default, all output is sent straight to the output. Any PHP code within the source document will not be processed. Turning this option on will force the plugin to process all output through an eval() function to force evaluation of any PHP code. **NOTE** : No attemp is made to make the PHP code within the page dynamic. The result of the eval() function will be cached along with the content of the page. This should be used for non-dynamic (or semi- dynamic) content. Default 0 (Results not evaluated) .. ###### END~OF~TABLE ###### .. _Considerations: Considerations -------------- - Because links within the page are manipulated through regular expressions, the time taken to load a page can be fairly long (depending on the page and your webserver). Try to take advantage of cacing to minimize the impact on your users. We will also look into possible code optimizations to speed up the process. - Keep in mind this plugin allows external HTML code to be processed. Because of security concerns you should now allow pages to be displayed from locations where malicious users could upload HTML/PHP code which could then be viewed and executed. Files should be located in a properly protected directory. - Remember that any PHP code processed through “evalResult” will have it's result cached and should only be used for non-dynamic or semi- dynamic content. - Note that implicit links (i.e: someweb\mydirectory\ ) will only work on a Apache based installation as we now query webserver for the expanded URI. .. _Known-problems: Known problems -------------- - Most likley will not work with external sites (http://). Have an option to turn off relinking of external links, but we may need real re-linking support for real external links. This is not the intent of this extension so this is a low priority item. - Forms contained within a webpage will most likley not function properly - Implicit URI's can only be decoded on a Apache based server running PHP as a module. .. _To-Do-list: To-Do list ---------- - More in-depth testing. (current test set is a doxygen generated website and the Apache documentation) - Try to see what can be done to speed process up. Initial caching can be slow for big and complex pages because of the regex replacement scripts. If anybody has experience speeding up similar processes and are willing to help, please let me know. - And of course, feel free to email your suggestions, bugs and test- cases!!! .. _Changelog: Changelog --------- .. _generated: ((generated)) ^^^^^^^^^^^^^ .. _Version-0-1-0: Version 0.1.0 """"""""""""" - Fixed bug where tags with with attributes were getting ignored - Added support to query Apache for expanded URI. This allows to support for paths with implicit pages. - Added workaround for bugs within the parsehtml class where tags with attributes seperated be non space whitespace isn't parsed properly. - Relative sections (i.e: href=”#mysection”) now works. - Updated documentation for all latest changes. .. _Version-0-0-6: Version 0.0.6 """"""""""""" - Added support for included PHP code through the eval function. - Support for turning off remaping of links for improved performance in special cases. .. _Version-0-0-4: Version 0.0.4 """"""""""""" - Added support for sub sections (# in link) - Tweaked documentation somewhat. .. _Version-0-0-3: Version 0.0.3 """"""""""""" - Added support for sub-directories within the fileRoot. - For security reasons, the script will die if any access below the fileRoot is requested. - Cleaned up code and fixed a few other little bugs. - First official version of the documentaion put online. .. _Version-0-0-2: Version 0.0.2 """"""""""""" - Added support for remapExternal and implemented it's basic functionality - First version of the user manual. - Fixed a few small bugs and code cleanup. |img-2| EXT: External PageSet - 4 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 394 .. :id: Graphic2 .. :name: Graphic2 .. :width: 560 .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102