collective.contact.contactlist 2.0

==========================================================================
collective.contact.contactlist
==========================================================================

This add-on is part of the ``collective.contact.*`` suite. For an overview and a demo of these suite, see `collective.contact.demo <https://github.com/collective/collective.contact.demo>`__.

Users can can manage lists of contacts.
Adds an action to search and add a content to an existing or a new list.

Lists handles any contact type: organization, person or held position.


Installation
============

You need to turn on Member folder creation.

API
===

An helper api to manage contact lists: ::

def extend_list(contact_list, contacts):
"""Add contacts to a contact list
@param contact_list: object - The contact list object
@param contacts: objects - A list of contact objects
@return: objects - the list of contacts that have been actually added
"""

def replace_list(contact_list, contacts):
"""Replace the contacts of a contact list
@param contact_list: object - The contact list object
@param contacts: objects - A list of contact objects
@return: objects - the list of contacts that have been actually added
"""

def get_contacts(*contact_lists, **kwargs):
"""Get the contacts from one or many contact list(s)
kwargs can have an 'operator' option ('and' or 'or')
so we make union or intersection of lists
default is 'or'
"""


Vocabularies
============

- `collective.contact.contactlist.lists`: all lists user can see.
Lists shared to user are distinguished with owner's name.
- `collective.contact.contactlist.alllists`: all lists user can view, without distinction,
- `collective.contact.contactlist.editablelists`: all lists user can edit,
- `collective.contact.contactlist.mylists`: all lists created by user,
- `collective.contact.contactlist.addtolist`: all lists user can edit + list creation option
- `collective.contact.contactlist.vocabularies`: vocabulary of all previous vocabularies.


Integration with collective.contact.facetednav
==============================================

If you have collective.contact.facetednav installed,
if you have enabled contact selection on your faceted navigation
you can batch select contacts and add them to lists

You have a new widget "contacts list", wich display your lists.
It filters your results on the contents of the lists you have selected.

Compatible with eea.facetednav > 10

Use ContactListSourceBinder
===========================

When you write a schema,
you can filter choices of a ContactChoice (or ContactList) field on the contacts of one or many lists: ::

birthday_guests = ContactList(
title=u"Birthday guests",
value_type=ContactChoice(
source=ContactListSourceBinder(
contact_lists_query={'Subject': 'Friends'}),
contact_lists_operator='or',
portal_type=("person",),
)
)
)

This works like ContactSourceBinder from collective.contact.widget, but it also gets a
countact_lists_query parameter, wich is a catalog query dictionnary. Contacts displayed by formwidget
query are filtered on the union or intersection (depending on contact_lists_operator) of the lists we get using this query.


Tests
=====

This add-on is tested using Travis CI. The current status of the add-on is :

.. image:: https://secure.travis-ci.org/collective/collective.contact.contactlist.png
:target: http://travis-ci.org/collective/collective.contact.contactlist

Contributors
============

- Thomas Desvenain, thomas.desvenain@gmail.com
Changelog
=========


2.0 (2019-04-24)
----------------

- Made it compatible with eea.facetednavigation >= 10.0. Branch 1.x is compatible with eea.facetednavigation < 10.0
[sgeulette]

1.3 (2018-11-13)
----------------

- 'collective.contact.contactlist.lists' vocabulary is sorted by title when creators are different.
+ few fixes on list order
[thomasdesvenain]


1.2 (2017-01-17)
----------------

- Test eea widget.
[thomasdesvenain]

- API: Added a source binder that allows developers
to restrict ContactChoice fields on contents of contact lists.
[thomasdesvenain]

- get_contacts with 'and' operator was broken.
[thomasdesvenain]

- Minor optimizations and PEP8.
[thomasdesvenain]

- API: deprecate update_list function and create extend_list instead,
which is less ambiguous.
[thomasdesvenain]

- Fix get_contacts API for empty list
[ebrehault]


1.1 (2016-09-23)
----------------

- More robust unit tests.
[thomasdesvenain]

- Add get_lists_for_contact method to get all lists that contain contact.
[cedricmessiant]

- Fix relations.
[cedricmessiant]

- Put 'Create a new list' on top of the select widget.
[cedricmessiant]

- Fix update_list API for empty list
[ebrehault]

- Fix permissions in API
[ebrehault]


1.0 (2014-06-16)
----------------

- Initial release.
[tdesvenain]