added documentation for the userpicker

diff --git a/js/lib/userpicker.js b/js/lib/userpicker.js
index f2c2aa53f66f9c4920d2c7518bc86481f9bef221..ae2add53f8ab002697f971a713d7ae96269077e4 100644 (file)
--- a/js/lib/userpicker.js
+++ b/js/lib/userpicker.js
@@ -1,5 +1,13 @@
 elgg.provide('elgg.userpicker');
 
+/**
+ * Userpicker initialization
+ *
+ * The userpicker is an autocomplete library for selecting multiple users or
+ * friends. It works in concert with the view input/userpicker.
+ *
+ * @return void
+ */
 elgg.userpicker.init = function() {
        
        // binding autocomplete.
@@ -29,7 +37,13 @@ elgg.userpicker.init = function() {
 }
 
 /**
+ * Adds a user to the select user list
+ *
  * elgg.userpicker.userList is defined in the input/userpicker view
+ *
+ * @param {Object} event
+ * @param {Object} ui    The object returned by the autocomplete endpoint
+ * @return void
  */
 elgg.userpicker.addUser = function(event, ui) {
        var info = ui.item;
@@ -39,7 +53,7 @@ elgg.userpicker.addUser = function(event, ui) {
                elgg.userpicker.userList[info.guid] = true;
                var users = $(this).siblings('.elgg-user-picker-list');
                var li = '<input type="hidden" name="members[]" value="' + info.guid + '" />';
-               li += elgg.userpicker.renderUser(info);
+               li += elgg.userpicker.viewUser(info);
                $('<li>').html(li).appendTo(users);
        }
 
@@ -47,6 +61,12 @@ elgg.userpicker.addUser = function(event, ui) {
        event.preventDefault();
 }
 
+/**
+ * Remove a user from the selected user list
+ *
+ * @param {Object} event
+ * @return void
+ */
 elgg.userpicker.removeUser = function(event) {
        var item = $(this).closest('.elgg-user-picker-list > li');
        
@@ -58,9 +78,14 @@ elgg.userpicker.removeUser = function(event) {
 }
 
 /**
- * The html in this method has to remain sync'ed with input/userpicker
+ * Render the list item for insertion into the selected user list
+ *
+ * The html in this method has to remain synced with the input/userpicker view
+ *
+ * @param {Object} info  The object returned by the autocomplete endpoint
+ * @return string
  */
-elgg.userpicker.renderUser = function(info) {
+elgg.userpicker.viewUser = function(info) {
 
        var deleteLink = "<a href='#' class='elgg-userpicker-remove'>X</a>";
 
@@ -73,6 +98,14 @@ elgg.userpicker.renderUser = function(info) {
        return html;
 }
 
+/**
+ * Get the parameters to use for autocomplete
+ *
+ * This grabs the value of the friends checkbox.
+ *
+ * @param {Object} obj  Object for the autocomplete callback
+ * @return Object
+ */
 elgg.userpicker.getSearchParams = function(obj) {
        if (obj.element.siblings('[name=match_on]').attr('checked')) {
                return {'match_on[]': 'friends', 'term' : obj.term};

diff --git a/views/default/input/userpicker.php b/views/default/input/userpicker.php
index 87cc6e24acd41ad91d7a80e8bbe22063b482f072..5c4b297b1db22043433be96921aca81e34c8e3dc 100644 (file)
--- a/views/default/input/userpicker.php
+++ b/views/default/input/userpicker.php
@@ -9,14 +9,14 @@
  *
  * The name of the hidden fields is members[]
  *
- * Defaults to lazy load user lists in paginated alphabetical order. User needs
+ * @warning Only a single input/userpicker is supported per web page.
+ *
+ * Defaults to lazy load user lists in alphabetical order. User needs
  * to type two characters before seeing the user popup list.
  *
- * As users are checked they move down to a "users" box.
+ * As users are selected they move down to a "users" box.
  * When this happens, a hidden input is created with the
  * name of members[] and a value of the GUID.
- *
- * @warning: this is not stable
  */
 
 elgg_load_js('elgg.userpicker');
@@ -29,6 +29,7 @@ function user_picker_add_user($user_id) {
        
        $icon = elgg_view_entity_icon($user, 'tiny', array('hover' => false));
 
+       // this html must be synced with the userpicker.js library
        $code = '<li><div class="elgg-image-block">';
        $code .= "<div class='elgg-image'>$icon</div>";
        $code .= "<div class='elgg-image-alt'><a href='#' class='elgg-userpicker-remove'>X</a></div>";
@@ -66,5 +67,6 @@ foreach ($vars['value'] as $user_id) {
        <ul class="elgg-user-picker-list"><?php echo $user_list; ?></ul>
 </div>
 <script type="text/javascript">
+       // @todo grab the values in the init function rather than using inline JS
        elgg.userpicker.userList = <?php echo $json_values ?>;
 </script>
\ No newline at end of file