/[drupal]/contributions/modules/activeselect/API.txt
ViewVC logotype

Diff of /contributions/modules/activeselect/API.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph | View Patch Patch

revision 1.3, Wed Mar 29 12:51:48 2006 UTC revision 1.4, Sun Apr 9 05:11:52 2006 UTC
# Line 1  Line 1 
1  // $Id: API.txt,v 1.2 2006/03/28 13:23:35 jaza Exp $  // $Id: API.txt,v 1.3 2006/03/29 12:51:48 jaza Exp $
2    
3  Implementing activeselect in other modules  Implementing activeselect in other modules
4  ------------------------------------------  ------------------------------------------
# Line 102  function foo_activeselect($source, $targ Line 102  function foo_activeselect($source, $targ
102    $targets = explode(',', $targets);    $targets = explode(',', $targets);
103    $output = array();    $output = array();
104    
105    $array = explode('||', $string);    $array = activeselect_explode_values($string);
   foreach ($array as $key => $value) {  
     $match = explode('|', $value);  
     $array[$match[0]] = html_entity_decode($match[1]);  
     unset($array[$key]);  
   }  
106    
107    foreach ($targets as $target) {    foreach ($targets as $target) {
108      $options = array();      $options = array();
109    
110      $first_element = TRUE;      $first_element = TRUE;
111      foreach ($array as $key => $value) {      foreach ($array as $key => $value) {
112        $options[$key. '-'. $target] = str_replace('|', '|', $value. ' ('. $target. ')');        $options[$key. '-'. $target]['value'] = $value. ' ('. $target. ')';
113    
114        if ($first_element) {        if ($first_element) {
115          $options[$key. '-'. $target] .= '|selected';          $options[$key. '-'. $target]['selected'] = TRUE;
116          $first_element = FALSE;          $first_element = FALSE;
117        }        }
118          else {
119            $options[$key. '-'. $target]['selected'] = FALSE;
120          }
121      }      }
122      $multiple = TRUE;      $multiple = TRUE;
     $target_name = str_replace('|', '|', $target). ($multiple ? '|multiple' : '');  
123    
124      $output[$target] = activeselect_implode_array($options);      $output[$target] = array('options' => $options, 'multiple' => $multiple);
125    }    }
126    
127    activeselect_set_header_nocache();    activeselect_set_header_nocache();
128    
129    print activeselect_implode_activeselect($output);    print drupal_to_js($output);
130    exit();    exit();
131  }  }
132    
# Line 137  The format of the variables passed in as Line 134  The format of the variables passed in as
134    
135  - $source: the name of the source activeselect element, as defined by the module author in a $form array. The name does not include the 'edit-' prefix that is prepended to it when it is outputted on the page.  - $source: the name of the source activeselect element, as defined by the module author in a $form array. The name does not include the 'edit-' prefix that is prepended to it when it is outputted on the page.
136  - $targets: the names of the target activeselect element(s), separated by commas. These names also do not include the 'edit-' prefix.  - $targets: the names of the target activeselect element(s), separated by commas. These names also do not include the 'edit-' prefix.
137  - $string: the options that the user has currently selected in the source activeselect, represented as a string. Each option in the string is separated by double pipe '|' symbols, and within each option, the option's internal value and its user-displayed text are separated by a single pipe '|' symbol.  - $string: the options that the user has currently selected in the source activeselect, represented as a string. Each option in the string is separated by double pipe '|' symbols, and within each option, the option's internal value and its user-displayed text are separated by a single pipe '|' symbol. It is recommended that you use the activeselect_explode_values() function, as shown, to convert this string into an array of keys and values.
138  - $extra: the data (if any) that has been defined for the source activeselect's 'extra' attribute. The format of this field is up to the module developer, but it must be stored as a string.  - $extra: the data (if any) that has been defined for the source activeselect's 'extra' attribute. The format of this field is up to the module developer, but it must be stored as a string.
139    
140  And the format of the output value is as follows:  And the format of the output value is as follows (when represented as a nested PHP array):
141    
142  target-name-1|||opt-val-1|opt-text-1||opt-val-2|opt-text-2|selected||||target-name-2|multiple|||opt-val-3|opt-text-3  array(
143      'target-name-1' => array(
144        'options' => array(
145          'opt-val-1' => array(
146            'value' => 'opt-text-1',
147            'selected' => TRUE
148          ),
149          'opt-val-2' => array(
150            'value' => 'opt-text-2',
151            'selected' => FALSE
152          )
153        ),
154        'multiple' => TRUE
155      ),
156      'target-name-2' => array(
157        'options' => array(
158          'opt-val-3' => array(
159            'value' => 'opt-text-3',
160            'selected' => FALSE
161          )
162        ),
163        'multiple' => FALSE
164      ),
165    );
166    
167  Values are grouped first by target, and then by each option element. Targets are separated by quadruple pipe '|' symbols. The target's name is separated from the list of options for that target by triple pipe '|' symbols. The option elements are separated by double pipe '|' symbols. And finally, the internal value is separated from the user-displayed text for each option by a single pipe '|' symbols.  Values are grouped first by target, and then by option element. Each target has an 'options' attribute (which holds the array of options), as well as a boolean 'multiple' attribute (to indicate whether or not the element should be a multi-select). Similarly, each option element has a 'value' attribute (which holds the user-displayed text of that element), as well as a boolean 'selected' attribute (to indicate whether or not the option should be set to 'selected' when it is added to the target element).
168    
169  The activeselect_implode_array() function is useful for converting an array of options into the required format, and the activeselect_implode_activeselect() function is useful for converting an array of targets (with already-converted option strings) into the required format. It is recommended that you use these functions in the manner illustrated in the example.  As the example above illustrates, the best way to build your output is as a nested PHP array. However, the final output of your callback must be a string in JSON (JavaScript Object Notation) format. It is recommended that you use the drupal_to_js() function (which is part of Drupal core), as shown, to convert your nested PHP array into a JSON string, which can then be outputted. The activeselect JavaScript library will then be able to process your output, using the Drupal-provided parseJson() JavaScript function.
170    
171  It is also important that you call the activeselect_set_header_nocache() function before printing your output. This function sets the HTTP headers for the activeselect page, such that the user's browser is instructed not to cache the content of the page. If you do not set the headers in this way, then you may experience problems with your activeselect elements in MSIE (as this browser caches HTTP GET requests by default).  It is also important that you call the activeselect_set_header_nocache() function before printing your output. This function sets the HTTP headers for the activeselect page, such that the user's browser is instructed not to cache the content of the page. If you do not set the headers in this way, then you may experience problems with your activeselect elements in MSIE (as this browser caches HTTP GET requests by default).
   
 For each option element that you output on your callback page, you can append the element's text with the a single pipe '|' symbol, and the word 'selected', to indicate that this option be set to 'selected' when it is added to the target element. Additionally, you can append a single pipe '|' symbol, and the word 'multiple', after the name of the target, to indicate that the element should be a multi-select (the reverse happens if you omit this). Neither the appended '|selected' string for selected elements, nor the appended '|multiple' string are actually output to the user - they are both removed by the receiving JavaScript code.  
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4
  ViewVC Help
Powered by ViewVC 1.1.2