Gallery Merge Documentation:

Gallery Merge Plugin Support for Other Plugin's Data:

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:

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>

The information needed about a plugin is very simple:

• folder_name - the name of the main folder this plugin adds - no need to worry about sub-folders under it.
• 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.
• plugin_name - the name the plugin is known as in the CPG Plugins table (this may vary by language - and is used only for messages
• 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...

EXAMPLE:

  'folder_name' => array(                                                // (folder name this plugin adds)
     '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')
           'plugin_name' => '{name}',                                    // (name of plugin - may vary by language - only used in messages)
          '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:

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)