phpmyadmin/doc/transformations.rst

   1 .. _transformations:
   2
   3 Transformations
   4 ===============
   5
   6 .. _transformationsintro:
   7
   8 Introduction
   9 ++++++++++++
  10
  11 To enable transformations, you have to setup the ``column_info``
  12 table and the proper directives. Please see the :ref:`config` on how to do so.
  13
  14 You can apply different transformations to the contents of each
  15 column. The transformation will take the content of each column and
  16 transform it with certain rules defined in the selected
  17 transformation.
  18
  19 Say you have a column 'filename' which contains a filename. Normally
  20 you would see in phpMyAdmin only this filename. Using transformations
  21 you can transform that filename into a HTML link, so you can click
  22 inside of the phpMyAdmin structure on the column's link and will see
  23 the file displayed in a new browser window. Using transformation
  24 options you can also specify strings to append/prepend to a string or
  25 the format you want the output stored in.
  26
  27 For a general overview of all available transformations and their
  28 options, you can consult your *<www.your-host.com>/<your-install-
  29 dir>/transformation\_overview.php* installation.
  30
  31 For a tutorial on how to effectively use transformations, see our
  32 `Link section <http://www.phpmyadmin.net/home_page/docs.php>`_ on the
  33 official phpMyAdmin homepage.
  34
  35 .. _transformationshowto:
  36
  37 Usage
  38 +++++
  39
  40 Go to your *tbl\_structure.php* page (i.e. reached through clicking on
  41 the 'Structure' link for a table). There click on "Change" (or change
  42 icon) and there you will see three new fields at the end of the line.
  43 They are called 'MIME-type', 'Browser transformation' and
  44 'Transformation options'.
  45
  46 * The field 'MIME-type' is a drop-down field. Select the MIME-type that
  47   corresponds to the column's contents. Please note that transformations
  48   are inactive as long as no MIME-type is selected.
  49 * The field 'Browser transformation' is a drop-down field. You can
  50   choose from a hopefully growing amount of pre-defined transformations.
  51   See below for information on how to build your own transformation.
  52   There are global transformations and mimetype-bound transformations.
  53   Global transformations can be used for any mimetype. They will take
  54   the mimetype, if necessary, into regard. Mimetype-bound
  55   transformations usually only operate on a certain mimetype. There are
  56   transformations which operate on the main mimetype (like 'image'),
  57   which will most likely take the subtype into regard, and those who
  58   only operate on a specific subtype (like 'image/jpeg'). You can use
  59   transformations on mimetypes for which the function was not defined
  60   for. There is no security check for you selected the right
  61   transformation, so take care of what the output will be like.
  62 * The field 'Transformation options' is a free-type textfield. You have
  63   to enter transform-function specific options here. Usually the
  64   transforms can operate with default options, but it is generally a
  65   good idea to look up the overview to see which options are necessary.
  66   Much like the ENUM/SET-Fields, you have to split up several options
  67   using the format 'a','b','c',...(NOTE THE MISSING BLANKS). This is
  68   because internally the options will be parsed as an array, leaving the
  69   first value the first element in the array, and so forth. If you want
  70   to specify a MIME character set you can define it in the
  71   transformation\_options. You have to put that outside of the pre-
  72   defined options of the specific mime-transform, as the last value of
  73   the set. Use the format "'; charset=XXX'". If you use a transform, for
  74   which you can specify 2 options and you want to append a character
  75   set, enter "'first parameter','second parameter','charset=us-ascii'".
  76   You can, however use the defaults for the parameters: "'','','charset
  77   =us-ascii'".
  78
  79 .. _transformationsfiles:
  80
  81 File structure
  82 ++++++++++++++
  83
  84 All specific transformations for mimetypes are defined through class
  85 files in the directory 'libraries/plugins/transformations/'. Each of
  86 them extends a certain transformation abstract class declared in
  87 libraries/plugins/transformations/abstract.
  88
  89 They are stored in files to ease up customization and easy adding of
  90 new transformations.
  91
  92 Because the user cannot enter own mimetypes, it is kept sure that
  93 transformations always work. It makes no sense to apply a
  94 transformation to a mimetype the transform-function doesn't know to
  95 handle.
  96
  97 There is a file called '*transformations.lib.php*' that provides some
  98 basic functions which can be included by any other transform function.
  99
 100 The file name convention is ``[Mimetype]_[Subtype]_[Transformation
 101 Name].class.php``, while the abtract class that it extends has the
 102 name ``[Transformation Name]TransformationsPlugin``. All of the
 103 methods that have to be implemented by a transformations plug-in are:
 104
 105 #. getMIMEType() and getMIMESubtype() in the main class;
 106 #. getName(), getInfo() and applyTransformation() in the abstract class
 107    it extends.
 108
 109 The getMIMEType(), getMIMESubtype() and getName() methods return the
 110 name of the MIME type, MIME Subtype and transformation accordingly.
 111 getInfo() returns the transformation's description and possible
 112 options it may receive and applyTransformation() is the method that
 113 does the actual work of the transformation plug-in.
 114
 115 Please see the libraries/plugins/transformations/TEMPLATE and
 116 libraries/plugins/transformations/TEMPLATE\_ABSTRACT files for adding
 117 your own transformation plug-in. You can also generate a new
 118 transformation plug-in (with or without the abstract transformation
 119 class), by using
 120 :file:`libraries/plugins/transformations/generator_plugin.sh` or
 121 :file:`libraries/plugins/transformations/generator_main_class.sh`.
 122
 123 The applyTransformation() method always gets passed three variables:
 124
 125 #. **$buffer** - Contains the text inside of the column. This is the
 126    text, you want to transform.
 127 #. **$options** - Contains any user-passed options to a transform
 128    function as an array.
 129 #. **$meta** - Contains an object with information about your column. The
 130    data is drawn from the output of the `mysql\_fetch\_field()
 131    <http://www.php.net/mysql_fetch_field>`_ function. This means, all
 132    object properties described on the `manual page
 133    <http://www.php.net/mysql_fetch_field>`_ are available in this
 134    variable and can be used to transform a column accordingly to
 135    unsigned/zerofill/not\_null/... properties. The $meta->mimetype
 136    variable contains the original MIME-type of the column (i.e.
 137    'text/plain', 'image/jpeg' etc.)
 138