New #managed_file element is undocumented

I would like to postpone this until we decide to fix or not fix:
#100680: [meta] Make API module generate Form API documentation
because hopefully we'll be generating the Forms API reference automatically from comments in the code, instead of the current manual editing process.

I will try to take this on. We need to have all of the FAPI documented without waiting for dependencies that may or may not arrive.

@eojthebrave: If you can give me a quick set of pointers on how it's used, I'll write it up.

I added this to D7 FAPI. Oh my goodness it's painful to add an element type.
Review is appreciated, http://api.drupal.org/api/drupal/developer--topics--forms_api_reference....

Looks pretty good Randy...

A couple of issues in the section http://api.drupal.org/api/drupal/developer--topics--forms_api_reference....

a) Missing the Properties: #access, etc. line.

b) " Something like the following within your submit handler should do the trick." -- missing the "following" code?

Attached patch addresses the issues in comment 6 as well as providing an inline example like elsewhere in the doc

Note: New files are uploaded with a status of 0 and are treated as temporary files which are removed after 6 hours via cron. Your module is responsible for changing the $file objects status to FILE_STATUS_PERMANENT and saving the new status to the database. Something like the following within your submit handler should do the trick.

<?php
// Load the file via file.fid.
$file = file_load($form_state['values']['my_file_field']);
// Change status to permanent.
$file->status = FILE_STATUS_PERMANENT;
// Save.
file_save($file);
?>

Properties: #access, #after_build, #array_parents, #attached, #attributes, #description, #disabled, #element_validate, #parents, #post_render, #prefix, #pre_render,#process, #states, #suffix, #theme, #theme_wrappers, #title, #tree, #weight

Usage example (image_example.pages.inc.):

  // Use the #managed_file FAPI element to upload an image file.
  $form['image_example_image_fid'] = array(
    '#title' => t('Image'),
    '#type' => 'managed_file',
    '#description' => t('The uploaded image will be displayed on this page using the image style choosen below.'),
    '#default_value' => variable_get('image_example_image_fid', ''),
    '#upload_location' => 'public://image_example_images/',
  );

Looks good to me. I sure appreciate you picking this up.

committed to head

Thanks so much, jgraham!

Alright.........what am I missing here.

eojthebrave said:

Your FAPI validate/submit callback will be given a file object ID that represents the ID of the new file in the {files} table.

How does a validate and/or a submit handler get called when the upload button triggers an ajax call?

Thanks for any advice.

Huh. Nothing?

Well here's what I ended up doing.

function MYMODULE_my_form($form, &$form_state) {
  $form['image'] = array(
    '#type' => 'managed_file',
    '#title' => 'File',
    '#upload_location' => 'public://my-files/',
    '#process' => array('MYMODULE_my_file_element_process')
  );

  return $form;
}

function MYMODULE_my_file_element_process($element, &$form_state, $form) {
  $element = file_managed_file_process($element, $form_state, $form);
  $element['upload_button']['#access'] = FALSE;
  return $element;
}
//  Disable the ajax submit button since it doesn't call my custom submit handler.  Why?
function MYMODULE_my_file_element_process($element, &$form_state, $form) {
  $element = file_managed_file_process($element, $form_state, $form);
  $element['upload_button']['#access'] = FALSE;
  return $element;
}

THEN.....my custom submit handler gets called and all is right within the world. (Except for the fact that this feels wicked-hacky.)

function MYMODULE_submit($form, &$form_state) {
  if (!empty($form_state['values']['thing'])){
    // Load the file via file.fid.
    $file = file_load($form_state['values']['thing']);
    // Change status to permanent.
    $file->status = FILE_STATUS_PERMANENT;
    // Save.
    file_save($file);
    //file_usage_add($file, 'user', 'user', $account->uid);
    drupal_set_message('Your file has been uploaded.');
  } else {
      form_set_error('thing', 'You didn\'t submit anything.');
    }
}