Mark Lavin avatar Mark Lavin committed 2b6740a

Docs on using the new label formatting options. See #35.

Comments (0)

Files changed (2)

docs/advanced.rst

 
 .. _server-side-parameters:
 
-Adding Parameters on the Server Side
+Adding Parameters on the Server Sid
 _______________________________________
 
 Each of the widgets define `update_query_parameters` which takes a dictionary. The
 addition parameter with the following javascript:
 
     .. literalinclude:: ../example/core/templates/advanced.html
+        :language: html
         :start-after: {% block extra-js %}
         :end-before: {% endblock %}
 
 Currently you must include the django-selectable javascript below this formset initialization
 code for this to work. See django-selectable `issue #31 <https://bitbucket.org/mlavin/django-selectable/issue/31/>`_
 for some additional detail on this problem.
+
+
+.. _advanaced-label-formats:
+
+Label Formats on the Client Side
+--------------------------------------
+
+The lookup label is the text which is shown in the list before it is selected.
+You can use the :ref:`get_item_label <lookup-get-item-label>` method in your lookup
+to do this on the server side. This works for most applications. However if you don't
+want to write your HTML in Python or need to adapt the format on the client side you
+can use the ``formatLabel`` option.
+
+``formatLabel`` takes two paramaters the current label and the current selected item.
+The item is a dictionary object matching what is returned by the lookup's
+:ref:`format_item <lookup-format-item>`. ``formatLabel`` should return the string
+which should be used for the label.
+
+Going back to the ``CityLookup`` we can adjust the label to wrap the city and state
+portions with their own classes for additional styling:
+
+    .. literalinclude:: ../example/core/lookups.py
+        :pyobject: CityLookup
+
+    .. code-block:: html
+
+        <script type="text/javascript">
+            $(document).ready(function() {
+                function formatLabel(label, item) {
+                    var data = label.split(',');
+                    return '<span class="city">' + data[0] + '</span>, <span class="state">' + data[1] + '</span>';
+                }
+                $('#id_city_0').djselectable('option', 'formatLabel', formatLabel);
+            });
+        </script>
+
+This is a rather simple example but you could also pass additional information in ``format_item``
+such as a flag of whether the city is the capital and render the state captials differently.
     :param term: The search term from the widget input.
     :return: An iterable set of data of items matching the search term.
 
+.. _lookup-get-item-label:
+
 .. py:method:: LookupBase.get_item_label(item)
 
     This is first of three formatting methods. The label is shown in the
     :param item: An item from the search results.
     :return: A string representation of the item to be shown in the search results.
 
+    .. versionadded:: 0.3
+
+    The label can include HTML. For changing the label format on the client side
+    see :ref:`Advanaced Label Formats <advanaced-label-formats>`.
+    
+
 .. py:method:: LookupBase.get_item_id(item)
 
     This is second of three formatting methods. The id is the value that will eventually
     :param value: The user given value.
     :return: The new item created from the item.
 
+.. _lookup-format-item:
+
 .. py:method:: LookupBase.format_item(item)
 
     By default `format_item` creates a dictionary with the three keys used by
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.