Metadata-Version: 1.1
Name: django-ucamlookup
Version: 1.0
Summary: A Django module for the University of Cambridge Lookup service
Home-page: https://git.csx.cam.ac.uk/x/ucs/u/amc203/django-ucamlookup.git
Author: Information Systems Group, University Information Services, University of Cambridge
Author-email: information-systems@ucs.cam.ac.uk
License: MIT
Description: Introduction
        ============
        
        django-ucamlookup is a library which provides useful methods and
        templates to integrate your `Django <https://www.djangoproject.com/>`__
        application with the University of Cambridge University `Lookup
        service <https://www.lookup.cam.ac.uk/>`__.
        
        Use
        ---
        
        Install django-ucamlookup using pip:
        
        .. code:: bash
        
            pip install django-ucamlookup
        
        Add django-ucamlookup to your installed applications in your project
        configuration settings.py:
        
        .. code:: python
        
                INSTALLED_APPS=(
                ...
                    'ucamlookup', 
                ...
                ),
        
        and the urls entries in the urls.py file:
        
        .. code:: python
        
                urlpatterns = patterns(
                ...
                    # lookup/ibis urls
                    url(r'^ucamlookup/', include('ucamlookup.urls')),
                ...
                )
        
        Requirements and warning
        ------------------------
        
        This module will only work inside the University of Cambridge network.
        Make sure your users are authenticated as University of Cambridge users
        (you can use the django-ucamwebauth module) or you will be exposing
        personal data to non authorised users.
        
        Lookup User
        -----------
        
        django-ucamlookup modifies a User object each time is going to be saved,
        either new or update, and assigns to its *last\_name* property the
        visible name from lookup for that user. The username is used to search
        for this user in lookup.
        
        Lookup Group
        ------------
        
        django-ucamlookup includes a new model called LookupGroup that it is
        used to cache lookup models. It is used to store the lookup group id and
        its name, and therefore used to reduce the number of call to the lookup
        service. It can also be used to create relation with other models. For
        example, let's say we have a model called Secret and we only want to let
        access to it to users inside a certain group or groups. We will create a
        ManyToMany relation from Secrets to LookupGroup.
        
        The name of the group is retrieve from the lookup service each time the
        group is saved (new or updated). The name is stored in the *name*
        property of the class and the id of the lookup group is stored in
        *lookup\_id*.
        
        It is important to say that this model is not used to cache relations
        between lookup users and lookup groups. These relations are always
        queried to the live lookup service. The model is only used to let the
        developer make relations 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.
        
        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*:
        
        .. code:: python
        
                {% include 'ucamlookup_users.html' with input_tag_id="lookup_users" 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.
        
        .. code:: python
        
                {% 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.
        
        The same will work for lookup groups, just substitute user by group in
        the id and in the include.
        
        Admin interface
        ---------------
        
        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 admin wants to
        add a new user to the app.
        
        These input forms allow to search for name and crsid in the case of a
        new user and for name in the case of a lookup group.
        
        Available functions
        -------------------
        
        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
        
        *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 the user passed by
        parameters will be shown first in the list returned
        
        *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.
        
        The last two methods can be used to add institutions to a model and show
        the name instead of the code in the admin interface
        
        .. code:: python
        
            class MyModelAdmin(ModelAdmin):
                all_institutions = get_institutions()
                
                model = MyModel
                list_display = ('institution', )
                list_filter = ('institution_id', )
        
                def institution(self, obj):
                    return get_institution_name_by_id(obj.institution_id, self.all_institutions)
                    
                institution.admin_order_field = 'institution_id'
        
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
