modules/helpers/helpers.module

<?php
// $Id: helpers.module,v 1.17 2006/08/01 07:05:54 ber Exp $

/**
 * @file
 * This is a library of useful functions and methods.
 * please insert the link if you have a patch for core to introduce a function from this lib to core.
 */

/**
 * Implementation of hook_help().
 */
function helpers_help($section) {
  switch ($section) {
    case 'admin/modules#description':
      return t('A development library. Contains numerous usefull functions and methods.');
  }
}

/**
 * implementation of hook_menu()
 */
function helpers_menu($may_cache) {
  if ($may_cache) {
    $items[] = array(
      'path' => 'helpers/void',
      'type' => MENU_CALLBACK,
      'callback' => 'void_page',
      'access' => TRUE,
    );
  }
  return $items;
}


/**
 * Test if a string is empty, or equals another string. If so, return a themed
 empty placeholder. Else return the input string.
 * @param $string: The string we want to find out if its empty;
 * @param $test: Optionally you can test against this string; In case you want to redefine "empty".
 */
function test_empty_string($string, $test = '') {
  if ($string == $test) {
   return theme('empty_placeholder');
  }
  return $string;
}

/**
 * Formats a chopped off string of a certain length. Calls a theme function to
 * do the actual formatting. By default it will return strings in the form of
 * verylongstringwithsomecoo...
 * @param $string the original string.
 * @param $length Optional provide a length for the string
 * @param $count_addition Optional provide an amount for the additional
 * charachters. Giving this parameter, for example a value of 5, you will
 * recieve a shortened string in the form of verylongstringwithsomec.....
 */
function format_shorten_string($string, $length = 15, $count_addition = 3) {
  if (drupal_strlen($string) > $length) {
    $out = theme('shorten_string', drupal_substr($string, 0, ($length - $count_addition)), $string, $count_addition);
  }
  else {
    $out = $string;
  }

  return $out;
}

/**
 * Page functions. Render pages
 */
/**
 * Void. Render nothing. A blank page.
 */
function void_page() {
  return '';
}

/**
 * Common API functions
 */
/**
 * Get a block as object prepared to use in the theme_block function
 * @param $name the modulename (block name) to get the block from.
 * @param $delta the blok delta. Each block in each module has a unique delta value. A number indicating that block.
 */
function get_block($name, $delta = 0) {
  if ($result = module_invoke($name, 'block', 'view', $delta)) {
    $block = (object)$result;
    $block->module = $name;
    $block->delta = $delta;
    return $block;
  }
}

/**
 * Find out if a user has a certain role or roles.
 * @param $user a user object. Must only contain the $user->roles array.
 * @param $roles an array of roles to check for.
 * @return TRUE if the user has a role you checked for, FALSE if the user is not
 * within any of the requested roles.
 */
function user_has_role($user, $roles) {
  foreach ($roles as $rid) {
    if(in_array($rid, array_keys($user->roles))) {
      return TRUE;
    }
  }
  return FALSE;
}

/**
 * Theme functions
 */

/**
 * Theme an "empty" placeholder. Outputs a translated "not available" by default.
 * @param $message: Optional. Provide a translated message string.
 * @return a string that can be used as placeholder for non existing content.
 */
function theme_empty_placeholder($message = NULL) {
  $message = ($message ? $message : t("not available"));
  return '<span class="empty">' . $message .'</span>';
}

/**
 * Return a themed list of definition items.
 * Patch pending at http://drupal.org/node/54898
 * @param $items
 *   An array of items to be displayed in the list.
 *   The argument is: array("term" => $term, "definitions" => $definitions)
 *   If you provide the $definition as arrays, you will get multiple DDs with each DT.
 *   If you provide the $definitions as a string, only one DD will be added to the DT.
 * @param $title
 *   The title of the list.
 * @param $filter
 *   Boolean value to define wether or not you wish to filter the input. Should be left TRUE, unless you sanitize your input yourself.
 * @return
 *   A string containing the list output.
 */
function theme_definition_list($items = array(), $title = NULL, $filter = TRUE) {
  $output = '<div class="definition-list">';
  if (isset($title)) {
    $output .= '<h3>'. ($filter ? check_plain($title) : $title).'</h3>';
  }

  if (!empty($items)) {
    $output .= "<dl>";
    foreach ($items as $item) {
      $output .= '<dt>'. ($filter ? check_plain($item['term']) : $item['term']) .'</dt> ';
      if (is_string($item['definitions'])) {
        $output .= '  <dd>'. ($filter ? filter_xss($item['definitions']) : $item['definitions']) .'</dd>';
      }
      elseif (is_array($item['definitions'])) {
        foreach ($item['definitions'] as $definition) {
          $output .= '  <dd>'.  ($filter ? filter_xss($definition) : $definition) ."</dd>\n";
        }
      }
    }
    $output .= "</dl>";
  }
  $output .= '</div>';
  return $output;
}

 /**
 * Return a themed name: value DT DL pair.
 * @param $name
 *   The name string.
 * @param $value
 *   The value string.
 * @param $filter
 *   Bool passed on to definition list.
 */
function theme_name_and_value_pair($name, $value, $filter = TRUE) {
  //simple version: return "<strong>$name:</strong> $value";
  $items[] = array('term' => $name .':', 'definitions' => $value);
  return theme('definition_list', $items, NULL, $filter);
}

/**
 * Returns a themed "none" string, for usage in a select form.
 * In case you wish a general way of building the &lt;none&gt; strings.
 * @param $string optionally provide a string that goes in the place of the word "none". If you provide this, it will not be translated.
 */
function theme_none_option($string = NULL) {
  $string = ($string ? $string : t('none'));
  return '<'. $string .'>';
}

/**
 * Function to theme the read more links
 * Drupal issue number 69571
 * @ingroup themeable
 * @param $path a drupal path or full url to the full resource. Include http:// if you link to external resource.
 * @param $title an optional title that will provide a tooltip text when hovering over the link.
 */
function theme_read_more($path, $title = NULL) {
  if ($title) {
    $params['title'] = check_plain($title);
  }
  $params['class'] = 'read-more';
  return l(t('read more'), $path, $params);
}

/**
 * Function to theme the read more links
 * @ingroup themeable
 * @param $short_string The shortened string
 * @param $full_string The unshortened string, for display in the tooltip
 * @param $count_addition The amount of charanters that the calling function wants to be added. Defaults to three. Optional.
 */
function theme_shorten_string($short_string, $full_string, $count_addition = 3) {
  while ($i < $count_addition) {
    $i++;
    $addition .= '.';
  }

  return '<span title="'. $full_string .'">'. $short_string . $addition .'</span>';
}
1	<?php
2	// $Id: helpers.module,v 1.17 2006/08/01 07:05:54 ber Exp $
3
4	/**
5	* @file
6	* This is a library of useful functions and methods.
7	* please insert the link if you have a patch for core to introduce a function from this lib to core.
8	*/
9
10	/**
11	* Implementation of hook_help().
12	*/
13	function helpers_help($section) {
14	switch ($section) {
15	case 'admin/modules#description':
16	return t('A development library. Contains numerous usefull functions and methods.');
17	}
18	}
19
20	/**
21	* implementation of hook_menu()
22	*/
23	function helpers_menu($may_cache) {
24	if ($may_cache) {
25	$items[] = array(
26	'path' => 'helpers/void',
27	'type' => MENU_CALLBACK,
28	'callback' => 'void_page',
29	'access' => TRUE,
30	);
31	}
32	return $items;
33	}
34
35
36	/**
37	* Test if a string is empty, or equals another string. If so, return a themed
38	empty placeholder. Else return the input string.
39	* @param $string: The string we want to find out if its empty;
40	* @param $test: Optionally you can test against this string; In case you want to redefine "empty".
41	*/
42	function test_empty_string($string, $test = '') {
43	if ($string == $test) {
44	return theme('empty_placeholder');
45	}
46	return $string;
47	}
48
49	/**
50	* Formats a chopped off string of a certain length. Calls a theme function to
51	* do the actual formatting. By default it will return strings in the form of
52	* verylongstringwithsomecoo...
53	* @param $string the original string.
54	* @param $length Optional provide a length for the string
55	* @param $count_addition Optional provide an amount for the additional
56	* charachters. Giving this parameter, for example a value of 5, you will
57	* recieve a shortened string in the form of verylongstringwithsomec.....
58	*/
59	function format_shorten_string($string, $length = 15, $count_addition = 3) {
60	if (drupal_strlen($string) > $length) {
61	$out = theme('shorten_string', drupal_substr($string, 0, ($length - $count_addition)), $string, $count_addition);
62	}
63	else {
64	$out = $string;
65	}
66
67	return $out;
68	}
69
70	/**
71	* Page functions. Render pages
72	*/
73	/**
74	* Void. Render nothing. A blank page.
75	*/
76	function void_page() {
77	return '';
78	}
79
80	/**
81	* Common API functions
82	*/
83	/**
84	* Get a block as object prepared to use in the theme_block function
85	* @param $name the modulename (block name) to get the block from.
86	* @param $delta the blok delta. Each block in each module has a unique delta value. A number indicating that block.
87	*/
88	function get_block($name, $delta = 0) {
89	if ($result = module_invoke($name, 'block', 'view', $delta)) {
90	$block = (object)$result;
91	$block->module = $name;
92	$block->delta = $delta;
93	return $block;
94	}
95	}
96
97	/**
98	* Find out if a user has a certain role or roles.
99	* @param $user a user object. Must only contain the $user->roles array.
100	* @param $roles an array of roles to check for.
101	* @return TRUE if the user has a role you checked for, FALSE if the user is not
102	* within any of the requested roles.
103	*/
104	function user_has_role($user, $roles) {
105	foreach ($roles as $rid) {
106	if(in_array($rid, array_keys($user->roles))) {
107	return TRUE;
108	}
109	}
110	return FALSE;
111	}
112
113	/**
114	* Theme functions
115	*/
116
117	/**
118	* Theme an "empty" placeholder. Outputs a translated "not available" by default.
119	* @param $message: Optional. Provide a translated message string.
120	* @return a string that can be used as placeholder for non existing content.
121	*/
122	function theme_empty_placeholder($message = NULL) {
123	$message = ($message ? $message : t("not available"));
124	return '<span class="empty">' . $message .'</span>';
125	}
126
127	/**
128	* Return a themed list of definition items.
129	* Patch pending at http://drupal.org/node/54898
130	* @param $items
131	* An array of items to be displayed in the list.
132	* The argument is: array("term" => $term, "definitions" => $definitions)
133	* If you provide the $definition as arrays, you will get multiple DDs with each DT.
134	* If you provide the $definitions as a string, only one DD will be added to the DT.
135	* @param $title
136	* The title of the list.
137	* @param $filter
138	* Boolean value to define wether or not you wish to filter the input. Should be left TRUE, unless you sanitize your input yourself.
139	* @return
140	* A string containing the list output.
141	*/
142	function theme_definition_list($items = array(), $title = NULL, $filter = TRUE) {
143	$output = '<div class="definition-list">';
144	if (isset($title)) {
145	$output .= '<h3>'. ($filter ? check_plain($title) : $title).'</h3>';
146	}
147
148	if (!empty($items)) {
149	$output .= "<dl>";
150	foreach ($items as $item) {
151	$output .= '<dt>'. ($filter ? check_plain($item['term']) : $item['term']) .'</dt> ';
152	if (is_string($item['definitions'])) {
153	$output .= ' <dd>'. ($filter ? filter_xss($item['definitions']) : $item['definitions']) .'</dd>';
154	}
155	elseif (is_array($item['definitions'])) {
156	foreach ($item['definitions'] as $definition) {
157	$output .= ' <dd>'. ($filter ? filter_xss($definition) : $definition) ."</dd>\n";
158	}
159	}
160	}
161	$output .= "</dl>";
162	}
163	$output .= '</div>';
164	return $output;
165	}
166
167	/**
168	* Return a themed name: value DT DL pair.
169	* @param $name
170	* The name string.
171	* @param $value
172	* The value string.
173	* @param $filter
174	* Bool passed on to definition list.
175	*/
176	function theme_name_and_value_pair($name, $value, $filter = TRUE) {
177	//simple version: return "<strong>$name:</strong> $value";
178	$items[] = array('term' => $name .':', 'definitions' => $value);
179	return theme('definition_list', $items, NULL, $filter);
180	}
181
182	/**
183	* Returns a themed "none" string, for usage in a select form.
184	* In case you wish a general way of building the <none> strings.
185	* @param $string optionally provide a string that goes in the place of the word "none". If you provide this, it will not be translated.
186	*/
187	function theme_none_option($string = NULL) {
188	$string = ($string ? $string : t('none'));
189	return '<'. $string .'>';
190	}
191
192	/**
193	* Function to theme the read more links
194	* Drupal issue number 69571
195	* @ingroup themeable
196	* @param $path a drupal path or full url to the full resource. Include http:// if you link to external resource.
197	* @param $title an optional title that will provide a tooltip text when hovering over the link.
198	*/
199	function theme_read_more($path, $title = NULL) {
200	if ($title) {
201	$params['title'] = check_plain($title);
202	}
203	$params['class'] = 'read-more';
204	return l(t('read more'), $path, $params);
205	}
206
207	/**
208	* Function to theme the read more links
209	* @ingroup themeable
210	* @param $short_string The shortened string
211	* @param $full_string The unshortened string, for display in the tooltip
212	* @param $count_addition The amount of charanters that the calling function wants to be added. Defaults to three. Optional.
213	*/
214	function theme_shorten_string($short_string, $full_string, $count_addition = 3) {
215	while ($i < $count_addition) {
216	$i++;
217	$addition .= '.';
218	}
219
220	return '<span title="'. $full_string .'">'. $short_string . $addition .'</span>';
221	}