/**************************************************
  Coppermine 1.5.x Plugin - gallery_merge
**************************************************/

This doc is provided in html format in file readme_plugin_support.php - accessible via link on Gallery Merge Configuration Screen 
or can be directly loaded to your browser.

--------------------------------------------------------------------------------------------------------------------

 Gallery Merge Documentation:
See readme.php (or readme.txt) for documentation on main Gallery Merge Plugin.
This file describes support for Gallery Merge to process data tables from other plugins during a merge.

 

Gallery Merge Plugin Support for Other Plugin's Data:
Of course there are many plugins available for use with CPG, and many of them need consideration during Gallery Merge.
Those that add features without altering the structure of CPG tables (adding columns, etc) or without adding their own CPG tables can often be addressed just by insuring the same plugin in installed in the Target gallery.
However, those that alter the structure of CPG tables, or add their own tables, have other considerations.

Those altering structure MUST be installed in the target gallery, or our generated SQL to merge galleries will not match the structure of the Target table. (Even if SQL were generated to account for this difference - you would lose the data in the altered fields..)
Those adding their own tables may need to have that data either compared with Target or Migrated.
Plugins may also just add rows to the CPG Config table - these are typically addressed just by installed the plugin in the Target if not already there. Exceptions here will be noted in both the compare of the Config table, and the compare of installed plugins.

During Merge simulation and execution, the plugins installed in the Source galery will be matched to the Target, and our knowledge base. Exceptions will be noted. Critical exceptions (plugins missing that are known to ALTER CPG tables) will flag a warning and prevent execution.

 

Plugin Knowledge Base:
Obviously I don't know about all plugins, nor could I possibly research them all... but you can help! An interface is provided to allow easy addition of knowledge about other plugins, and where needed to add support for plugin added data tables - retaining any mappings to data in the core Coppermine tables affected by the merge.

data/plugin_data.php defines all 'known' plugins, and their impact on Gallery Merge. Plugins can be added to the array defined there to:

    Eliminate 'Unknown Plugin' Warnings during Galery Merge
    Provide correct messages for Merge impact based on what the plugin does/li>
    Provide link to script to support the merge if plugin defines it's own tables, and merge is required and supported./li> 

Adding plugins even without support provided assists in providing proper impact assessment during Gallery Merge.

The information needed about a plugin is very simple:

    plugin_name - the name the plugin is known as in the CPG Plugins table
    alters_cpg_tables - TRUE or FALSE - If the plugin ALTERS the structure of CPG core tables, set to TRUE
    adds_tables - TRUE or FALSE - If the plugin adds it's own data tables, set to TRUE
    table_pattern - a pattern to match for this plugin's tables NOT including the CPG table prefix
    standard_folders - TRUE or FALSE - if the plugin uses the standard location in the Plugins folder for its source, set to TRUE
    some older mods add a folder to the main CPG root - this helps us correctly respond to a mismatch in folders during file compare.
    folder_name - the name of the main folder this plugin adds - no need to worry about sub-folders under it.
    merge_script - IF support is provided, the name of the script to include to provide the additional definitions/support
    suggested name is merge_plugin_{pluginfoldername}
    pid_sql - If merge script translation will require picture (pid) information, provide SQL to generate set of PIDs that we care about...
    Only required PIDs are mapped to conserve memory. in SQL use {cpg_table_prefix} to represent prefix...

Data can be added to 'plugins/gallery_merge/data/plugin_data.php'. Please let me know about plugins you research and add, so I can update the distribution for the next person...

 

EXAMPLE:

  'plugin_name' => array(
     'alters_cpg_tables' => {TRUE|FALSE|unknown},                        // (changes CPG base tables STRUCTURES - adding columns, etc)
           'adds_tables' => {TRUE|FALSE|unknown},                        // (adds any new tables)
         'table_pattern' => '{pattern}',                                 // (patten to match for this plugins tables (that follows cpg table prefix)
      'standard_folders' => {TRUE|FALSE|unknown},                        // (FALSE if folder is outside of plugins directory - should only be older 'mods')
           'folder_name' => '{name}',                                    // (folder name this plugin adds)
          'merge_script' => '{merge_plugin_{pluginfoldername}|needed|unknown|n/a}',    // (script to include if merge is supported for this table - .php suffix added of course)
                                 // ****** remaining fields only required if 'merge_script' is provided ******
                'pid_sql' => 'SELECT SQL to return list of PIDs')         // If merge script translation will require picture (pid) information, provide SQL to generate a result
                                                                          // set of PIDs that we care about...  Only required PIDs are mapped to conserve memory
                                                                          // in SQL use {cpg_table_prefix} to represent prefix...

 

Plugin Merge Scripts:
For those plugins adding their own tables, the mapping and processing already part of Gallery Merge can be used to support these tables, and where needed - custom code can be provided - but many will be able to be handled with just a little research and some parameter settings.

A skeleton is provided to clone for each supported plugin - start with 'plugins/gallery_merge/merge_plugin_skeleton.php' which contains an example of each type of process.
Completed files should be named merge_plugin_{pluginfoldername}.php

When to use this script:

    If a Plugin does NOT create it's own data tables, this script is not needed.
    This is intended to support merge of plugin defined tables - taking advantage of the mapping already done by gallery merge, and extending those capabilities to a plugin's tables.
    In defining the support for Coppermine's core tables, a range of cases can be easily handled for plugin tables.

 

Parameters:

    plugin_name - name as it appears in cpg_plugins table and data/plugin_data.php
    plugin_table_array - array with an entry for each table the plugin adds.
        table_suffix - table name that follows the cpg table prefix
        process_type - Define the function to be use to process this table
            process_table - full mapping and insert support - requires additional fields below to be defined
            if 'pre_merge_function' is specified, it will be called before normal processing
            if 'post_merge_function' is specified, it will be called following normal processing
            compare_values - onfig table with name/value columns only - compare data and report missing fields or unmatched values
            field names can be provided to match table definiton
            transient - data not required - could be logs, session info, or other data that doesn't need to carry forward
            static - data doesn't change except with maint - compare row counts only
            unsupported - data not migrated - compare row counts only
            custom - invoke function(s) specified in 'pre_merge_function' and/or 'post_merge_function' to process this table
    Fields for 'compare_values'
        compare_name_column - the name of the table column containing the variable names
        compare_value_column - the name of the table column containing the variable contents
    Fields for 'process_table'
        table_key - the key field name for this table - if there is no key field, spcify '*none*'
        order_by - by default, the table will be processed in key field sequence - if another order is required to see data in correct order, specify here
        For example - in processing cpg_categories, we want to process parent categories before children - and not in order entered.
        VALUES:
            null - use default
            orderby = 'ORDER BY field1, field2, field3'
        compare_fields - the field name(s) - comma separated - to use to determine if row already exists in target - or if it will be inserted
        compare_type - type of compare to perform
            UNIQUE = only insert unique records based on compare fields above.
            INSERT = insert all records - report duplicates based on compare fields above. (no unique indexes to stop duplicates)
            IGNORE = process table with INSERT IGNORE - no comparison needed, no duplicate processing needed
        If merging of data in some form is needed - then special code will be required to handle.
        skip_keys - set keys/columns to bypass for insert (typically auto-increment fields) These will be excluded from the generated INSERT statements
        zero_keys - set keys/columns to 0 value on insert (typically data not yet available... to be updated later)
        map_values - array of column names to map - *IF* mapping is required for this table...
        Mapping is ONLY required if later plugin tables need to translate data (like related key fields in this table) for INSERTs array contains column names to map.
        Column name beginning with / is for doc purposes only - only source field (after / is stripped) is saved to make array more 'human readable'
        The key field of the table will be mapped automatically - it does not need to be specified
        EXAMPLE: array('/title', 'thumb')
        skip_keys_difference - array of column names to bypass when comparing rows in source and target
        Typically used to eliminate 'differences' messages for fields we know will be different... keys we know will change or be translated, last accessed timestamps, etc
        EXAMPLE: array('aid', 'thumb')
        translations - array to request remapping of fields to new values - the workhorse of the process
        Defined as: fieldname => table.keyvalue.field{.condition} to use
            fieldname - column from this table to translate - or fieldname.suffix if providing conditions
            table - mapping table suffix to use
            keyvalue - key to mapping array to lookup
            field - field from mapping array to translate to. if prefixed with incr_ - adds the requested value rather than assigning...
            condition - {optional} specified as fieldname=value - only perform the requested mapping if condition field name = condition value.
            used in cases where a translation depends on contents of another field..
        MAPS AVAILABLE:
        Each name including key represents a pair of entries to map from source to target
            usergroups - key: 'group_id'
            users - key: 'user_id'
            categories - key: 'cid' - Additional Fields: 'pos', 'thumb', 'depth'
            albums - key: 'aid' - Additional Fields: 'thumb'
            pictures - key: 'pid'
            if mapping on pictures... to save memory, not all pid's are added to mapping array - only those which we care about..
    Fields for 'custom' - and optional for 'process_table':
    If none of the opions above will work for your plugin's tables - then you can provide your own functions to handle the data (process_type of 'custom') or combine the 'process_table' options with your own functions to 'tweak' the data. Ability to call a function either (or both) before or after the normal processing (custom can use either or both - nothing happens in between...)
        pre_merge_function - name of function to call prior to executing normal merge processing can be existing cpg, gallery_merge plugin, or custom function defined in merge_plugin_{foldername}.php
        post_merge_function - name of function to call following execution of normal merge processing
        can be existing cpg, gallery_merge plugin, or custom function defined in merge_plugin_{foldername}.php

 

EXAMPLE:

   'table_suffix' => array(                                                        // table name that follows the cpg table prefix
            'process_type' => '{process_table|compare_values|transient|static|custom}',  // see detail above
                              // ****** following fields only required if 'process_type' = 'compare_values' ******
     'compare_name_column' => 'name',                                             // name of column containing the variable names
    'compare_value_column' => 'value',                                            // name of the column containing the variable setting
                              // ****** following fields only required if 'process_type' = 'process_table' or 'custom' ******
               'table_key' => 'aid',                                              // key field name
                 'orderby' => '';                                                 // order by key field is default to assist restart - override here if needed
          'compare_fields' => 'title';                                            // field(s) - comma separated - to match source to target (identify duplicates/inserts)
            'compare_type' => '';                                                 // type of compare: UNIQUE, IGNORE, MERGE
               'skip_keys' => array('aid');                                       // set keys/columns to bypass for insert (typically auto-increment fields)
               'zero_keys' => array('thumb');                                     // set keys/columns to 0 value on insert (typically data not yet available... to be updated later)
              'map_values' => array('/title', 'thumb');                           // set mapping values to set fields to build array for later processing
    'skip_keys_difference' => array('aid', 'thumb');                              // set keys to bypass for comparing like rows in source and target (like passwords...)
            'translations' => array('visibility' => 'usergroups.visibility.group_id', // <- translate 'visibility' field using usergroups mapping, visibility as key, and set to target group_id
                                    'owner' => 'users.owner.user_id',                 // <- translate 'owner' fied using users mapping, owner as key, and set to target user_id
                                    'pos' => 'categories.category.incr_subalbum_pos', // <- translate 'pos' field using categories mapping, category as key, and ADD the subalbum_pos to current pos value
                                    'conid.1' => 'categories.conid.cid.type=0',       // <- translate 'conid' field using categories mapping, conid as key, and set to target cid - ONLY IF type = 0
                                    'conid.2' => 'albums.conid.aid.type=1',           //    (the suffix following translate field (.1, .2, etc) are ignored - they can be any character or string to make array key unique)
                                    'conid.3' => 'pictures.conid.pid.type=2'), );  // set translations to be done... fieldname => table.keyvalue.field to use
                              // ****** following fields (at least one) only required if 'process_type' = 'custom' - Optional for 'process_type = 'process_table' ******
      'pre_merge_function' => ''                                                  // function to call before execution of merge script... (process types of 'process_table' and 'custom' only)
     'post_merge_function' => ''                                                  // function to call following execution of merge script... (process types of 'process_table' and 'custom' only)

 

Congratulations again if you made it through all of this! And good luck merging galleries!!
Your comments are welcome.
I hope you find this useful.
Greg (gmc on the CPG forum) 