How to wrap field in custom markup?

Question

Situation I have a custom module that is using hook_field_formatter_info() to add an "fancy" option to the image field in the manage display of a content type. When this option is chosen I want to be able to surround the ENTIRE field in custom divs and markup. I want the solution to be a hook in my custom module and not a template override.

Process A user wants the display of an image field to be the "fancy" option. They check it in the drop down and click save from the content types Manage Display admin page. Now on that content type node there should be custom markup surrounding the entire field even if there are multiple images, the new markup should surround ALL the images and not each individual image.

hook_field_formatter_view hook_field_formatter_view seems to demand it's output be an array and I can't seem to be able to wrap the output in a div.

Template overrides I can't just make a field.tpl.php for the specific field because like I initially mentioned I need to be able to switch themes and the module still work like normal. Unless there is a way to get my module to override any field where said field has hook_field_formatter_info() set specifically.

/**
 * Implements hook_field_formatter_view().
 */
function bootstrap_modal_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
  $element = array();

  foreach ($items as $delta => $item) {
    if ($index === NULL || $index === $delta) {
      $element[$delta] = array(
        '#theme' => 'bootstrap_modal_image_formatter',
        '#item' => $item,
        '#entity_type' => $entity_type,
        '#entity' => $entity,
        '#node' => $entity, // Left for legacy support.
        '#field' => $field,
        '#display_settings' => $display['settings'],
        '#delta' => $delta,
      );
    }
  }


  // $element = '<div id="CUSTOMDIVSTUFF">' . $element . '</div>';

  return $element;
}

And here is the #theme function:

function theme_bootstrap_modal_image_formatter($variables) {

  $item = $variables['item'];
  $entity_type = $variables['entity_type'];
  $entity = $variables['entity'];
  $field = $variables['field'];
  $settings = $variables['display_settings'];

  $image = array(
    'path' => $item['uri'],
    'alt' => isset($item['alt']) ? $item['alt'] : '',
    'title' => isset($item['title']) ? $item['title'] : '',
    'style_name' => $settings['bootstrap_modal_node_style'],
  );

  if (isset($item['width']) && isset($item['height'])) {
    $image['width'] = $item['width'];
    $image['height'] = $item['height'];
  }

  if (isset($item['attributes'])) {
    $image['attributes'] = $item['attributes'];
  }

  // Allow image attributes to be overridden.
  if (isset($variables['item']['override']['attributes'])) {
    foreach (array('width', 'height', 'alt', 'title') as $key) {
      if (isset($variables['item']['override']['attributes'][$key])) {
        $image[$key] = $variables['item']['override']['attributes'][$key];
        unset($variables['item']['override']['attributes'][$key]);
      }
    }
    if (isset($image['attributes'])) {
      $image['attributes'] = $variables['item']['override']['attributes'] + $image['attributes'];
    }
    else {
      $image['attributes'] = $variables['item']['override']['attributes'];
    }
  }

  $entity_title = entity_label($entity_type, $entity);

  if ($style_name = $settings['bootstrap_modal_image_style']) {
    $path = image_style_url($style_name, $image['path']);
  }
  else {
    $path = file_create_url($image['path']);
  }

  $caption = 'some value';
  $gallery_id = 'some value';

  return theme('bootstrap_modal_imagefield', array('image' => $image, 'path' => $path, 'title' => $caption, 'gid' => $gallery_id));
}

Been working on this for days, I'm drowning here.

Answer 1

This is possible via HOOK_process_field(). Use this hook to define a new template file for your field by adding it to theme_hook_suggestions array (place the template file in your module directory, because you wanted to change the theme -as you mentioned-). More info about field template suggestions.

Then, you will need to add the module path to drupal theme registry, so it picks up the template file. Demo.

Answer 2

I found out it was:

function bootstrap_modal_field_formatter_view($entity_type, $entity, $field, $instance,       $langcode, $items, $display) {
  $element = array(
    '#prefix' => '<div class="wrapper">',
    '#suffix' => '</div>',
);