phpmyadmin/libraries/transformations/README

TRANSFORMATION USAGE (Garvin Hicking, <me@supergarv.de>)
====================

1. What are transformations?
----------------------------

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.