Updated the README to reflect the changes in v3.

README.md

@@ -90,47 +90,72 @@ between models that include lookup groups and cache the name of the group.
 
 ## Template macros
 
-Two macros are available to be used in a template: ucamlookup_users, and ucamlookup_groups. These macros have 
-javascript functions that will modify a html input tag to an interactive ajax box with interaction to the lookup 
-service that will let the user use autocomplete and search for lookup users and groups.
+Two macros are available to be used in a template: `ucamlookup_users`, and `ucamlookup_groups`.
+These macros have javascript functions that will tranform an html `select` tag into an interactive
+selection control which will interact with the lookup service and will let the user use autocomplete
+and search for lookup users and groups.
 
-If you want to include an input box to let the user search and introduce a single user or a list of users, use the 
-ucamlookup_users macro. You should pass as parameters to the macro the html input tag *id* that you want to modify/use
-and if you want to let the user select one or more users with the parameter *multiple*:
+To include a selection control that can search and add a single or list of users, use the
+`ucamlookup_users` macro. You should pass the html `select` `id` as a parameter to the macro.
+If you want the control to add more than one user you should set the `multiple` parameter.
 
-```python
-    {% include 'ucamlookup_users.html' with input_tag_id="lookup_users" multiple=true user_list="authors" %}
+```html
+    <select id="authors_id" name="authors" multiple="multiple"></select>
+
+    {% include 'ucamlookup_users.html' with input_tag_id="authors_id" multiple=true placeholder='Select an author' %}
 ```
 
-You can optionally override the placeholder text.
+As seen in the example you can set the placeholder text with `placeholder` parameter.
 
-If you want to show existing records in the input tag you will need to pass to the view the list of crsids. This list 
-needs to be passed inside a dictionary called *lookup_lists*. The key entry name of the dictionary where the list is
-located it is passed to the macro using the variable *user_list* as shown previously. In this example:
+If you want to show existing `User` records in the input tag you should use the `option` tag in
+the template as in the following example:
 
-```python
-    lookup_lists = {
-        'authors': post.users.all(),
-    }
+```html
+    <select id="authors_id" name="authors" multiple="multiple">
+        {% for user in authors %}
+            <option selected=selected value="{{ user.username }}">
+                {{user.last_name}} ({{ user.username }})
+            </option>
+        {% endfor %}
+    </select>
+
+    {% include 'ucamlookup_users.html' with input_tag_id="authors_id" multiple=true %}
 ```
 
-You will also have to include the following macro in the head of your template to load the js and css files 
-associated. These macros require jquery if you want to include your own jquery library or you are already using it in
-your template use the parameter *jquery* to specify it.
+You will also have to include the following macro in the html `header` of your template to load
+the js and css files  associated. These macros require jquery if you want to include your own 
+jquery library or you are already using it in your template use the parameter `jquery` to specify
+it.
 
-```python
+```html
     {% include 'ucamlookup_headers.html' with jquery=True %}
 ```
 
-And your input tag will be transform into an ajax box that allows the user to search for users using lookup either
-using their username or their complete name. A list of crsids will be sent as the value of the input tag.
+Your `select` tag will be transform into a selection control that allows the user to search for
+users with either using their username or complete name. When the form is submitted, a list of
+crsids will be sent with the request as with any normal `select` tag.
 
-The same will work for lookup groups, just substitute user by group in the id and in the include.
+If you need to customise the style of the control, you can use the `ucamlookup-user-container`
+class for the container part and the `ucamlookup-user-dropdown` class for the dropdown parrt of
+the control.
 
+The same approach will also work for lookup groups, as in the following example:
+
+```html
+    <select id="groups_id" name="groupids" multiple="multiple">
+        {% for group in groups %}
+            <option selected=selected value="{{ group.lookup_id }}">
+                {{group.name}}
+            </option>
+        {% endfor %}
+    </select>
+    
+    {% include 'ucamlookup_groups.html' with input_tag_id="groups_id" multiple="true" %}
+```
 
 ## Admin interface
 
-The admin interface is tunned to add managing options for the LookupGroup model. The *add* option will show the same
+The admin interface is tunned to add managing options for the LookupGroup model. The **add** option will show the same
 ajax-lookup-integrated-input as the template macros described above.
 
 It also changes the add form for the user and it also shows an interactive ajax lookup-integrated input form when the
@@ -144,22 +169,29 @@ group.
 
 The module also provides some useful functions to use in your app that do all the calls to the lookup service needed.
 
-*get_group_ids_of_a_user_in_lookup(user)*: Returns the list of group ids of a user
+`get_group_ids_of_a_user_in_lookup(user)`: Returns the list of group ids of a user
 
-*user_in_groups(user, lookup_groups)*: Check in the lookup webservice if the user is member of any of the groups in the 
+`user_in_groups(user, lookup_groups)`: Check in the lookup webservice if the user is member of any of the groups in the 
 LookupGroup list passed by parameter. Returns True if the user is in any of the groups or False otherwise
 
-*def get_institutions(user=None)*: Returns the list of institutions using the lookup ucam service. The institutions of 
+`get_institutions(user=None)`: Returns the list of institutions using the lookup ucam service. The institutions of 
 the user passed by parameters will be shown first in the list returned
 
-*validate_crsids(crsids_text)*: It receives a list of crsids (comming from input tag from the template macros described 
-previously) [wich format is separated by commas and with no spaces in between] and returns a list of Users corresponding
-to the crsids passed.
+`validate_crsid_list(crsids)`: It receives a list of crsids (from the `select` tag from the
+template macros described previously) and returns a list of `User` objects corresponding to the
+crsids passed.
+
+`get_or_create_user_by_crsid(crsid)`: Returns the `User` object corresponding to the `crsid` 
+passed. If it does not exists in the database, it is created.
+
+`validate_groupid_list(groupids)`: It receives a list of groupids (from the `select` tag from the
+template macros described previously) and returns a list of `LookupGroup` objects corresponding to
+the crsids passed.
 
-*get_or_create_user_by_crsid(crsid)*: Returns the User corresponding to the crsid passed. If it does not exists in the 
-database, it is created.
+`get_or_create_group_by_groupid(groupid)`: Returns the `LookupGroup` object corresponding to the
+`groupid` passed. If it does not exists in the database, it is created.
 
-*get_institution_name_by_id(institution_id, all_institutions=None)*: Returns the name of an institution by the id 
+`get_institution_name_by_id(institution_id, all_institutions=None)`: Returns the name of an institution by the id 
 passed. If all_institutions is passed (the result from get_institutions) then the search is done locally using this 
 list instead of a lookup call.