collective.z3cform.widgets 1.0rc1

**************************
collective.z3cform.widgets
**************************

.. contents:: Table of Contents

Life, the Universe, and Everything
----------------------------------

A widget package for Dexterity projects.

.. Warning::
This package will no longer be actively maintained.
Take a look at `plone.app.widgets`_ for an alternative set of widgets.

collective.z3cform.widgets provides the following widgets:

**EnhancedTextLinesFieldWidget**
This widget is an ajaxified version of the TextLinesFieldWidget that will
allow creation, sort, update and deletion of text lines; degrades to
<textarea> if JavaScript is not enabled.

.. image:: https://github.com/collective/collective.z3cform.widgets/raw/master/enhancedtextlines.png
:align: center
:height: 143px
:width: 600px

This widget uses the `jQuery TaskPlease`_ plugin.

**TokenInputFieldWidget**
TokenInputFieldWidget allows your users to select multiple items from
portal Subjects list , using autocompletion as they type to find each
item. You may have seen a similar type of text entry when filling in the
recipients field sending messages on `Facebook`_. This widget will degrade
to <textarea> if JavaScript is not enabled.

.. image:: https://github.com/collective/collective.z3cform.widgets/raw/master/tokeninput.png
:align: center
:height: 110px
:width: 600px

This widget uses the `jQuery Tokeninput`_ plugin.

If you install collective.z3cform.widgets in a Plone site it will replace
every ICategorization subjects field's widget of any Dexterity-based
content type with this one.

**MultiContentSearchFieldWidget**
A widget to add a dynamic list of objects. This works as a widget for
related items field so it must be used like this:

.. code-block::

relatedItems = RelationList(
title=_(u'label_related_items', default=u'Related Items'),
default=[],
value_type=RelationChoice(title=u"Related",
source=ObjPathSourceBinder(portal_type='Document')),
required=False,
)
form.widget(relatedItems=MultiContentSearchFieldWidget)

The parameters passed to the ObjPathSourceBinder class are used to filter
the search of elements to relate to. If no parameters are passed, a tree
structure is shown in the widget.

**SimpleRichTextWidget**
A lightweight and unbloated Rich Text Editor (RTE / WYSIWYG). These
parameters can be configured::

'iframe_height': height in pixels,
'format_block': 'true' or 'false',
'bold': 'true' or 'false',
'italic': 'true' or 'false',
'unordered_list': 'true' or 'false',
'link': 'true' or 'false',
'image': 'true' or 'false',
'allow_disable': 'true' or 'false'

This widget uses the `jQuery RTE`_ plugin.

Mostly Harmless
---------------

.. image:: http://img.shields.io/pypi/v/collective.z3cform.widgets.svg
:target: https://pypi-hypernode.com/pypi/collective.z3cform.widgets

.. image:: https://img.shields.io/travis/collective/collective.z3cform.widgets/master.svg
:target: http://travis-ci.org/collective/collective.z3cform.widgets

.. image:: https://img.shields.io/coveralls/collective/collective.z3cform.widgets/master.svg
:target: https://coveralls.io/r/collective/collective.z3cform.widgets

Got an idea? Found a bug? Let us know by `opening a support ticket`_.

Don't Panic
-----------

Installation
^^^^^^^^^^^^

To enable this product in a buildout-based installation:

1. Edit your buildout.cfg and add ``collective.z3cform.widgets`` to the list
of eggs to install::

[buildout]
...
eggs =
collective.z3cform.widgets

After updating the configuration you need to run ''bin/buildout'', which will
take care of updating your system.

Go to the 'Site Setup' page in a Plone site and click on the 'Add-ons' link.

Check the box next to ``collective.z3cform.widgets`` and click the 'Activate'
button.

Note: You may have to empty your browser cache and save your resource
registries in order to see the effects of the product installation.

New fields
^^^^^^^^^^

**EnhancedTextLinesFieldWidget**
To use this widget we must use a List field or a Tuple field with the
value_type as an schema.TextLine() like this::

.. code-block::

from collective.z3cform.widgets.enhancedtextlines import EnhancedTextLinesFieldWidget

form.widget(options = EnhancedTextLinesFieldWidget)
options = schema.Tuple(
title=_(u"Options"),
value_type=schema.TextLine(),
missing_value=(),
)

**TokenInputFieldWidget**
To use this Widget we must use a List field or a Tuple field with the
value_type as a schema.TextLine() like this::

.. code-block::

from collective.z3cform.widgets.token_input_widget import TokenInputFieldWidget

form.widget(subjects=TokenInputFieldWidget)
subjects = schema.List(
title=_(u"Categories"),
value_type=schema.TextLine(),
default=[],
)

**MultiContentSearchFieldWidget**
The parameters passed to the ObjPathSourceBinder class are used to filter
the search of elements to relate to.. if none parameter are passed, a tree
structure is shown in the widget::

.. code-block::

from collective.z3cform.widgets.multicontent_search_widget import MultiContentSearchFieldWidget

form.widget(relatedItems=MultiContentSearchFieldWidget)
relatedItems = RelationList(
title=_(u"Related Items"),
default=[],
value_type=RelationChoice(title=u"Related",
source=ObjPathSourceBinder(portal_type='Document')),
)

**SimpleRichTextWidget**
TBA

Override existing fields
^^^^^^^^^^^^^^^^^^^^^^^^

TBA

Future widgets
--------------

The following widgets will be available in this package in the near future:

- widget to select an option from a list; this widget will degrade to <select>
if JavaScript is not enabled.

- widget to select multiple options from a list; this widget will degrade to
<select> if JavaScript is not enabled.

This widgets will probably use the `Chosen`_ plugin.

Browsers supported
------------------

All modern browsers should be supported (Mozilla Firefox 3.0+, Google Chrome
7.0+, Apple Safari 4.0+, Opera 10.0+ and Microsoft Internet Explorer 9.0+).

See also
--------

Not entirely unlike
-------------------

`collective.z3cform.datagridfield`_
Version of DataGridField for use with Dexterity / z3c.form.

`plone.app.widgets`_
A revamp of Plone widgets, it does this by overriding the widgets of some
of the fields in Plone.

.. _`jQuery TaskPlease`: https://github.com/Quimera/tasksplease
.. _`jQuery Tokeninput`: http://loopj.com/jquery-tokeninput/
.. _`Chosen`: http://harvesthq.github.com/chosen/
.. _`Facebook`: http://www.facebook.com/
.. _`opening a support ticket`: https://github.com/collective/collective.z3cform.widgets/issues
.. _`eea.tags`: https://github.com/collective/eea.tags
.. _`jQuery RTE`: http://code.google.com/p/rte-light
.. _`collective.z3cform.datagridfield`: http://pypi.python.org/pypi/collective.z3cform.datagridfield
.. _`plone.app.widgets`: https://github.com/plone/plone.app.widgets

Share and Enjoy
---------------

``collective.z3cform.widgets`` would not have been possible without the
contribution of the following people:

- Franco Pellegrini
- Gonzalo Almeida
- Silvestre Huens
- Héctor Velarde
- Cleber J. Santos
- João S. O. Bueno
- Juan Pablo Giménez

You can find an updated list of package contributors on `GitHub`_.

Development sponsored by Open Multimedia.

.. _`GitHub`: https://github.com/collective/collective.z3cform.widgets/contributors

Changelog
---------

There's a frood who really knows where his towel is.

1.0rc1 (2015-07-29)
^^^^^^^^^^^^^^^^^^^

- Fix JS to be jQuery 1.9 compat
[simahawk]

- Make CSS resources render as <link />
[simahawk]

- Add French translations.
[sophiejazwiecki]

- Fix i18n.
[vincentfretin]


1.0b11 (2014-11-27)
^^^^^^^^^^^^^^^^^^^

- Rename ``formwidget_autocomplete_new_value`` function in
``related.js`` to ``related_widget_new_value``. Has been just copied from
``plone.formwidget.autocomplete``.
[rnixx]

- remove zope.i18n from package dependencies in order to avoid
conflicting zcml with between zope.i18n and Zope2 Publihser
i18n.zcml
[jensens]

- Fix package dependencies.
[hvelarde]


1.0b10 (2014-10-08)
^^^^^^^^^^^^^^^^^^^

- Remove dependency on unittest2 (test run under Python 2.7 only).
[hvelarde]

- Remove dependency on Pillow. [hvelarde]

- Drop support for Plone 4.1. [hvelarde]

- Install plone.formwidget.contenttree resources to avoid duplication of
related items field (fixes `#69 in collective.nitf`_). [jpgimenez]

- Make TokenInputFieldWidget be case-insensitive when suggesting Keywords
[pbauer]


1.0b9 (2013-05-02)
^^^^^^^^^^^^^^^^^^

- Fixed problem Multicontent (type checkbox gets set to radio). [Kosi81]


1.0b8 (2013-04-24)
^^^^^^^^^^^^^^^^^^

- Rename upgrade step profile. Never, ever name a profile with a number as
first character and never, ever work for 3 weeks in a row. [hvelarde]


1.0b7 (2013-04-19)
^^^^^^^^^^^^^^^^^^

- Refactor JSON view to access the catalog only when there's a query and limit
the number of tokens returned to 10 (fixes `#32`_). [hvelarde]

- TokenInputFieldWidget now use ajax to bring the subjects. [flecox]

- Refactor method used in upgrade step to increase its performance: we
recatalog only offending objects and update only the Subjects index.
[hvelarde]

- Trim Subjects in TokenInputFieldWidget; an upgrade step for updating all
offending objects in the catalog is included (fixes `#33`_). [flecox]

- Fixed IE8 problem with 2 simultantious checked radio buttons. [Kosi81]


1.0b6 (2013-04-09)
^^^^^^^^^^^^^^^^^^

- Update package documentation. [hvelarde, jpgimenez]

- TokenInputFieldWidget now replaces subjects widget for any Dexterity-based
content types on the site, but only if the package is installed. [jpgimenez]

- Tested for compatibility with Dexterity 2.0 and Plone 4.3. [hvelarde]

- Plone 4.1 is no longer supported (closes `#25`_). [hvelarde]

1.0b5 (2013-03-25)
^^^^^^^^^^^^^^^^^^

- Remove dependency on zope.i18n as it is causing ConfigurationConflictError
(issue `#28`_).
[hvelarde]


1.0b4 (2013-03-23)
^^^^^^^^^^^^^^^^^^

- Fix package dependencies to be Plone 4.3 compatible. [hvelarde]

- Fix the rendered URLs of related items in the MultiContentSearchWidget in
display_mode to be actual URLs, not the physical path inside Zope.
[leorochael]


1.0b3 (2013-01-14)
^^^^^^^^^^^^^^^^^^

- Refactoring of the SimpleRichTextWidget to make it work in an AJAX call.
[quimera]

- Do not mix unicode and strings in TokenInputWiget editing (fixes `#20`_).
[jsbueno]

- Checking if contenttree js code should be run or not. [Flecox]

- Test compatibility with Plone 4.3. [hvelarde]

- Add Pillow as a dependency of the package. [hvelarde]

- Import ViewPageTemplateFile from zope.browserpage to avoid dependency on
zope.app.pagetemplate.
[hvelarde]


1.0b2 (2012-09-27)
^^^^^^^^^^^^^^^^^^

- New field and widget included which uses the rte-light editor [frapell]


1.0b1 (2012-09-16)
^^^^^^^^^^^^^^^^^^

- Added Dutch translation. [kingel]

- Correction in tasks layout. [quimera]

- Spinners for the related widget so you know is working. [frapell]


1.0a4 (2012-09-04)
^^^^^^^^^^^^^^^^^^

- Spanish translation was updated; Brazilian Portuguese translation was
added. [hvelarde]

- Resources are only loaded for logged in users. [quimera]

- Ordered search catalog in MultiContentSearchFieldWidget. [flecox]

- Infinite Scroll in MultiContentSearchFieldWidget (fixes `#10`_). [flecox]

- Fix bug when searching with no results in MultiContentSearchFieldWidget.
[flecox]

- Updating taskplease library in EnhancedTextLinesFieldWidget (fixes `#13`_).
[flecox]


1.0a3 (2012-06-15)
^^^^^^^^^^^^^^^^^^

- Updated package documentation. [hvelarde]

- Fixing style in EnhancedTextLinesFieldWidget and TokenInputFieldWidget.
[flecox]

- TasksWidget was renamed to EnhancedTextLinesFieldWidget (fixes `#7`_).
[hvelarde]

- Changing the name of RelatedContentWidget to MultiContentSearchFieldWidget.
[flecox]


1.0a2 (2012-05-18)
^^^^^^^^^^^^^^^^^^

- Updated package documentation. [hvelarde]

- Changing the name of KeywordWidget to a better name TokenInputFieldWidget.
[flecox]

- Now you can add a token just by pressing Enter. [flecox]


1.0a1 (2012-05-04)
^^^^^^^^^^^^^^^^^^

- Initial release.

.. _`#7`: https://github.com/collective/collective.z3cform.widgets/issues/7
.. _`#10`: https://github.com/collective/collective.z3cform.widgets/issues/10
.. _`#13`: https://github.com/collective/collective.z3cform.widgets/issues/13
.. _`#20`: https://github.com/collective/collective.z3cform.widgets/issues/20
.. _`#25`: https://github.com/collective/collective.z3cform.widgets/issues/25
.. _`#28`: https://github.com/collective/collective.z3cform.widgets/issues/28
.. _`#32`: https://github.com/collective/collective.z3cform.widgets/issues/32
.. _`#33`: https://github.com/collective/collective.z3cform.widgets/issues/33
.. _`#69 in collective.nitf`: https://github.com/collective/collective.nitf/issues/69