Rendu, tableau de rendu et éléments

Source: Render Arrays in Drupal 7 https://www.drupal.org/node/930760

Depuis drupal 7, les données restent dans des tableaux PHP et restent dc manipulables (par les divers thèmes et modules) jusqu'à ce que le thème en produisent son rendu (et chmilblic html).

Sous drupal 6, on pouvait les modifier comme des formulaires (via hook_form_alter()). Depuis la v7 un thème (ou module) peut utiliser hook_page_alter() jusqu'au dernier moment, pour travailler sur blocks et pages :

<?php
function mymodule_page_alter(&$page) {
  // Move search form into the footer.
  $page['footer']['search_form'] = $page['sidebar_first']['search_form'];
  unset($page['sidebar_first']['search_form']);
  // Remove the "powered by Drupal" block
  unset($page['footer']['system_powered-by']);
}
?>

 Elements et tableaux de rendu (render array)

Les modules peuvent définir des "éléments" (les penser comme des tableaux de rendu "prets-à-l'emploi", qui ont un #type et des propriétés), en utilisant hook_element_info(). Quand #type est déclaré pour un render array, les prop par défaut du type d'elm nommé seront chargés à l'aide de hook_element_info().

Créer le contenu en render array

A chaque fois qu'un module crée du contenu, il doit etre sous la forme d'un tab de rendu (depuis la v7).

<?php
function mymodule_menu() {
  $items['mypage-html'] = array(
    'title' => 'My page with HTML-style function',
    'page callback' => 'mymodule_html_page',
    'access callback' => TRUE,
  );
  $items['mypage-ra'] = array(
    'title' => 'My page with render array function',
    'page callback' => 'mymodule_ra_page',
    'access callback' => TRUE,
  );
  return $items;
}

// Ancienne methode pour generer page (HTML)
function mymodule_html_page() {
  $output = '<p>A paragraph about some stuff...</p>';
  $output .= '<ul><li>first item</li><li>second item</li><li>third item</li></ul>';
  return $output;
}

// New method of generating the render array and returning that
function mymodule_ra_page() {
  $output =  array(
    'first_para' => array(
      '#type' => 'markup',
      '#markup' => '<p>A paragraph about some stuff...</p>',
    ),
    'second_para' => array(
      '#items' => array('first item', 'second item', 'third item'),
      '#theme' => 'item_list',
    ),
  );
  return $output;
}
?>

Ex de type de tableaux spéciaux

Dans la v6, chaque "élément" drupal (cf hook_element_info()) est un type (ex de types prédéfinis: page, form, html_tag, value, markup, link, fieldset...). Du coup, les éléments sont accessibles en vrac dans system_element_info().
Par convension, les #-properties utilisées par ces #types sont documentés avec la meme fonction theme.
Ex: pour trouver infos sur #type => 'html_tag' rechercher theme_html_tag().
On peux créer des types et des prop à la volée.

3 ex (de http://drupal.org/project/examples):

<?php
$demos = array(
  t('Super simple #markup')  => array(
    '#markup' => t('Some basic text in a #markup (shows basic markup and how it is rendered)'),
  ),

  'prefix_suffix' => array(
    '#markup' => t('This one adds a prefix and suffix, which put a div around the item'),
    '#prefix' => '<div><br/>(prefix)<br/>',
    '#suffix' => '<br/>(suffix)</div>',
  ),

  'theme for an element' => array(
    'child' => array(
      t('This is some text that should be put together'),
      t('This is some more text that we need'),
    ),
    '#separator' => ' | '// Made up for this theme function.
    '#theme' => 'render_example_aggregate',
  ),
);
?>

Quelques propriétés

#type le type de l'élément. Si ce tab est un elmt, les prop par défaut de l'elmt est chargé => raccourcis pour un ens de prop prédéfinies (qui ont été préparées avec hook_element_info()).
#markup prop la plus simple, qui fabrique une chaine de balisage pour #type => 'markup'
#prefix/#suffix chaine (à mettre avant ou après) l'elmt rendu
#pre_render tab de fonctions qui peuvent modifier l'actuel render array avant le rendu (effacer parties, changer de place, mettre #printed = TRUE ...).
#post_render tab de fonctions qui peuvent travailler sur le HTML final après le rendu. Ces fonctions recoivent en arg le html et le tab de rendu qui l'avait généré.
Ressemble à #theme_wrappers sauf que le sous-system du thème n'est pas utilisé.
#theme  
#theme_wrappers  
#cache  
#weight  

 

logo drush