Functions for grouping, sorting, and filtering items

Install into modules/articles/xaruserapi/

Or, I have a simple module named "misctools" that I drop miscellaneous functions into. So in my case, I renamed the functions misctools_* and put them into modules/misctools/xaruserapi/

groupitems

groupitems.php

* array $args['items'] array of item arrays (like as returned by articles getall)
* string $args['field'] name of field to group by
* returns array of ('fieldvalue' => array(items) ) , sorted by key
* items with null value in the field are grouped in key 'null'

function articles_userapi_groupitems( $args )  
{
     extract($args);
     $result = array();
     foreach ($items as $key=>$item) {
         if ( empty($item[$field]) )
             $result[ 'null' ][$key] = $item;
         else
             $result[ $item[$field] ][$key] = $item;
     }
     ksort($result);
     return $result; 
}
 

sortitems

sortitems.php

 * array $args['items'] array of item arrays (like as returned by articles getall)
 * string $args['field'] name of field to sort on
 * string $args['order'] one of ASC, DESC, [default ASC]
 * returns sorted array of items
 Note: I do bubble sort by hand because the $field arg is not in scope of a compare function for usort()
 TODO: allow 'field' to be a list of fields and/or an array of fields

function articles_userapi_sortitems( $args ) 
{
    extract($args);
 
    // Argument check
    if (!isset($items) || count($items)<1) {
        $msg = xarML('Invalid #(1) for #(2) function #(3)() in module #(4)',
            'items list', 'user', 'sortitems',
            'Articles');
        xarErrorSet(XAR_USER_EXCEPTION, 'BAD_PARAM',
            new SystemException($msg));
        return false;
    }
    if (!isset($field)) {
        $msg = xarML('Invalid #(1) for #(2) function #(3)() in module #(4)',
            'field', 'user', 'sortitems',
            'Articles');
        xarErrorSet(XAR_USER_EXCEPTION, 'BAD_PARAM',
            new SystemException($msg));
        return false;
    }
 
 
    $array_size = count($items);
 
    if (!empty($order) && ($order == 'DESC')) {
        for($x = 0; $x < $array_size; $x++) {
            for($y = 0; $y < $array_size; $y++) {
                if($items[$x][$field] > $items[$y][$field]) {
                    $hold = $items[$x];
                    $items[$x] = $items[$y];
                    $items[$y] = $hold;
                }
            }
        }
    }
    else { // assume ASC
        for($x = 0; $x < $array_size; $x++) {
            for($y = 0; $y < $array_size; $y++) {
                if($items[$x][$field] < $items[$y][$field]) {
                    $hold = $items[$x];
                    $items[$x] = $items[$y];
                    $items[$y] = $hold;
                }
            }
        }
    }
 
    return $items;
 }
 

Note, this doesnt work on key arrays! (not sure how to do that yet. Maybe should use usort() and a global for the field?) Instead if you are sorting on a key array, convert it to an index array first with array_values() , such as

<xar:set name="myitems">array_values($myitems)</xar:set>
<xar:set name="myitems">xarModApiFunc('articles','user','sortitems', array('items'=>$myitems, 'field'=>'myfield'))</xar:set>
<xar:foreach in="$myitems" value="$item">
    ....
</xar:foreach> 

filteritems

filteritems.php

 * array $args['items'] array of item arrays (like as returned by articles getall)
 * string $args['field'] name of field to filter on
 * string $args['value'] value to match
 * returns array of ( matchitems, otheritems )

function articles_userapi_filteritems( $args ) {
    extract($args);
 
    $matchitems = array();
    $otheritems = array();
 
    foreach ($items as $item) {
        if ($item[$field] == $value)
            $matchitems[] = $item;
        else
            $otheritems[] = $item;
    }
    return array( $matchitems, $otheritems );
 }
 

dropdownitems

 * flatten a list of items for use in a dropdownlist property
 * array $args['items'] array of item arrays (like as returned by articles getall)
 * string $args['value'] name of field to use for value (default: "key" which is the array key. 
 Example aternatives: "aid", "name". Note should be unique )
 * string $args['field'] name of field to filter on
 * string $args['first'] optional first item (null value)
 * returns array of ( itemkey=>fieldvalue )

function misctools_userapi_dropdownitems( $args ) {
    extract($args);
 
    if (empty($value)) {
        $value = 'key';
    }
    $list = array();
     
    if (isset($first)) {
        $list[''] = $first;
    }
    foreach ($items as $key=>$item) {
        if ($value == 'key') {
            $list[ $key ] = $item[ $field ];            
        }
        else {
            $list[ $item[ $value ] ] = $item[ $field ];
        }
    }
    return $list;
}
   

Example: a dropdown list of categories under a root cat id. Plug this into a dropdown list property's validation function

 xarModApiFunc('misctools','user','dropdownitems', 
     array( 'field'=>'name', 
     'first'=>'', 
     'items'=>xarModApiFunc('categories','user','getchildren', array('cid'=>36))  )) 

Instead of using the CID as the value, lets say you want the cat name as the value, and the cat description as the section name. Further, lets include two cat roots in the selection list. Finally, lets say the property is a Combo Dropdown/Textarea property. The validation may look like this:

xarModApiFunc('misctools','user','dropdownitems', 
    array('field'=>'description','value'=>'name',
    'first'=>'Pick one or enter Other...', 
    'items'=>xarModApiFunc('categories','user','getchildren', 
        array('cids'=>array(87,106))) ))