Mark Lavin  committed 2b6740a

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

  • Participants
  • Parent commits a038570
  • Branches default

Comments (0)

Files changed (2)

File 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 <>`_
 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/
+        :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.

File docs/lookups.rst

     :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