[Summary view] [Print] [Text view]

   1  // $Id: README.txt,v 1.1.2.2 2008/11/22 04:51:59 aland Exp $
   2  
   3  This module provides two new form elements to assist with files that are stored/updated in Drupal's {files} table.
   4  
   5  This module was programmed by Alan Davison @ www.caignwebs.com.au
   6  
   7  
   8  Dependencies
   9  ------------
  10   * none
  11   
  12  Optimal integration
  13  -------------------
  14   * Image Cache (http://drupal.org/project/imagecache)
  15     This module allows integration with Image Cache when saving
  16     uploaded files.
  17  
  18  Install
  19  -------
  20  Installing the Upload Element module is simple:
  21  
  22  1) Copy the upload_element folder to the modules folder in your installation.
  23  
  24  2) Enable the module using Administer -> Modules (/admin/build/modules)
  25  
  26  Configuration for Upload Element
  27  -------------------------------
  28  
  29  No configuration is required.
  30  
  31  Contributing
  32  ------------
  33  All comments and patches welcome. Just visit the issue queue.
  34  
  35  Support
  36  -------
  37  If you experience a problem with upload element or have a problem, file a
  38  request or issue on the upload element queue at
  39  http://drupal.org/project/issues/upload_element.
  40  
  41  DO NOT POST IN THE FORUMS.
  42  
  43  Posting in the issue queues is a direct line of communication with the module authors.
  44  
  45  Usage
  46  -----
  47  The base usage can be as simple as:
  48  
  49  ## To add the element to the form
  50    $form['image'] = array(
  51      '#type' => 'image_upload_element',
  52      '#title' => t('Image'),
  53      '#default_value' => $node->image, // {files} object
  54    );
  55  
  56  ## And to handle the submission
  57  
  58    // in hook_insert or somewhere
  59    // $node->image is a {files} object
  60    // If you handle this yourself, make sure that you check
  61    // the property submit_action to see if the object has
  62    // been flagged as deleted.
  63    $image_id = 0;
  64    if($node->image) {
  65      $image_id = upload_element_save($node->image, 'dest/directory', FILE_EXISTS_RENAME, 'imagecache_preset');
  66    }
  67  
  68  
  69  Configurable settings
  70  ---------------------
  71  
  72  1) File validators
  73  
  74    These are passed to file_save_upload during "hook_value", form_type_upload_element_value.
  75    
  76    The image upload element has 'file_validate_is_image' automatically added.
  77    
  78    Both elements get 'file_validate_size' added for theming purposes. This can be overridden
  79    with a custom theme_upload_element_file_description($element).
  80    
  81    This is adjusted to file_upload_max_size() if this is lower than the user defined size.
  82    
  83    Even if set to file_upload_max_size(), PHP will drop the file or the entire form submission
  84    if the upload size is exceeded, so these do not get passed to "hook_value".
  85    
  86    While the text must be changed with a custom theme, the message seperator can be set using
  87    '#file_validator_seperator'. This is defaulted to '<br />'
  88  
  89  2) Images
  90  
  91    There are two main settings of interest.
  92    
  93    i) Image preview size
  94    
  95      This can be used to change the image thumb on the form.
  96    
  97      Eg: '#image_preview_size' => '100x100',
  98  
  99    ii) Image preview default image
 100    
 101      This replaces the simple "no image" image.
 102    
 103      Eg: '#image_preview_default_image' => drupal_get_path('module', 'cw') .'/no_image2.GIF',
 104    
 105  3) Themes
 106  
 107    There are a number of possible theming functions:
 108    
 109    i) Element theming functions
 110    
 111      Takes full control of the element theming.
 112      
 113      Note that theme_image_upload_element simply calls theme_upload_element
 114      
 115    ii) Theming the filename preview
 116    
 117      The theme_upload_element_preview themes the filename.
 118      
 119      To override just a one off element, pass the theme function name as a '#file_formatter'
 120      
 121    iii) Theming the image preview
 122    
 123      Override theme_upload_element_image_preview
 124  
 125      To override just a one off element, pass the theme function name as a '#image_formatter'
 126  
 127    iv) Theming the description under the file input control.
 128    
 129      Override theme_upload_element_file_description
 130  
 131  ##############################################################################################################
 132  ######   The demo version that is running @ http://www.caignwebs.com.au/contributions/node/2            ######
 133  ##############################################################################################################
 134  
 135  Adding an image and a file to a node
 136  ------------------------------------
 137  
 138  1) Create a new module info file: "cw.info"
 139  
 140  --------------------------------------------------------------------------------------------------------------
 141  name = Upload example demo
 142  description = A module to demo/test the upload field.
 143  package = Other
 144  core = 6.x
 145  --------------------------------------------------------------------------------------------------------------
 146  
 147  2) Create an install file to create a new table to store the information: "cw.install"
 148  
 149  --------------------------------------------------------------------------------------------------------------
 150  <?php
 151  
 152  function cw_schema() {
 153    $t = get_t();
 154    
 155    // fid1, fid3 are images
 156    // fid2, fid4 are files
 157    $schema['cw_node_images'] = array(
 158      'description' => $t('Additional upload element example fields.'),
 159      'fields' => array(
 160        'nid'             => array('type' => 'int',   'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0,  'description' => $t('Primary Key: The {node}.nid of the node.')),
 161        'fid1'            => array('type' => 'int',   'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0,  'description' => $t('Index: The {files}.fid of the image file.')),
 162        'fid2'            => array('type' => 'int',   'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0,  'description' => $t('Index: The {files}.fid of the file.')),
 163        'fid3'            => array('type' => 'int',   'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0,  'description' => $t('Index: The {files}.fid of the image file.')),
 164        'fid3_alt'        => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => '',  'description' => $t('Custom ALT attribute of the image.')),
 165        'fid3_title'      => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => '',  'description' => $t('Custom TITLE attribute of the image.')), 
 166        'fid3_copyright'  => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => '',  'description' => $t('Copyright details of the image.')),
 167        'fid4'            => array('type' => 'int',   'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0,  'description' => $t('Index: The {files}.fid of the file.')),
 168        'fid4_title'      => array('type' => 'varchar', 'length' => 255, 'not null' => TRUE, 'default' => '',  'description' => $t('Custom TITLE of the file.')), 
 169      ),
 170      'primary key' => array('nid'),
 171    );
 172    return $schema;
 173  }
 174  
 175  /**
 176   * Implementation of hook_install().
 177   */
 178  function cw_install() {
 179    drupal_install_schema('cw');
 180  }
 181  
 182  /**
 183   * Implementation of hook_uninstall().
 184   */
 185  function cw_uninstall() {
 186    drupal_uninstall_schema('cw');
 187  }
 188  
 189  --------------------------------------------------------------------------------------------------------------
 190  
 191  3) Create the hooks required to hook into a node form: "cw.module"
 192  
 193  In this example, we are using a custom 'upload_element_example' content type as the type to add the two fields to.
 194  
 195   a) Using hook_form_alter to add the new fields to the node edit form
 196   b) Using hook_nodeapi op save to save the data
 197   c) Also using the hook_nodeapi ops load and view to present the files
 198   
 199  The example shows how to add new elements into the upload element.
 200   
 201  --------------------------------------------------------------------------------------------------------------
 202  <?php
 203  
 204  /**
 205   * Implementation of hook_form_alter().
 206   */
 207  function cw_form_alter(&$form, $form_state, $form_id) {
 208    // Only do this for node forms
 209    if (isset($form['#id']) && ($form['#id'] == 'node-form') && arg(0) == 'node') {
 210      $node = $form['#node'];
 211      if ($node->type == 'upload_element_example') {
 212        $form['#attributes'] = array("enctype" => "multipart/form-data");
 213        $form['fid2'] = array(
 214          '#type' => 'upload_element',
 215          '#title' => t('File 1'),
 216          '#required' => FALSE,
 217          '#default_value' => $node->fid2,
 218          '#file_validators' => array('file_validate_size' => array(32768)),
 219        );
 220        $form['fid4'] = array(
 221          '#type' => 'upload_element',
 222          '#title' => t('File 2'),
 223          '#required' => FALSE,
 224          '#default_value' => $node->fid4,
 225          '#file_validators' => array(
 226            'file_validate_size' => array(16384),
 227            'file_validate_extensions' => array('txt gif patch diff jpg jpeg'),
 228          ),
 229        );
 230        $form['fid4']['fid4_info'] = array(
 231          '#type' => 'markup',
 232          '#value' => '<div id="edit-fid4-info" class="form-item"><label>Element info: </label><div>This info box and the title field below are child elements added to the upload_element. Two file validators have also been added, size and extension validation.</div></div>',
 233        );
 234        $form['fid4']['fid4_title'] = array(
 235          '#type' => 'textfield',
 236          '#title' => 'Title',
 237          '#description' => 'Extra fields can be added as simply as defining them as child elements.',
 238          '#default_value' => $node->fid4_title,
 239        );
 240        $form['fid1'] = array(
 241          '#type' => 'image_upload_element',
 242          '#title' => t('Image 1'),
 243          '#description' => 'Upload an image to demonstrate the usage of the image_upload_field.',
 244          '#required' => TRUE,
 245          '#default_value' => $node->fid1,
 246          '#file_validators' => array('file_validate_size' => array(131072)),
 247        );
 248        $form['fid3'] = array(
 249          '#type' => 'image_upload_element',
 250          '#title' => t('Image 2'),
 251          '#description' => 'This example uses element settings to configure the preview size.',
 252          '#required' => FALSE,
 253          '#default_value' => $node->fid3,
 254          '#file_validators' => array('file_validate_size' => array(524288)),
 255          '#image_preview_size' => '150x150',
 256        );
 257        $form['fid3']['fid3_info'] = array(
 258          '#type' => 'markup',
 259          '#value' => '<div id="edit-fid4-info" class="form-item"><label>Element info: </label><div>This info box and the following three fields are child elements added to the image_upload_element. A file validators has been added, the image validator is automatically added. Using <i>#image_preview_size</i> we have changed the preview size to fit inside a 150 square box. Save has a distinctive imagecache filter applied to reduce the image size and to convert the image to greyscale.</div></div>',
 260        );
 261        $form['fid3']['fid3_alt'] = array(
 262          '#type' => 'textfield',
 263          '#title' => 'Alt',
 264          '#description' => 'Extra fields can be added as simply as defining them as child elements.',
 265          '#default_value' => $node->fid3_alt,
 266        );
 267        $form['fid3']['fid3_title'] = array(
 268          '#type' => 'textfield',
 269          '#title' => 'Title',
 270          '#description' => 'The title attribute of the image.',
 271          '#default_value' => $node->fid3_title,
 272        );
 273        $form['fid3']['fid3_copyright'] = array(
 274          '#type' => 'textfield',
 275          '#title' => 'Copyright details',
 276          '#description' => 'Another example field.',
 277          '#default_value' => $node->fid3_copyright,
 278        );
 279      }
 280    }
 281  }
 282  
 283  function cw_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) {
 284    if ($node->type == 'upload_element_example') {
 285      switch ($op) {
 286        case 'load':
 287          _cw_load($node);
 288          break;
 289        case 'insert':
 290        case 'update':
 291          _cw_save($node);
 292          break;
 293        case 'view':
 294          $node->content['ue_files'] = array(
 295            '#value' => 
 296              '<h3>File 1:</h3><div>'. cw_file($node->fid2) .'</div>' .
 297              '<h3>File 2:</h3><div>'. cw_file($node->fid4, $node->fid4_title) .'</div>',
 298            '#weight' => 9,
 299          );
 300          $node->content['ue_images'] = array(
 301            '#value' => 
 302              '<h3>Image 1:</h3><div>'. cw_image($node->fid1) .'</div>'.
 303              '<h3>Image 2:</h3><div>'. cw_image($node->fid3, $node->fid3_alt, $node->fid3_title, $node->fid3_copyright) .'</div>',
 304            '#weight' => 10,
 305          );
 306          break;
 307      }
 308    }
 309  }
 310  
 311  function cw_image($image = FALSE, $alt = FALSE, $title = FALSE, $copy = FALSE) {
 312    if (is_object($image)) {
 313      return theme('imagecache', 'upload_element_preview', $image->filepath, $alt, $title) . '<br/><i>' . check_plain($copy) . '</li>';
 314    }
 315    return '--';
 316  }
 317  
 318  function cw_file($file = FALSE, $title = FALSE) {
 319    if ($file) {
 320      $element = array('#value' => $file);
 321      return '<strong>'. $title .'</strong>' . theme('upload_element_preview', $element);
 322    }
 323    return '--';
 324  }
 325  
 326  function _cw_load(&$node) {
 327    if(!$node->nid) return;
 328    $node->fid1 = FALSE;
 329    $node->fid2 = FALSE;
 330    $node->fid3 = FALSE;
 331    $node->fid4 = FALSE;
 332    $q1 = db_fetch_object(db_query("SELECT * FROM {cw_node_images} WHERE nid = %d", $node->nid));
 333    if ($q1) {
 334      $node->fid1 = ($q1->fid1) ? db_fetch_object(db_query("SELECT * FROM {files} WHERE fid = %d", $q1->fid1)) : FALSE;
 335      $node->fid2 = ($q1->fid2) ? db_fetch_object(db_query("SELECT * FROM {files} WHERE fid = %d", $q1->fid2)) : FALSE;
 336      $node->fid3 = ($q1->fid3) ? db_fetch_object(db_query("SELECT * FROM {files} WHERE fid = %d", $q1->fid3)) : FALSE;
 337      $node->fid4 = ($q1->fid4) ? db_fetch_object(db_query("SELECT * FROM {files} WHERE fid = %d", $q1->fid4)) : FALSE;
 338      foreach(array('fid3_alt', 'fid3_title', 'fid3_copyright', 'fid4_title') as $prop) {
 339        $node->$prop = $q1->$prop;
 340      }
 341    }
 342  }
 343  
 344  function _cw_save(&$node) {
 345    if(!$node->nid) return;
 346    
 347  
 348    $fid1 = $fid2 = $fid3 = $fid4 = 0;
 349    if(is_object($node->fid1)) {
 350      $fid1 = upload_element_save($node->fid1, 'upload_element', FILE_EXISTS_RENAME);
 351    }    
 352    if(is_object($node->fid2)) {
 353      $fid2 = upload_element_save($node->fid2, 'upload_element', FILE_EXISTS_RENAME);
 354    }    
 355    if(is_object($node->fid3)) {
 356      $fid3 = upload_element_save($node->fid3, 'upload_element', FILE_EXISTS_RENAME, 'upload_element_save_action');
 357    }    
 358    if(is_object($node->fid4)) {
 359      $fid4 = upload_element_save($node->fid4, 'upload_element', FILE_EXISTS_RENAME);
 360    }    
 361    db_query("
 362      INSERT INTO {cw_node_images} (nid, fid1, fid2, fid3, fid4, fid3_alt, fid3_title, fid3_copyright, fid4_title)
 363      VALUES (%d, %d, %d, %d, %d, '%s', '%s', '%s', '%s')
 364      ON duplicate KEY
 365      UPDATE fid1 = %d, fid2 = %d, fid3 = %d, fid4 = %d, fid3_alt = '%s', fid3_title = '%s', fid3_copyright = '%s', fid4_title = '%s'
 366      ", $node->nid, $fid1, $fid2, $fid3, $fid4, $node->fid3_alt, $node->fid3_title, $node->fid3_copyright, $node->fid4_title,
 367         $fid1, $fid2, $fid3, $fid4, $node->fid3_alt, $node->fid3_title, $node->fid3_copyright, $node->fid4_title);
 368  }
 369  
 370  --------------------------------------------------------------------------------------------------------------