doc/transformations.rst

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