libraries/transformations/README

   1 TRANSFORMATION USAGE (Garvin Hicking, <me@supergarv.de>)
   2 ====================
   3
   4 1. What are transformations?
   5 ----------------------------
   6
   7 You can apply different transformations to the contents of each field. The transformation will take the content
   8 of each field and transform it with certain rules defined in the selected transformation.
   9
  10 Say you have a field 'filename' which contains a filename. Normale you would see in phpMyAdmin only this filename.
  11 Using transformations you can transform that filename into a html link, so you can click inside of the phpMyAdmin
  12 structure on the field's link and will see the file displayed in a new browser window. Using transformation
  13 options you can also specify strings to append/prepend to a string or the format you want the output stored in.
  14
  15 For a general overview of all available transformations and their options, you can consult your
  16
  17 http://<your phpMyAdmin installation>/libraries/transformations/overview.php
  18
  19
  20 2. How to use transformations
  21 -----------------------------
  22
  23 Go to your tbl_properties.inc.php3 page (like reached through clicking on the 'properties' link for a table).
  24 There you will see three new fields at the end of the line. They are called 'MIME-type', 'Browser transformation'
  25 and 'Transformation options'.
  26
  27
  28 * The field 'MIME-type' is a dropdown field. You have the options to leave that field empty or to use
  29 'auto' [this feature is not yet available]. Please note that transformations are inactive as long as no
  30 mimetype is selected.
  31
  32
  33 * The field 'Browser transformation' is a dropdown field. You can choose from a hopefully growing amount
  34 of pre-defined transformations. See below for information how to build your own transformation.
  35
  36 There are global transformations and mimetype-bound transformations. Global transformations can be used
  37 for any mimetype. They will take the mimetype, if neccessary, into regard. Mimetype-bound transformations
  38 usually only operate on a certain mimetype. There are transformations which operate on the main mimetype
  39 (like 'image'), which will most likely take the subtype into regard, and those who only operate on a
  40 specific subtype (like 'image/jpeg').
  41
  42 You can use transformations on mimetypes for which the function was not defined for. There is no security
  43 check for you selected the right transformation, so take care of what the output will be like.
  44
  45 * The field 'Transformation options' is a free-type textfield. You have to enter transform-function specific
  46 options here. Usually the transforms can operate with default options, but it is generally a good idea
  47 to look up the overview to see which options are neccessary.
  48
  49 Much like the ENUM/SET-Fields, you have to split up several options using the format 'a','b','c',...
  50 (NOTE THE MISSING BLANKS). This is because internally the options will be parsed as an array, leaving
  51 the first value the first element in the array, and so forth.
  52
  53 If you want to specify a MIME charset you can define it in the transformation_options. You have to
  54 put that outside of the pre-defined options of the specific mime-transform, as the last value of
  55 the set. Use the format "'; charset=XXX'". If you use a transform, for which you can specify 2
  56 options and you want to append a charset, enter "'first parameter','second parameter','charset=us-ascii'".
  57 You can, however use the defaults for the parameters: "'','','charset=us-ascii'".
  58
  59 3. Basic file structure
  60 ------------------------
  61
  62 All mimetypes and their transformations are defined through single files in the directory
  63 'libraries/transformations/'.
  64
  65 They are stored in files to ease up customization and easy adding of new transformations.
  66
  67 Because the user cannot enter own mimetypes, it is kept sure that transformations always work. It makes
  68 no sense to apply a transformation to a mimetype, the transform-function doesn't know to handle.
  69
  70 One can, however, use empty mime-types and global transformations which should work for many mimetypes.
  71 You can also use transforms on a different mimetype they where built for, but pay attention to option
  72 usage as well as what the transformation does to your field.
  73
  74 All transformation functions are kept in the directory 'libraries/transformations'.
  75
  76 There is a basic file called 'global.inc.php3'. This function can be included by any other transform
  77 function and provides some basic functions.
  78
  79 There are X possible file names:
  80
  81 3.1
  82     A mimetype+subtype transform:
  83
  84     <mimetype>_<subtype>__<transform>.inc.php3
  85
  86     Please not that mimetype and subtype are seperated via '_', which shall not be contained in their names.
  87     The transform function/filename may contain only characters which cause no problems in the file system as well
  88     as the PHP function naming convention.
  89
  90     The transform function will the be called 'PMA_transform_<mimetype>_<subtype>__<transform>()'.
  91
  92     Example:
  93
  94     text_html__formatted.inc.php3
  95     PMA_transform_text_html__formatted()
  96
  97 3.2
  98     A mimetype (w/o subtype) transform:
  99
 100     <mimetype>__<transform>.inc.php3
 101
 102     Please note that there are no single '_' characters.
 103     The transform function/filename may contain only characters which cause no problems in the file system as well
 104     as the PHP function naming convention.
 105
 106     The transform function will the be called 'PMA_transform_<mimetype>__<transform>()'.
 107
 108     Example:
 109
 110     text__formatted.inc.php3
 111     PMA_transform_text__formatted()
 112
 113 3.3
 114     A mimetype+subtype without specific transform function
 115
 116     <mimetype>_<subtype>.inc.php3
 117
 118     Please note that there are no '__' characters in the filename. Do not use special characters in the filename
 119     causing problems with the file system.
 120
 121     No transformation function is defined in the file itself.
 122
 123     Example:
 124
 125     text_plain.inc.php3
 126     (No function)
 127
 128 3.4
 129     A mimetype (w/o subtype) without specific transform function
 130
 131     <mimetype>.inc.php3
 132
 133     Please note that there are no '_' characters in the filename. Do not use special characters in the filename
 134     causing problems with the file system.
 135
 136     No transformation function is defined in the file itself.
 137
 138     Example:
 139
 140     text.inc.php3
 141     (No function)
 142
 143 3.5
 144     A global transform function with no specific mimetype
 145
 146     global__<transform>.inc.php3
 147
 148     The transform function will the be called 'PMA_transform_global__<transform>()'.
 149
 150     Example:
 151
 152     global__formatted
 153     PMA_transform_global__formatted()
 154
 155
 156 So generally use '_' to split up mimetype and subtype, and '__' to provide a transform function.
 157
 158 All filenames containing no '__' in themselves are not shown as valid transform functions in the dropdown.
 159
 160 Please see the TEMPLATE file for adding your own transform function. See the TEMPLATE_MIMETYPE for adding
 161 a mimetype without a transform function. Also note the introduction of a function description in the language
 162 files. For each function a $strTransformation_<filename without .inc.php3> has to exist.
 163
 164 You can use the template generator (see 5) to generate new functions and entries in the language file.
 165
 166
 167 4. FAQ
 168 -------
 169
 170 4.1
 171     Q: I can't enter my own mimetype! WTF is this feature then useful for?
 172
 173     A: Slow down :). Defining mimetypes is of no use, if you can't put transformations on them.
 174        Otherwise you could just put a comment on the field. Because entering your own mimetype will
 175        cause serious syntax checking issues and validation, this introduces a high-risk false-user-input
 176        situation. Instead you have to initialize mimetypes using functions or empty mimetype definitions.
 177
 178        Plus, you have a whole overview of available mimetypes. Who knows all those mimetypes by heart so
 179        he/she can enter it at will?
 180
 181
 182 5. Template Generator
 183 ----------------------
 184
 185 To create a new transform function please see template_generator.sh.
 186
 187 To create a new, empty mimetype please see template_generator_mimetype.sh.