Project

General

Profile

Download (8.39 KB) Statistics
| Branch: | Tag: | Revision:
1
<?php
2
/**
3
 * @file
4
 * pre-drupal8.inc
5
 *
6
 * Contains useful functions which will most probably be included into
7
 * Drupal 8 core and for which did not want to wait that long.
8
 *
9
 */
10

    
11
/******************************************************************************
12
 * description_list from Version: 8.x-dev
13
 *
14
 * from issue:
15
 *   Add a theme_description_list() function to theme a description list
16
 *   (ex. definition list)
17
 *   http://drupal.org/node/54898
18
 *   http://drupal.org/files/drupal8.theme-dl.54.patch
19
 *****************************************************************************/
20
/**
21
 * Preprocesses variables for theme_description_list().
22
 *
23
 * "The dl element represents an association list consisting of zero or more
24
 * name-value groups (a description list). Each group must consist of one or
25
 * more names (dt elements) followed by one or more values (dd elements).
26
 * Within a single dl element, there should not be more than one dt element for
27
 * each name."
28
 *
29
 * @see http://html5doctor.com/the-dl-element/
30
 * @see http://www.w3.org/TR/html-markup/dl.html
31
 * @see http://www.w3.org/wiki/HTML_lists#Description_lists
32
 *
33
 * This means:
34
 * - The DL may be empty.
35
 * - If there is a DT, it must be followed by a DD.
36
 * - There can be multiple DTs followed by one or more DDs.
37
 * - Each set of DTs and DDs forms a group.
38
 * - The text of one DT must be unique within the DL.
39
 * - The DL must contain DT and DD elements only.
40
 *
41
 * @param array $variables
42
 *   An associative array containing:
43
 *   - groups: A list of groups to render. Each item is an array containing:
44
 *     - term: One of the following values:
45
 *       - A string containing the term.
46
 *       - A list of of strings containing terms.
47
 *       - A list of render arrays containing elements to render. Each child
48
 *         element will be wrapped into a DT element. Use #wrapper_attributes
49
 *         to specify attributes of the DT element.
50
 *     - description: One of the following values:
51
 *       - A string containing the description for the term.
52
 *       - A list of of strings containing descriptions for the term.
53
 *       - A list of render arrays containing elements to render. Each child
54
 *         element will be wrapped into a DD element. Use #wrapper_attributes
55
 *         to specify attributes of the DD element.
56
 *   - title: (optional) A heading for the list.
57
 *   - attributes: (optional) Attributes to apply to the DL element.
58
 *
59
 * @return void
60
 *   $variables['groups'] is processed into $variables['items'].
61
 */
62
function template_preprocess_description_list(&$variables) {
63
  $groups = &$variables['groups'];
64
  $variables['items'] = array();
65
  $items = &$variables['items'];
66

    
67
  // Loop over all groups and contained terms and descriptions to prepare the
68
  // simplified 'items' variable for theme_description_list(). But also
69
  // harmonize all items within 'groups' so subsequently invoked preprocess
70
  // functions as well as theme_description_list() can operate on a single,
71
  // reliable structure and syntax.
72
  foreach ($groups as $group) {
73
    // DTs always come before DDs, regardless of their order in the array.
74
    foreach (array('term' => 'dt', 'description' => 'dd') as $key => $tag) {
75
      $item = &$group[$key];
76
      // If the item is a string, then there is only one DT/DD.
77
      if (is_string($item)) {
78
        $items[] = array(
79
            'tag' => $tag,
80
            'attributes' => array(),
81
            'value' => $item,
82
        );
83
        $item = array(array('#prefix' => "<$tag>", '#markup' => $item, '#suffix' => "</$tag>"));
84
      }
85
      // Otherwise, there are multiple DTs/DDs.
86
      else {
87
        foreach ($item as &$value) {
88
          if (is_string($value)) {
89
            $items[] = array(
90
                'tag' => $tag,
91
                'attributes' => array(),
92
                'value' => $value,
93
            );
94
            $value = array('#prefix' => "<$tag>", '#markup' => $value, '#suffix' => "</$tag>");
95
          }
96
          else {
97
            $items[] = array(
98
                'tag' => $tag,
99
                'attributes' => isset($value['#wrapper_attributes']) ? $value['#wrapper_attributes'] : array(),
100
                'value' => drupal_render($value),
101
            );
102
            $value += array('#prefix' => '', '#suffix' => '');
103
            $value['#prefix'] = "<$tag>" . $value['#prefix'];
104
            $value['#suffix'] = $value['#suffix'] . "</$tag>";
105
          }
106
        }
107
      }
108
    }
109
  }
110
}
111

    
112
/**
113
 * Returns HTML for a description list.
114
 *
115
 * @param array $variables
116
 *   An associative array containing:
117
 *   - items: The preprocessed list of description list elements to render. Each
118
 *     item is an associative array containing:
119
 *     - tag: Either 'dt' or 'dd'.
120
 *     - attributes: An array of attributes to apply to the tag.
121
 *     - value: The rendered content for the tag.
122
 *   - groups: The original list of groups to render. Each item is an array
123
 *     containing:
124
 *     - term: One of the following values:
125
 *       - A string containing the term.
126
 *       - A list of of strings containing terms.
127
 *       - A list of render arrays containing elements to render. Each child
128
 *         element will be wrapped into a DT element. Use #wrapper_attributes
129
 *         to specify attributes of the DT element.
130
 *     - description: One of the following values:
131
 *       - A string containing the description for the term.
132
 *       - A list of of strings containing descriptions for the term.
133
 *       - A list of render arrays containing elements to render. Each child
134
 *         element will be wrapped into a DD element. Use #wrapper_attributes
135
 *         to specify attributes of the DD element.
136
 *   - title: (optional) A heading for the list.
137
 *   - attributes: (optional) Attributes to apply to the DL element.
138
 *
139
 * @return string
140
 *   The rendered description list.
141
 *
142
 * @ingroup themeable
143
 */
144
function theme_description_list($variables) {
145
  $items = $variables['items'];
146
  $output = '';
147
  foreach ($items as $item) {
148
    $output .= '<' . $item['tag'] . drupal_attributes($item['attributes']) . '>'; // using drupal_attributes() instead of D8 new Attribute()
149
    $output .= $item['value'];
150
    $output .= '</' . $item['tag'] . '>';
151
  }
152
  // Only output the list, container, and title, if there are any groups.
153
  if ($output !== '') {
154
    $output = '<dl' . drupal_attributes($variables['attributes']) . '>' . $output . '</dl>'; // using drupal_attributes() instead of D8 new Attribute()
155
    $title = '';
156
    if (isset($variables['title'])) {
157
      $title = '<h3>' . $variables['title'] . '</h3>';
158
    }
159
    // If not used for styling purposes, this DIV should be an ASIDE.
160
    $output = '<div class="description_list">' . $title . $output . '</div>';
161
  }
162
  return $output;
163
}
164

    
165
/**
166
 * Adds one term and one description entry to the given description_list_group $group.
167
 *
168
 * Creation of a new entry does not take place if the $description is a string
169
 * which can be trimmed to an empty string. The $group array will be associative in order to
170
 * ease alphabetical ordering of the entries.
171
 *
172
 * NOTE: To be used only for themable description_list as proposed in
173
 * http://drupal.org/node/54898 see includes/pre-drupal8.inc
174
 *
175
 * @param array $groups
176
 *  The description_list_groups
177
 * @param string $term
178
 *
179
 * @param string|array $description
180
 *   a text string or an form element array
181
 *
182
 * @param string $suffix
183
 *   to be appended to the $description if it is not an array
184
 *
185
 * @param number $weight
186
 *   the weight to be used for ordering the TD,DD element groups in the description list
187
 *
188
 * @param array $dt_attributes
189
 *   an array of attributes of the DT element
190
 *
191
 */
192
function _description_list_group_add(&$groups, $term, $description, $suffix = '', $weight=NULL, array $dt_attributes=NULL) {
193

    
194
  if (!is_array($description)) {
195
    $description = trim(drupal_html_to_text($description));
196
  }
197

    
198
  if ($description) {
199
    if (!is_array($description)) {
200
      $description .= $suffix;
201
    }
202

    
203
    if(is_array($dt_attributes)) {
204
      $term_elements = array(
205
        array(
206
            '#wrapper_attributes' => $dt_attributes,
207
            '#markup' => $term
208
        )
209
      );
210
    } else {
211
      $term_elements = $term;
212
    }
213

    
214
    $groups[$term] = array(
215
        'term' => $term_elements,
216
        'description' => $description,
217
    );
218
    if ($weight) {
219
      $groups[$term]['#weight'] = $weight;
220
    }
221
  }
222
}
223

    
224
/******************************************************************************
225
 * add another one below this comment if needed
226
 *****************************************************************************/
(8-8/10)