Rename new_facet_items() -> unselected_facets()

Also add a docstring

ckan/lib/helpers.py

@@ -337,16 +337,33 @@ def _subnav_named_route(text, routename, **kwargs):
 def default_group_type():
     return str( config.get('ckan.default.group_type', 'group') )
 
-def new_facet_items(name, limit=10):
+def unselected_facet_items(facet, limit=10):
+    '''Return the list of unselected facet items for the given facet, sorted
+    by count.
+
+    Returns the list of unselected facet contraints or facet items (e.g. tag
+    names like "russian" or "tolstoy") for the given search facet (e.g.
+    "tags"), sorted by facet item count (i.e. the number of search results that
+    match each facet item).
+
+    Reads the complete list of facet items for the given facet from
+    c.new_facets, and filters out the facet items that the user has already
+    selected.
+
+    Arguments:
+    facet -- the name of the facet to filter.
+    limit -- the max. number of facet items to return.
+
+    '''
     if not c.new_facets or \
-       not c.new_facets.get(name) or \
-       not c.new_facets.get(name).get('items'):
+       not c.new_facets.get(facet) or \
+       not c.new_facets.get(facet).get('items'):
         return []
     facets = []
-    for facet_item in c.new_facets.get(name)['items']:
+    for facet_item in c.new_facets.get(facet)['items']:
         if not len(facet_item['name'].strip()):
             continue
-        if not (name, facet_item['name']) in request.params.items():
+        if not (facet, facet_item['name']) in request.params.items():
             facets.append(facet_item)
     return sorted(facets, key=lambda item: item['count'], reverse=True)[:limit]
 

ckan/lib/helpers_clean.py

@@ -28,7 +28,7 @@
            subnav_link,
            subnav_named_route,
            default_group_type,
-           new_facet_items,
+           unselected_facet_items,
            facet_items,
            facet_title,
          #  am_authorized, # depreciated

ckan/templates/facets.html

@@ -31,17 +31,17 @@
   
 -->
 <py:def function="facet_div(name, title, limit=5, label_function=lambda item: item.display_name, if_empty=None, count_label=lambda c: ' (%d)'%c)">
-    <div py:if="if_empty is not None or h.new_facet_items(name, limit)" class="facet-box">
+    <div py:if="if_empty is not None or h.unselected_facet_items(name, limit)" class="facet-box">
         <h2>${h.facet_title(title)}</h2>
         <ul class="facet-options">
-            <li py:for="facet_item in h.new_facet_items(name, limit)">
+            <li py:for="facet_item in h.unselected_facet_items(name, limit)">
                 <a href="${c.drill_down_url(**{name: facet_item.name})}">
                     ${label_function(facet_item)}
                 </a>
                 ${count_label(facet_item['count'])}
             </li>
         </ul>
-        <p py:if="not h.new_facet_items(name, limit)">${if_empty}</p>
+        <p py:if="not h.unselected_facet_items(name, limit)">${if_empty}</p>
     </div>
 </py:def>
 
@@ -85,17 +85,17 @@ <h2>${h.facet_title(title)}</h2>
       import logging
       logging.getLogger('ckan.templates.facets').warning("Deprecated function: ckan/templates/facets.html:facet_sidebar()")
     ?>
-    <div py:if="if_empty is not None or h.new_facet_items(code, limit)" class="facet-box">
+    <div py:if="if_empty is not None or h.unselected_facet_items(code, limit)" class="facet-box">
         <h2>${title(code)}</h2>
         <ul class="facet-options">
-            <li py:for="facet_item in h.new_facet_items(code, limit)"
+            <li py:for="facet_item in h.unselected_facet_items(code, limit)"
                 py:if="not (code, facet_item.name) in c.fields">
                   <a href="${c.drill_down_url(**{code: facet_item.name})}">
                   <span py:if="'format' in code.lower()">${h.icon(h.format_icon(facet_item.name))}</span>
                     ${label(facet_item.name)}</a>${count_label(facet_item['count'])}
             </li>
         </ul>
-        <p py:if="not h.new_facet_items(code, limit)">${if_empty}</p>
+        <p py:if="not h.unselected_facet_items(code, limit)">${if_empty}</p>
     </div>
 </py:def>
 
@@ -120,8 +120,8 @@ <h2>${title(code)}</h2>
 -->
 <py:def function="facet_list_items(code, limit=5, label=lambda n: n, if_empty=None)">
 
-        <li py:if="if_empty and not h.new_facet_items(code, limit)">${if_empty}</li>
-        <li py:for="facet_item in h.new_facet_items(code, limit)">
+        <li py:if="if_empty and not h.unselected_facet_items(code, limit)">${if_empty}</li>
+        <li py:for="facet_item in h.unselected_facet_items(code, limit)">
             <a href="${c.drill_down_url(**{code: facet_item.name})}">${label(facet_item.name)}</a> (facet_item['count'])
         </li>
 </py:def>