EDIT

 * Returns a set of feature blocks for a taxon profile from the $mergedFeatureNodes of a given $taxon.

 * The taxon profile consists of drupal block elements, one for the description elements

 * of a specific feature. The structure is defined by specific FeatureTree.

 * The chosen FeatureTree is merged with the list of description elements prior to using this method.

 * @param $mergedFeatureNodes

 * @param $taxon

 *

 * @return array

 *  A Drupal render array

 *

 * @ingroup compose

function compose_cdm_feature_nodes($mergedFeatureNodes, $taxon) {

  // Create a drupal block for each feature

    if ((isset($node->descriptionElements['#type']) ||

        has_feature_node_description_elements($node)) && $node->feature->uuid != UUID_IMAGE) { // skip empty or supressed features

      $feature_name = cdm_term_representation($node->feature, 'Unnamed Feature');

      if ($node->feature->uuid == UUID_DISTRIBUTION) {

        $block = compose_feature_block_distribution($taxon, $node->descriptionElements, $node->feature);

        $common_names_render_array = compose_cdm_common_names($node->descriptionElements, $node->feature);

        $block->content .= drupal_render($common_names_render_array);

        $media_list = array();

        $out_child_elements = '';

          // Content/ALL OTHER FEATURES/Subordinate Features

          // subordinate features are printed inline in one floating text,

          // it is expected hat supordinate features can "contain" TextData,

          // Qualitative- and Qualitative- DescriptioneElements

          if (isset($node->childNodes[0])) {

          $block->content .=  compose_feature_media_gallery($node, $media_list, $gallery_settings);

          /*

           * Footnotes for the feature block

           */

          $block->content .= theme('cdm_footnotes', array('footnoteListKey' => $node->feature->uuid));

          $block->content .= theme('cdm_annotation_footnotes', array('footnoteListKey' => $node->feature->uuid));

    } // END: skip empty or supressed features

  } // END: creating a block per feature

  return markup_to_render_array($out);

  /**

   * @param $node

   * @param $media_list

   * @param $gallery_settings

   * @return array

   */

  function compose_feature_media_gallery($node, $media_list, $gallery_settings) {

    if (isset($node->descriptionElements)) {

      $media_list = array_merge($media_list, cdm_dataportal_media_from_descriptionElements($node->descriptionElements));

    }

    $captionElements = array('title', 'rights');

    $gallery = '';

    if (isset($gallery_settings['cdm_dataportal_media_maxextend']) && isset($gallery_settings['cdm_dataportal_media_cols'])) {

      $gallery = theme('cdm_media_gallerie', array(

        'mediaList' => $media_list,

        'galleryName' => CDM_DATAPORTAL_DESCRIPTION_GALLERY_NAME . '_' . $node->feature->uuid,

        'maxExtend' => $gallery_settings['cdm_dataportal_media_maxextend'],

        'cols' => $gallery_settings['cdm_dataportal_media_cols'],

        'captionElements' => $captionElements,

      ));

      return array($media_list, $gallery);

    }

    return array($media_list, $gallery);

  }

  /**

   * @param $taxon

   * @param $descriptionElements

   *   an associative array with two elements:

   *   - '#type': must be 'DTO'

   *   - 'DistributionInfoDTO': a CDM DistributionInfoDTO object as returned by the DistributionInfo web service

   * @param $feature

   *

   * @ingroup compose

   */

  function compose_feature_block_distribution($taxon, $descriptionElements, $feature) {

    $text_data_glue = '';

    $text_data_sortOutArray = FALSE;

    $text_data_enclosingTag = 'ul';

    $text_data_out_array = array();

    $distributionElements = NULL;

    $distribution_info_dto = NULL;

    $distribution_sortOutArray = FALSE;

    if (variable_get('distribution_sort', 'NO_SORT') != 'NO_SORT') {

      $distribution_glue = '';

      $distribution_enclosingTag = 'dl';

    } else {

      $distribution_glue = '';

      $distribution_enclosingTag = 'ul';

    }

    if (!isset($descriptionElements['#type']) || !$descriptionElements['#type'] == 'DTO') {

      // skip the DISTRIBUTION section if there is no DTO type element

      return array(); // FIXME is it ok to return an empty array?

    }

    $block = feature_block(

      cdm_term_representation($feature, 'Unnamed Feature'),

      $feature

    );

    // ======== FIXME is this being used at all? seems to make no sense!!!

    if (isset($descriptionElements['TextData'])) {

      // --- TextData

      foreach ($descriptionElements['TextData'] as $text_data_element) {

        $asListElement = FALSE;

        $repr = theme('cdm_descriptionElementTextData', array(

          'element' => $text_data_element,

          'asListElement' => $asListElement,

          'feature_uuid' => $text_data_element->feature->uuid,

        ));

        if (!array_search($repr, $text_data_out_array)) {

          $text_data_out_array[] = $repr;

          // TODO HINT: sorting in theme_cdm_feature_block_elements will

          // not work since this array contains html attributes with uuids

          // !!!!

          $text_data_sortOutArray = TRUE;

          $text_data_glue = '<br/> ';

          $text_data_enclosingTag = 'p';

        }

      }

    }

    if ($text_data_out_array && variable_get(DISTRIBUTION_TEXTDATA_DISPLAY_ON_TOP, 0)) {

      $block->content .= theme('cdm_feature_block_elements', array(

        'elementArray' => $text_data_out_array,

        'feature' => $feature,

        'glue' => $text_data_glue,

        'sortArray' => $text_data_sortOutArray,

        'enclosingHtml' => $text_data_enclosingTag,

      ));

    }

    // --- Distribution map

    $distribution_map_query_parameters = NULL;

    if (isset($descriptionElements['DistributionInfoDTO'])) {

      $distribution_map_query_parameters = $descriptionElements['DistributionInfoDTO']->mapUriParams;

    }

    $map_render_element = compose_distribution_map($taxon, $distribution_map_query_parameters);

    $block->content .= $map_render_element['#markup'];

    // --- tree or list

    $dto_out_array = array();

    if (isset($descriptionElements['DistributionInfoDTO'])) {

      $distribution_info_dto = $descriptionElements['DistributionInfoDTO'];

      // --- tree

      if (is_object($distribution_info_dto->tree)) {

        $dto_out_array[] = theme('cdm_description_ordered_distributions', array('distribution_tree' => $distribution_info_dto->tree));

      }

      // --- sorted element list

      if (is_array($distribution_info_dto->elements) && count($distribution_info_dto->elements) > 0) {

        foreach ($distribution_info_dto->elements as $descriptionElement) {

          if (is_object($descriptionElement->area)) {

            $sortKey = $descriptionElement->area->representation_L10n;

            $distributionElements[$sortKey] = $descriptionElement;

          }

        }

        ksort($distributionElements);

        $dto_out_array[] = theme('cdm_descriptionElement_Distribution', array(

          'descriptionElements' => $distributionElements,

        ));

      }

      //

      $block->content .= theme('cdm_feature_block_elements', array(

        'elementArray' => $dto_out_array,

        'feature' => $feature,

        'glue' => $distribution_glue,

        'sortArray' => $distribution_sortOutArray,

        'enclosingHtml' => $distribution_enclosingTag,

      ));

    }

    // --- TextData at the bottom

    if ($text_data_out_array && !variable_get(DISTRIBUTION_TEXTDATA_DISPLAY_ON_TOP, 0)) {

      $block->content .= theme('cdm_feature_block_elements', array(

        'elementArray' => $text_data_out_array,

        'feature' => $feature,

        'glue' => $text_data_glue,

        'sortArray' => $text_data_sortOutArray,

        'enclosingHtml' => $text_data_enclosingTag,

      ));

    }

    $block->content .= theme('cdm_footnotes', array('footnoteListKey' => UUID_DISTRIBUTION));

    $block->content .= theme('cdm_annotation_footnotes', array('footnoteListKey' => UUID_DISTRIBUTION));

    return $block;

  }

  /**

function theme_cdm_feature_block_elements($variables) {

  $out = '<' . $enclosingHtml . ' class="feature-block-elements" id="' . $feature->representation_L10n . '">';

  $out .= '<span class="feature-block-element">' . join($elementArray, '<span class="feature-block-element">' . $glue . '</span>') . '</span>';

  $modifiers_strings = cdm_modifers_representations($element->statisticalValues);

  $out .= ($modifiers_strings ? ' ' . cdm_modifers_representations($element->statisticalValues) : '');

        $out .= $description . $sourceRefs . theme(

            'cdm_annotations_as_footnotekeys',

            array('cdmBase_list' => $element,

              'footnote_list_key' => $feature_uuid)) . '</li>';

  // FIXME This will create footnotes for annotations and sources, sources are already rendered though

 * Composes block of common names for the given DescriptionElements $elements which must be of the feature CommonName

 *

 * @parameter $elements

 *  an array of CDM DescriptionElements either of type CommonName or TextData

 * @parameter $feature

 *  the common feature of all $elements, must be CommonName

 *

 * @return

 *   A drupal render array

 *

 * @ingroup compose

function compose_cdm_common_names($elements, $feature) {

  $common_name_feature_elements = array();

  $footnote_key_suggestion = 'common-names-feature-block';

    // loop over set of elements per language area

    foreach ($common_names as $language_area_key => $elements) {

      $per_language_area_out = array();

      // loop over set of individual elements

          $per_language_area_out[] = '<span class="' . html_class_attribute_ref($element) . '">'

          . $element->name . cdm_create_description_element_footnotes($element, ',', $footnote_key_suggestion) . '</span>';

      } // End of loop over set of individual elements

      $common_name_feature_elements[] = ($language_area_key ? $language_area_key . ': ' : '' ) . join(',', $per_language_area_out);

    } // End of loop over set of elements per language area

    $common_name_out .= theme('cdm_feature_block_elements',

      array(

        'elementArray' => $common_name_feature_elements,

        'feature' => $feature,

        'glue' => ';',

        'sortArray' => FALSE,

        'enclosingHtml' => 'div',

      )

    );

  $text_data_out = array();

    /* footnotes are not handled correctly in theme_cdm_descriptionElementTextData,

       need to set 'common-names-feature-block' as $footnote_key_suggestion */

    RenderHints::setFootnoteListKey($footnote_key_suggestion);

    $text_data_out[] = theme('cdm_descriptionElementTextData', array(

  $common_name_out_text_data = theme(

        'cdm_feature_block_elements',

        array(

          'elementArray' => $text_data_out,

          'feature' => $feature

        )

      );

  $footnotes = theme('cdm_footnotes', array('footnoteListKey' => $footnote_key_suggestion)); // FIXME is this needed at all?

  $footnotes .= theme('cdm_annotation_footnotes', array('footnoteListKey' => $footnote_key_suggestion));

  return  markup_to_render_array(

    '<div class="common_names_as_common_names">' . $common_name_out . '</div>'

    .'<div class="common_names_as_text_data">' . $common_name_out_text_data . '</div>'

    .$footnotes

  );

 *   - featureUuid: currently unused, according code disabled

 *   - taxon_uuid: only used for ordered distributions (will be removed!)

  $out = theme('cdm_feature_block_elements', array(