.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ======================== EXT: PMK Forced Download ======================== :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed: 2009-11-17T18:44:28.070000000 :Classification: pmkfdl :Description: The keywords help with categorizing and tagging of the manuals. You can combine two or more keywords and add additional keywords yourself. Please use at least one keyword from both lists. If your manual is NOT in english, see next tab "language" ---- forEditors (use this for editors / german "Redakteure") forAdmins (use this for Administrators) forDevelopers (use this for Developers) forBeginners (manuals covering TYPO3 basics) forIntermediates (manuals going into more depth) forAdvanced (covering the most advanced TYPO3 topics) see more: http://wiki.typo3.org/doc_template#tags ---- :Keywords: forAdmins, forDevelopers, forIntermediates :Author: Peter Klein :Email: pmk@io.dk :Info 4: :Language: en |img-1| |img-2| EXT: PMK Forced Download - pmkfdl .. _EXT-PMK-Forced-Download: EXT: PMK Forced Download ======================== |img-3| Extension Key: pmkfdl Language: en Keywords: forAdmins, forDevelopers, forIntermediates Copyright 2009, Peter Klein, 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: Table of Contents ----------------- `EXT: PMK Forced Download 1 <#1.EXT:%20PMK%20Forced%20Download|outline>`_ **`Introduction 3 <#1.1.Introduction|outline>`_** `What does it do? 3 <#1.1.1.What%20does%20it%20do_|outline>`_ **`Users manual 4 <#1.2.Users%20manual|outline>`_** **`Administration 5 <#1.3.Administration|outline>`_** **`Configuration 6 <#1.4.Configuration|outline>`_** `Reference 6 <#1.4.1.Reference|outline>`_ `Special "register" values. 6 <#1.4.2.Special%20"register"%20values.|outline>`_ `Examples 6 <#1.4.3.Examples|outline>`_ `Fileicons 8 <#1.4.4.Fileicons|outline>`_ `Enable pmkfdl for filelinks in tt\_news 9 <#1.4.5.Enable%20pmkfdl%20for%20filelinks%20in%20tt_news|outline>`_ **`Hooks for extending the plugin 10 <#1.5.Hooks%20for%20extending%20the%20plugin|outline>`_** **`Known problems 11 <#1.6.Known%20problems|outline>`_** **`To-Do list 12 <#1.7.To-Do%20list|outline>`_** **`Reporting Bugs 13 <#1.8.Reporting%20Bugs|outline>`_** **`Updates 14 <#1.9.Updates|outline>`_** **`ChangeLog 15 <#1.10.ChangeLog|outline>`_** .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ Force a download on links to files. With this extension it's possible to force download of files like images, PDFs, MP3 etc., overriding the browser settings. (Normally when you click on a TYPO3 link to a file like an image, the image will open in the browser.) Works by extending the stdWrap/typolink function. So the extension can be used in other extensions which uses the standard TYPO3 typolink functionality when linking. If a link points to a valid file (with a file extension not listed in the blocked file extensions config var) Then the link will be modified to point to a eID script. This script then sends the file to the user by setting the response header to the matching mime type. .. _Users-manual: Users manual ------------ Once the extension is installed, you can use the new stdWrap/userFunc on your typolink file links. .. _Administration: Administration -------------- N/A .. _Configuration: Configuration ------------- See typoscript examples later in the manual for how to use. .. _Reference: Reference ^^^^^^^^^ .. ### BEGIN~OF~TABLE ### .. _makeDownloadLink: makeDownloadLink """""""""""""""" .. container:: table-row Property makeDownloadLink Data type boolean / string Description If set, link will be rewritten into a download link which opens up a browser prompt. Special cases: If the value is "forcedl" then the download will begin instantly without opening up a browser prompt. If the value is "secure" then the access groups required to view the page or content element is passed as a parameter, which is then compared with the users permission. All parameters will also be encrypted using PHP's “mcrypt”, using TYPO3\_CONF\_VARS['SYS']['encryptionKey'] as key. Note: It is possible to combine the 2 special options, by specifying both values separated by a “\|” pipe char. Default .. ###### END~OF~TABLE ###### [tsref:(stdWrap)] Since the extension works on standard typolink generated links, it's quite easy to implement it for RTE generated links too. Just add the following line to your TypoScript Setup: :: lib.parseFunc_RTE.tags.link.typolink.parameter.postUserFunc = tx_pmkfdl->makeDownloadLink (Note: if you are using RealURL or CoolURI, you might need to add “html” to the list of blocked file extensions.) .. _Special-register-values: Special "register" values. ^^^^^^^^^^^^^^^^^^^^^^^^^^ After creating a download link, two special register values are available: - **filesize** - This contains the size of the file. (in bytes) - **filetype** - This contains the type of the file. (gif, pdf, zip etc.) .. _Examples: Examples ^^^^^^^^ .. _generated: ((generated)) """"""""""""" .. _Example-of-usage-as-extended-stdWrap-parameter-Requires-TYPO3-v4-2: Example of usage as extended stdWrap parameter (Requires TYPO3 v4.2+): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: 10 = TEXT 10.value = download 10.typolink.parameter = fileadmin/templates/images/dwarf_male120x.gif 10.typolink.parameter.makeDownloadLink = 1 .. _Example-of-usage-as-userFunction: Example of usage as userFunction: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: 10 = TEXT 10.value = download 10.typolink.parameter = fileadmin/templates/images/dwarf_male120x.gif 10.typolink.parameter.postUserFunc = tx_pmkfdl->makeDownloadLink If the typolink points to a valid file, then the link will be modified to something like this: :: http://www.mydomain.com/index.php?eID=pmkfdl&file=fileadmin%2Ftemplates%2Fimages%2Fdwarf_male120x.gif&ck=a94fad5a0262b2e00e1aa72e8aac4c30 This link will open up a browser prompt, asking the user what he wants to do with the file (Save, Open etc.) A MD5 checksum is added as a 2nd parameter to insure that it is the correct file that is being downloaded. (If the MD5 checksum doesn't match the file, then the download will be terminated.) .. _Forced-download: Forced download """"""""""""""" If you want to force the download to start instantly without opening up the browser prompt, you can add a special option/parameter called "forcedl" .. _Example-of-usage-as-extended-stdWrap-parameter-with-forcedl-set-Requires-TYPO3-v4-2: Example of usage as extended stdWrap parameter, with "forcedl" set (Requires TYPO3 v4.2+): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: 10 = TEXT 10.value = download 10.typolink.parameter = fileadmin/templates/images/dwarf_male120x.gif 10.typolink.parameter.makeDownloadLink = forcedl .. _Example-of-usage-as-userFunction-with-forcedl-set: Example of usage as userFunction, with "forcedl" set: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: 10 = TEXT 10.value = download 10.typolink.parameter = fileadmin/templates/images/dwarf_male120x.gif 10.typolink.parameter.postUserFunc = tx_pmkfdl->makeDownloadLink 10.typolink.parameter.postUserFunc.makeDownloadLink = forcedl .. _Example-of-using-the-register-value: Example of using the register value: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: 10 = COA 10 { # Display the filelink 10 = TEXT 10.value = download 10.typolink.parameter = fileadmin/templates/images/dwarf_male120x.gif 10.typolink.parameter.postUserFunc = tx_pmkfdl->makeDownloadLink # Display the filesize from register value 20 = TEXT 20.data = register:filesize 20.bytes = 1 20.wrap =
Filesize: |
# Display the filetype from register value 30 = TEXT 30.data = register:filetype 30.wrap =
Filetype: |
} .. _Advanced-example-of-using-the-register-value-for-displaying-a-filetype-icon: Advanced example of using the register value for displaying a filetype icon: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: 10 = COA 10 { wrap =
|
# First we store the link in a register value, since # we want to display an icon BEFORE the link. 10 = LOAD_REGISTER 10.filelink.cObject = TEXT 10.filelink.cObject { value = download stdWrap typolink.parameter = fileadmin/templates/images/dwarf_male120x.gif typolink.parameter.makeDownloadLink = 1 } # Display the fileicon and filelink 20 = CASE 20 { # Wrapping of image, incl. the filelink from previously created register value stdWrap.dataWrap = | {register:filelink} # Case key is the filetype (from register value) key.data = register:filetype default = IMAGE default.file = fileadmin/fileicons/default.gif gif < .default gif.file = fileadmin/fileicons/gif.gif # You can add more types here } # Display the filesize ( from register value) 30 = TEXT 30.data = register:filesize 30.bytes = 1 30.wrap =  (|) } .. _Secure-downloads: Secure downloads """""""""""""""" If the "secure" option is selected, then all GET parameters will be encrypted. So it will no longer be possible to see the path/filename in the URL, which will look something like this: :: http://www.mydomain.com/index.php?eID=pmkfdl&sfile=qrjyPtFoTa6AdvdexSe%2BUQekt5gkrV3ptMnhp1bzkl%2FUmI1MSdIZcYo8MDBuuy5%2BYICkJboTVh%2FcpIpdb%2BJ4UBB3upcnEShGJzNBBQl1UknUwtUg9Ifi2t4rW69cNak1tjtlGhjkkno%3D If the page/content element where the filelink is located, has special access permissions, these access permissions will also be passed along to the eID script.The permissions is then compared with the permissions of the user downloading the link. If the comparison fails, a 404 header is sent to the browser. .. _Example-of-usage-as-userFunction-with-secure-set: Example of usage as userFunction, with "secure" set: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: 10 = TEXT 10.value = download 10.typolink.parameter = fileadmin/templates/images/dwarf_male120x.gif 10.typolink.parameter.postUserFunc = tx_pmkfdl->makeDownloadLink 10.typolink.parameter.postUserFunc.makeDownloadLink = secure .. _Fileicons: Fileicons ^^^^^^^^^ A folder with fileicons from the Splitbrain Fileicon Project ( `http://www.splitbrain.org/projects/file\_icons `_ ) is located in the **res/** folder. |img-4| A sample TypoScript lib is provided as a static template. To use it, just include the static template and do like this to create a filelink with icon and filesize. :: lib.mylink < lib.downloadLink # Specify the title of the link here. lib.mylink.10.filelink.cObject.value = Download manual # Specify the file for the link here. lib.mylink.10.filelink.cObject.typolink.parameter = fileadmin/user_upload/manual.pdf TYPO3 also has a fileicons collection located in the folder **typo3/gfx/fileicons/** , but the path is not accessible from typoscript. So if you want to use those, you need to copy the folder into the **fileadmin/** folder. .. _Enable-pmkfdl-for-filelinks-in-tt-news: Enable pmkfdl for filelinks in tt\_news ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The filelinks in tt\_news is generated by the cObj->filelink() function, so it is not possible to use the pmkfdl on those links. But if you enable the pmkfdl hook for tt\_news, the links will instead be generated using the typolink function. (Actually it is generated by a TypoScript object) To enable this feature, you must enable the hook in the Extension Manager and include the pmkfdl static template AFTER the tt\_news static template. .. _Hooks-for-extending-the-plugin: Hooks for extending the plugin ------------------------------ The extension contains two hooks for extending the functionality of the plugin: **preProcessHook** (located in the file **class.tx\_pmkfdl.php** ) This hook is activated just before the link is generated. Possible use: Adding extra GET parameters to the link. Modifying the existing GET parameters. Adding extra register values with additional data. (Such as download count.) **postProcessHook** (located in the file **class.tx\_pmkfdl\_download.php** ) This hook is activated just before the file is pushed to the browser. Possible use: Logging the downloads. (see example hook script) Adding additional access checks. An example hook script **class.tx\_pmkfdl\_process\_hook.php** is located in the **res/** folder. This script will create a logfile in the **fileadmin/** called **pmkfdl\_log.txt** , which is updated whenever someone downloads a file. .. _Known-problems: Known problems -------------- - Due to a (still unfixed) bug in interface.tslib\_content\_stdwraphook.php (See Bugtracker `http://bugs.typo3.org/view.php?id=9058 `_ ), it is recommended to use the extension as a userFunc until this bug is fixed! - The bug still exists 1.5 years after reporting it, so I guess bugfixing is not high on the TYPO3 core members priority list :( .. _To-Do-list: To-Do list ---------- Nothing planned, but ideas are welcome. .. _Reporting-Bugs: Reporting Bugs -------------- - If you discover a bug, please don't write the author(s) directly. Instead post a bug report at the Forge bugtracker: `http://forge.typo3.org/projects/show/extension-pmkfdl `_ - That way others can see your bug report and maybe add additional comment. It also makes it possible for all the extension authors to see what bugs are already been fixed by one of the other authors. .. _Updates: Updates ------- - If you like this extension, please rate it. `http://typo3.org/extensions/repository/view/pmkfdl/current/rating/ `_ - As ratings are the only way I can see if there's an interest in this extension, updates depends on people rating it. - **(No ratings = No updates)** - For latest version, always check the Forge repository: `http://forge.typo3.org/projects/show/extension-pmkfdl `_ .. _ChangeLog: ChangeLog --------- - 14.Nov.2009 - Fixed problem with Access check not used in class tx\_pmkfdl\_download. (Thanks to Rainer Becker for reporting this.) - TypoScript conf var is now saved as a class var, so that it can be accessed from hooks. - - 1.Nov.2009 - Added tt\_news hook script to enable pmkfdl for filelinks in tt\_news - - 19.Oct.2009 - Fixed linefeed problem in logfile (Thanks to Stefan Galinski for reporting this.) - Added support for user definable logfile name/path. - - 18.Oct.2009 - Updated the manual with info about hooks and the secure mode. - Added static template with lib object for creating filelinks with icons and filesize, similar to the one described in the manual, but using the file icons in the res/ folder. - Fixed small problem in ext\_emconf.php - - 15.Oct.2009 - Added hooks for pre- and post- processing of links. An example hooks script is located in the res/ folder. This script will create a logfile in fileadmin/ called pmkfdl\_log.txt, which is updated whenever someone downloads a file. - - 14.Oct.2009 - Replaced the “crypt\_blowfish” dependencies with plain PHP “mcrypt” functions. - - 7.Oct.2009 - Added support for encrypted filenames if the extension “crypt\_blowfish” is installed. - - 30.Sep.2009 - Added fileicons from the Splitbrain Fileicon Project ( `http://www.splitbrain.org/projects/file\_icons `_ ) - - 29.Sep.2009 - Added register values for making the filesize and filetype accessible from typoscript. - - 26.Sep.2009 - Fixed Bug #4768 by adding “PATH\_site” to the “finfo\_file” and “mime\_content\_type” lookups. (Thanks to Stefan Galinski for reporting this bug.) - Added check for blocked file extensions in the “class.tx\_pmkfdl.php” file. - - 20.Sep.2009 - First version released on TER 15 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. |img-2| image:: img-2.png .. :border: 0 .. :height: 21 .. :hspace: 9 .. :id: Grafik2 .. :name: Grafik2 .. :width: 87 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 128 .. :id: graphics1 .. :name: graphics1 .. :width: 128 .. |img-4| image:: img-4.png .. :align: left .. :border: 1 .. :height: 319 .. :id: graphics2 .. :name: graphics2 .. :width: 479