Pushed MIME-transformation functionality by propagating the corresponding $meta value to plugins.

ChangeLog

@@ -12,6 +12,11 @@ $Source$
       formatting has been altered to preserve those.
     * libraries/transformations/text_plain__dateformat.inc.php3:
       Remove obsolete code, thanks to Thiemo Maettig!
+    * Documentation.html, libraries/display_tbl.lib.php3,
+      libraries/transformations/*:
+      The $meta field information is now passed to the transformation plugins
+      to allow future (and easier) usage of field information
+      (zerofill/unsigned/not_null/...).
 
 2003-11-04 Marc Delisle  <lem9@users.sourceforge.net>
     * Documentation.html: bug 833900, added known limitation in FAQ 3.10

Documentation.html

@@ -2134,6 +2134,16 @@ language file.</p><br />
 <p>To create a new transform function please see libraries/transformations/template_generator.sh.
 To create a new, empty mimetype please see libraries/transformations/template_generator_mimetype.sh.</p><br />
 
+<p>A transform function always gets passed three variables:</p>
+<ol>
+    <li><b>$buffer</b> - Contains the text inside of the column. This is the text, you want to transform.</li>
+    <li><b>$options</b> - Contains any user-passed options to a transform function as an array.</li>
+    <li><b>$meta</b> - Contains an object with field information to your column. The data is drawn from the output of the
+    <a href="http://www.php.net/mysql_fetch_field">mysql_fetch_field()</a> function. This means, all object properties described
+    on the <a href="http://www.php.net/mysql_fetch_field">manual page</a> are available in this variable and can be used to
+    transform a field accordingly to unsigned/zerofill/not_null/... properties.</li>
+</ol>
+
 <!-- FAQ -->
 <a name="faq"></a><br />
 <h2>FAQ - Frequently Asked Questions</h2>

libraries/display_tbl.lib.php3

@@ -1237,7 +1237,6 @@ if (!defined('PMA_DISPLAY_TBL_LIB_INCLUDED')) {
                     if (isset($GLOBALS['mime_map'][$meta->name]['mimetype']) && isset($GLOBALS['mime_map'][$meta->name]['transformation']) && !empty($GLOBALS['mime_map'][$meta->name]['transformation'])) {
                         // garvin: for security, never allow to break out from transformations directory
                         $include_file = eregi_replace('\.\.*', '.', $GLOBALS['mime_map'][$meta->name]['transformation']);
-
                         if (file_exists('./libraries/transformations/' . $include_file)) {
                             $transformfunction_name = str_replace('.inc.php3', '', $GLOBALS['mime_map'][$meta->name]['transformation']);
 
@@ -1315,9 +1314,9 @@ if (!defined('PMA_DISPLAY_TBL_LIB_INCLUDED')) {
                                                                    .  PMA_generate_common_url($map[$meta->name][3], $map[$meta->name][0])
                                                                    .  '&pos=0&session_max_rows=' . $session_max_rows . '&dontlimitchars=' . $dontlimitchars
                                                                    .  '&sql_query=' . urlencode('SELECT * FROM ' . PMA_backquote($map[$meta->name][0]) . ' WHERE ' . PMA_backquote($map[$meta->name][1]) . ' = ' . $row[$pointer]) . '"' . $title . '>'
-                                                                   .  ($transform_function != $default_function ? $transform_function($row[$pointer], $transform_options) : $transform_function($row[$pointer])) . '</a>';
+                                                                   .  ($transform_function != $default_function ? $transform_function($row[$pointer], $transform_options, $meta) : $transform_function($row[$pointer], array(), $meta)) . '</a>';
                         } else {
-                            $vertical_display['data'][$row_no][$i] .= ($transform_function != $default_function ? $transform_function($row[$pointer], $transform_options) : $transform_function($row[$pointer]));
+                            $vertical_display['data'][$row_no][$i] .= ($transform_function != $default_function ? $transform_function($row[$pointer], $transform_options, $meta) : $transform_function($row[$pointer], array(), $meta));
                         }
                         $vertical_display['data'][$row_no][$i]     .= '</td>' . "\n";
                     } else {
@@ -1341,7 +1340,7 @@ if (!defined('PMA_DISPLAY_TBL_LIB_INCLUDED')) {
                         }
 
                         $blobtext .= ']';
-                        $blobtext = ($default_function != $transform_function ? $transform_function($blobtext, $transform_options) : $default_function($blobtext));
+                        $blobtext = ($default_function != $transform_function ? $transform_function($blobtext, $transform_options, $meta) : $default_function($blobtext, array(), $meta));
 
                         $vertical_display['data'][$row_no][$i]      = '    <td align="center" ' . $column_style . ' valign="top" bgcolor="' . $bgcolor . '">' . $blobtext . '</td>';
                     } else {
@@ -1356,7 +1355,7 @@ if (!defined('PMA_DISPLAY_TBL_LIB_INCLUDED')) {
                             }
                             // loic1: displays all space characters, 4 space
                             // characters for tabulations and <cr>/<lf>
-                            $row[$pointer]     = ($default_function != $transform_function ? $transform_function($row[$pointer], $transform_options) : $default_function($row[$pointer]));
+                            $row[$pointer]     = ($default_function != $transform_function ? $transform_function($row[$pointer], $transform_options, $meta) : $default_function($row[$pointer], array(), $meta));
 
                             $vertical_display['data'][$row_no][$i] = '    <td valign="top" ' . $column_style . ' bgcolor="' . $bgcolor . '">' . $row[$pointer] . '</td>' . "\n";
                         } else {
@@ -1385,12 +1384,12 @@ if (!defined('PMA_DISPLAY_TBL_LIB_INCLUDED')) {
                             $row[$pointer]     = str_replace("\x0a", '\n', $row[$pointer]);
                             $row[$pointer]     = str_replace("\x0d", '\r', $row[$pointer]);
                             $row[$pointer]     = str_replace("\x1a", '\Z', $row[$pointer]);
-                            $row[$pointer]     = ($default_function != $transform_function ? $transform_function('BLOB', $transform_options) : $default_function($row[$pointer]));
+                            $row[$pointer]     = ($default_function != $transform_function ? $transform_function($row[$pointer], $transform_options, $meta) : $default_function($row[$pointer], array(), $meta));
                         }
                         // loic1: displays all space characters, 4 space
                         // characters for tabulations and <cr>/<lf>
                         else {
-                            $row[$pointer]     = ($default_function != $transform_function ? $transform_function($row[$pointer], $transform_options) : $default_function($row[$pointer]));
+                            $row[$pointer]     = ($default_function != $transform_function ? $transform_function($row[$pointer], $transform_options, $meta) : $default_function($row[$pointer], array(), $meta));
                         }
 
                         // garvin: transform functions may enable nowrapping:

libraries/transformations/README

@@ -1,187 +1,4 @@
 TRANSFORMATION USAGE (Garvin Hicking, <me@supergarv.de>)
 ====================
 
-1. What are transformations?
+See the Documentation.html for complete instructions on how to use transformation plugins.
-----------------------------
-
-You can apply different transformations to the contents of each field. The transformation will take the content
-of each field and transform it with certain rules defined in the selected transformation.
-
-Say you have a field 'filename' which contains a filename. Normale you would see in phpMyAdmin only this filename.
-Using transformations you can transform that filename into a html link, so you can click inside of the phpMyAdmin
-structure on the field's link and will see the file displayed in a new browser window. Using transformation
-options you can also specify strings to append/prepend to a string or the format you want the output stored in.
-
-For a general overview of all available transformations and their options, you can consult your 
-
-http://<your phpMyAdmin installation>/libraries/transformations/overview.php
-
-
-2. How to use transformations
------------------------------
-
-Go to your tbl_properties.inc.php3 page (like reached through clicking on the 'properties' link for a table).
-There you will see three new fields at the end of the line. They are called 'MIME-type', 'Browser transformation'
-and 'Transformation options'.
-
-
-* The field 'MIME-type' is a dropdown field. You have the options to leave that field empty or to use
-'auto' [this feature is not yet available]. Please note that transformations are inactive as long as no
-mimetype is selected.
-
-
-* The field 'Browser transformation' is a dropdown field. You can choose from a hopefully growing amount
-of pre-defined transformations. See below for information how to build your own transformation.
-
-There are global transformations and mimetype-bound transformations. Global transformations can be used
-for any mimetype. They will take the mimetype, if neccessary, into regard. Mimetype-bound transformations
-usually only operate on a certain mimetype. There are transformations which operate on the main mimetype
-(like 'image'), which will most likely take the subtype into regard, and those who only operate on a 
-specific subtype (like 'image/jpeg').
-
-You can use transformations on mimetypes for which the function was not defined for. There is no security
-check for you selected the right transformation, so take care of what the output will be like.
-
-* The field 'Transformation options' is a free-type textfield. You have to enter transform-function specific
-options here. Usually the transforms can operate with default options, but it is generally a good idea
-to look up the overview to see which options are neccessary.
-
-Much like the ENUM/SET-Fields, you have to split up several options using the format 'a','b','c',...
-(NOTE THE MISSING BLANKS). This is because internally the options will be parsed as an array, leaving
-the first value the first element in the array, and so forth.
-
-If you want to specify a MIME charset you can define it in the transformation_options. You have to
-put that outside of the pre-defined options of the specific mime-transform, as the last value of
-the set. Use the format "'; charset=XXX'". If you use a transform, for which you can specify 2
-options and you want to append a charset, enter "'first parameter','second parameter','charset=us-ascii'".
-You can, however use the defaults for the parameters: "'','','charset=us-ascii'".
-
-3. Basic file structure 
-------------------------
-
-All mimetypes and their transformations are defined through single files in the directory
-'libraries/transformations/'.
-
-They are stored in files to ease up customization and easy adding of new transformations.
-
-Because the user cannot enter own mimetypes, it is kept sure that transformations always work. It makes
-no sense to apply a transformation to a mimetype, the transform-function doesn't know to handle.
-
-One can, however, use empty mime-types and global transformations which should work for many mimetypes.
-You can also use transforms on a different mimetype they where built for, but pay attention to option
-usage as well as what the transformation does to your field.
-
-All transformation functions are kept in the directory 'libraries/transformations'.
-
-There is a basic file called 'global.inc.php3'. This function can be included by any other transform
-function and provides some basic functions.
-
-There are X possible file names:
-
-3.1 
-    A mimetype+subtype transform:
-    
-    <mimetype>_<subtype>__<transform>.inc.php3
-    
-    Please not that mimetype and subtype are seperated via '_', which shall not be contained in their names.
-    The transform function/filename may contain only characters which cause no problems in the file system as well
-    as the PHP function naming convention.
-    
-    The transform function will the be called 'PMA_transform_<mimetype>_<subtype>__<transform>()'.
-    
-    Example:
-    
-    text_html__formatted.inc.php3
-    PMA_transform_text_html__formatted()
-
-3.2
-    A mimetype (w/o subtype) transform:
-    
-    <mimetype>__<transform>.inc.php3
-    
-    Please note that there are no single '_' characters.
-    The transform function/filename may contain only characters which cause no problems in the file system as well
-    as the PHP function naming convention.
-
-    The transform function will the be called 'PMA_transform_<mimetype>__<transform>()'.
-    
-    Example:
-    
-    text__formatted.inc.php3
-    PMA_transform_text__formatted()
-
-3.3
-    A mimetype+subtype without specific transform function
-    
-    <mimetype>_<subtype>.inc.php3
-    
-    Please note that there are no '__' characters in the filename. Do not use special characters in the filename
-    causing problems with the file system.
-    
-    No transformation function is defined in the file itself.
-    
-    Example:
-    
-    text_plain.inc.php3
-    (No function)
-
-3.4
-    A mimetype (w/o subtype) without specific transform function
-    
-    <mimetype>.inc.php3
-    
-    Please note that there are no '_' characters in the filename. Do not use special characters in the filename
-    causing problems with the file system.
-    
-    No transformation function is defined in the file itself.
-    
-    Example:
-    
-    text.inc.php3
-    (No function)
-    
-3.5
-    A global transform function with no specific mimetype
-    
-    global__<transform>.inc.php3
-    
-    The transform function will the be called 'PMA_transform_global__<transform>()'.
-    
-    Example:
-    
-    global__formatted
-    PMA_transform_global__formatted()
-    
-
-So generally use '_' to split up mimetype and subtype, and '__' to provide a transform function.
-
-All filenames containing no '__' in themselves are not shown as valid transform functions in the dropdown.
-
-Please see the TEMPLATE file for adding your own transform function. See the TEMPLATE_MIMETYPE for adding
-a mimetype without a transform function. Also note the introduction of a function description in the language
-files. For each function a $strTransformation_<filename without .inc.php3> has to exist.
-
-You can use the template generator (see 5) to generate new functions and entries in the language file.
-
-
-4. FAQ
--------
-
-4.1 
-    Q: I can't enter my own mimetype! WTF is this feature then useful for?
-    
-    A: Slow down :). Defining mimetypes is of no use, if you can't put transformations on them.
-       Otherwise you could just put a comment on the field. Because entering your own mimetype will
-       cause serious syntax checking issues and validation, this introduces a high-risk false-user-input
-       situation. Instead you have to initialize mimetypes using functions or empty mimetype definitions.
-       
-       Plus, you have a whole overview of available mimetypes. Who knows all those mimetypes by heart so
-       he/she can enter it at will?
-       
-       
-5. Template Generator
-----------------------
-
-To create a new transform function please see template_generator.sh.
-
-To create a new, empty mimetype please see template_generator_mimetype.sh.

libraries/transformations/TEMPLATE

@@ -6,21 +6,24 @@
  * Plugin function TEMPLATE (Garvin Hicking).
  * -----------------------------------------
  *
- * For instructions, read the libraries/transformations/README file.
+ * For instructions, read the /Documentation.html file.
  *
- * The string ENTER_FILENAME_HERE shall be substituted with the filename without the '.inc.php3'
+ * The string ENTER_FILENAME_HERE shall be substituted with the filename without the '.inc.php'
- * extension. For further information regarding naming conventions see the README file.
+ * extension. For further information regarding naming conventions see the /Documentation.html file.
  */
 
 if (!defined('PMA_TRANSFORMATION_[ENTER_FILENAME_HERE]')){
     define('PMA_TRANSFORMATION_[ENTER_FILENAME_HERE]', 1);
 
-    function PMA_transformation_[enter_filename_here]($buffer, $options = array()) {
+    function PMA_transformation_[enter_filename_here]($buffer, $options = array(), $meta = '') {
         // possibly use a global transform and feed it with special options:
         // include('./libraries/transformations/global.inc.php3');
 
         // further operations on $buffer using the $options[] array.
 
+        // You can evaluate the propagated $meta Object. It's contained fields are described in http://www.php.net/mysql_fetch_field.
+        // This stored information can be used to get the field information about the transformed field.
+
         return $buffer;
     }
 }

libraries/transformations/global.inc.php3

@@ -26,15 +26,15 @@
 if (!defined('PMA_TRANSFORMATION_LIB_GLOBAL')){
     define('PMA_TRANSFORMATION_LIB_GLOBAL', 1);
 
-    function PMA_transformation_global_plain($buffer, $options = array()) {
+    function PMA_transformation_global_plain($buffer, $options = array(), $meta = '') {
         return htmlspecialchars($buffer);
     }
 
-    function PMA_transformation_global_html($buffer, $options = array()) {
+    function PMA_transformation_global_html($buffer, $options = array(), $meta = '') {
         return $buffer;
     }
 
-    function PMA_transformation_global_html_replace($buffer, $options = array()) {
+    function PMA_transformation_global_html_replace($buffer, $options = array(), $meta = '') {
         if (!isset($options['string'])) {
             $options['string'] = '';
         }

libraries/transformations/image_jpeg__inline.inc.php3

@@ -5,7 +5,7 @@
 if (!defined('PMA_TRANSFORMATION_IMAGE_JPEG__INLINE')){
     define('PMA_TRANSFORMATION_IMAGE_JPEG__INLINE', 1);
 
-    function PMA_transformation_image_jpeg__inline($buffer, $options = array()) {
+    function PMA_transformation_image_jpeg__inline($buffer, $options = array(), $meta = '') {
         include('./libraries/transformations/global.inc.php3');
 
         if (PMA_IS_GD2) {

libraries/transformations/image_jpeg__link.inc.php3

@@ -5,7 +5,7 @@
 if (!defined('PMA_TRANSFORMATION_IMAGE_JPEG__LINK')){
     define('PMA_TRANSFORMATION_IMAGE_JPEG__LINK', 1);
 
-    function PMA_transformation_image_jpeg__link($buffer, $options = array()) {
+    function PMA_transformation_image_jpeg__link($buffer, $options = array(), $meta = '') {
         include('./libraries/transformations/global.inc.php3');
 
         $transform_options = array ('string' => '<a href="transformation_wrapper.php3' . $options['wrapper_link'] . '" alt="[__BUFFER__]">[BLOB]</a>');

libraries/transformations/image_png__inline.inc.php3

@@ -5,7 +5,7 @@
 if (!defined('PMA_TRANSFORMATION_IMAGE_PNG__INLINE')){
     define('PMA_TRANSFORMATION_IMAGE_PNG__INLINE', 1);
 
-    function PMA_transformation_image_png__inline($buffer, $options = array()) {
+    function PMA_transformation_image_png__inline($buffer, $options = array(), $meta = '') {
         include('./libraries/transformations/global.inc.php3');
 
         if (PMA_IS_GD2) {

libraries/transformations/text_plain__dateformat.inc.php3

@@ -2,20 +2,10 @@
 /* $Id$ */
 // vim: expandtab sw=4 ts=4 sts=4:
 
-/**
- * Plugin function TEMPLATE (Garvin Hicking).
- * -----------------------------------------
- *
- * For instructions, read the libraries/transformations/README file.
- *
- * The string ENTER_FILENAME_HERE shall be substituted with the filename without the '.inc.php'
- * extension. For further information regarding naming conventions see the README file.
- */
-
 if (!defined('PMA_TRANSFORMATION_TEXT_PLAIN__DATEFORMAT')){
     define('PMA_TRANSFORMATION_TEXT_PLAIN__DATEFORMAT', 1);
 
-    function PMA_transformation_text_plain__dateformat($buffer, $options = array()) {
+    function PMA_transformation_text_plain__dateformat($buffer, $options = array(), $meta = '') {
         // possibly use a global transform and feed it with special options:
         // include('./libraries/transformations/global.inc.php');
 

libraries/transformations/text_plain__external.inc.php3

@@ -2,16 +2,6 @@
 /* $Id$ */
 // vim: expandtab sw=4 ts=4 sts=4:
 
-/**
- * Plugin function TEMPLATE (Garvin Hicking).
- * -----------------------------------------
- *
- * For instructions, read the libraries/transformations/README file.
- *
- * The string ENTER_FILENAME_HERE shall be substituted with the filename without the '.inc.php3'
- * extension. For further information regarding naming conventions see the README file.
- */
-
 if (!defined('PMA_TRANSFORMATION_TEXT_PLAIN__EXTERNAL')){
     define('PMA_TRANSFORMATION_TEXT_PLAIN__EXTERNAL', 1);
 
@@ -31,7 +21,7 @@ if (!defined('PMA_TRANSFORMATION_TEXT_PLAIN__EXTERNAL')){
         return $nowrap;
     }
 
-    function PMA_transformation_text_plain__external($buffer, $options = array()) {
+    function PMA_transformation_text_plain__external($buffer, $options = array(), $meta = '') {
         // possibly use a global transform and feed it with special options:
         // include('./libraries/transformations/global.inc.php3');
 

libraries/transformations/text_plain__formatted.inc.php3

@@ -5,7 +5,7 @@
 if (!defined('PMA_TRANSFORMATION_TEXT_PLAIN__FORMATTED')){
     define('PMA_TRANSFORMATION_TEXT_PLAIN__FORMATTED', 1);
 
-    function PMA_transformation_text_plain__formatted($buffer, $options = array()) {
+    function PMA_transformation_text_plain__formatted($buffer, $options = array(), $meta = '') {
         return $buffer;
     }
 }

libraries/transformations/text_plain__imagelink.inc.php3

@@ -5,7 +5,7 @@
 if (!defined('PMA_TRANSFORMATION_TEXT_PLAIN__IMAGELINK')){
     define('PMA_TRANSFORMATION_TEXT_PLAIN__IMAGELINK', 1);
 
-    function PMA_transformation_text_plain__imagelink($buffer, $options = array()) {
+    function PMA_transformation_text_plain__imagelink($buffer, $options = array(), $meta = '') {
         include('./libraries/transformations/global.inc.php3');
 
         $transform_options = array ('string' => '<a href="' . (isset($options[0]) ? $options[0] : '') . $buffer . '" target="_blank"><img src="' . (isset($options[0]) ? $options[0] : '') . $buffer . '" border="0" width="' . (isset($options[1]) ? $options[1] : 100) . '" height="' . (isset($options[2]) ? $options[2] : 50) . '">' . $buffer . '</a>');

libraries/transformations/text_plain__link.inc.php3

@@ -5,7 +5,7 @@
 if (!defined('PMA_TRANSFORMATION_TEXT_PLAIN__LINK')){
     define('PMA_TRANSFORMATION_TEXT_PLAIN__LINK', 1);
 
-    function PMA_transformation_text_plain__link($buffer, $options = array()) {
+    function PMA_transformation_text_plain__link($buffer, $options = array(), $meta = '') {
         include('./libraries/transformations/global.inc.php3');
 
 //        $transform_options = array ('string' => '<a href="' . (isset($options[0]) ? $options[0] : '') . '%1$s" title="' . (isset($options[1]) ? $options[1] : '%1$s') . '">' . (isset($options[1]) ? $options[1] : '%1$s') . '</a>');

libraries/transformations/text_plain__substr.inc.php3

@@ -2,20 +2,10 @@
 /* $Id$ */
 // vim: expandtab sw=4 ts=4 sts=4:
 
-/**
- * Plugin function TEMPLATE (Garvin Hicking).
- * -----------------------------------------
- *
- * For instructions, read the libraries/transformations/README file.
- *
- * The string ENTER_FILENAME_HERE shall be substituted with the filename without the '.inc.php3'
- * extension. For further information regarding naming conventions see the README file.
- */
-
 if (!defined('PMA_TRANSFORMATION_TEXT_PLAIN__SUBSTR')){
     define('PMA_TRANSFORMATION_TEXT_PLAIN__SUBSTR', 1);
 
-    function PMA_transformation_text_plain__substr($buffer, $options = array()) {
+    function PMA_transformation_text_plain__substr($buffer, $options = array(), $meta = '') {
         // possibly use a global transform and feed it with special options:
         // include('./libraries/transformations/global.inc.php3');