js.deform 2.0.14
Fanstatic packaging of deform
License: BSD

js.deform
=========

.. image:: https://travis-ci.org/fanstatic/js.deform.svg?branch=master
    :target: https://travis-ci.org/fanstatic/js.deform

Introduction
------------

This library packages `deform`_ for `fanstatic`_.

.. _`fanstatic`: http://fanstatic.org
.. _`deform`: http://docs.pylonsproject.org/projects/deform/

This requires integration between your web framework and ``fanstatic``,
and making sure that the original resources (shipped in the ``resources``
directory in ``js.deform``) are published to some URL.

Included resources
------------------

``js.deform`` is different from most ``js.`` packages in that it doesn't
include any resources itself.  It references the resources from ``deform``
instead.  The only resources that are made available from ``js.deform``
are ``deform.js``, ``form.css`` and ``beautify.css``.  All other resources
that are part of the ``deform`` distribution are available separately:

  - jQuery (http://pypi.python.org/pypi/js.jquery)
  - jQueryUI (http://pypi.python.org/pypi/js.jqueryui)
  - jQueryUI Timepicker Addon (http://pypi.python.org/pypi/js.jquery_timepicker_addon)
  - jQuery Form (http://pypi.python.org/pypi/js.jquery_form)
  - jquery.maskedinput (http://pypi.python.org/pypi/js.jquery_maskedinput)
  - jquery-maskmoney (http://pypi.python.org/pypi/js.jquery_maskmoney)
  - jQuery Sortable (http://pypi.python.org/pypi/js.jquery-sortable)
  - TinyMCE (http://pypi.python.org/pypi/js.tinymce)
  - Typeahead (http://pypi.python.org/pypi/js.typeahead)

How to use?
===========

JS
--

You can import ``deform_js`` from ``js.deform`` and ``need``
it where you want these resources to be included on a page::

  >>> from js.deform import deform_js
  >>> deform_js.need()

CSS
---

You can import ``deform_css`` from ``js.deform`` and ``need``
it where you want these resources to be included on a page::

  >>> from js.deform import deform_css
  >>> deform_css.need()

All
---

You can import ``deform`` from ``js.deform`` and ``need``
it where you want these resources to be included on a page::

  >>> from js.deform import deform
  >>> deform.need()

This automatically includes all of Deform's CSS and JS and is
the equivalent to needing both ``deform_js`` and ``deform_css``
as described above.

Auto-needing Resources
----------------------

You can avoid needing to manually import and ``need()`` each
Fanstatic dependency of your ``Deform`` form by use of the ``auto_need``
function provided in this package.

  >>> import js.deform
  >>> import colander
  >>> import deform

  >>> schema = colander.Schema()
  >>> form = deform.Form(schema)
  >>> js.deform.auto_need(form)

By doing the above, any widget requirements - including those of `Deform`
itself - will be included for Fanstatic.

So, you may have a form that requires a ``deform.widget.RichTextWidget``
for one of its fields.  This type of widget requires resources relating to
`TinyMCE`.  ``js.deform.auto_need`` will use ``js.tinymce`` for this
requirement.

This is all best illustrated in the following example.

Initialise Fanstatic so we can see resources being included:

  >>> import fanstatic
  >>> dummy = fanstatic.init_needed()
  >>> len(fanstatic.get_needed().resources())
  0

Create a demonstration schema and form:

  >>> schema = colander.Schema()
  >>> node = colander.SchemaNode(colander.String(),
  ...                            widget=deform.widget.RichTextWidget())
  >>> schema.add(node)
  >>> form = deform.Form(schema)

Check the form's resource requirements:

  >>> form.get_widget_requirements()
  [('deform', None), ('tinymce', None)]

Ask ``auto_need`` to include the resources for us:

  >>> js.deform.auto_need(form)
  >>> needed = fanstatic.get_needed()

So we can now see the resources that have been included:

  >>> from js.jquery import jquery
  >>> jquery in needed.resources()
  True
  >>> from js.tinymce import tinymce
  >>> tinymce in needed.resources()
  True
  >>> from js.deform import deform_js
  >>> deform_js in needed.resources()
  True

The above resources will automatically be included on your page once
Fanstatic is configured accordingly.


Patching deform to automatically need the resources for a widget
----------------------------------------------------------------

If you don't want to have to call ``auto_need(form)`` for every form
instance in your application, you can patch deform (e.g. on application
startup) to automagically ``need()`` everything for you where required.
If you use Pyramid adding ``js.deform`` to your ``pyramid.includes``
is enough.

Let's reinit fanstatic...

  >>> dummy = fanstatic.init_needed()
  >>> len(fanstatic.get_needed().resources())
  0

...and patch ``deform`` this time:

  >>> from js.deform import includeme
  >>> includeme()

Note that you only have too do this once, e.g on application startup.

Now do the same as above, but without calling auto_need.  Note that
the ``need()`` calls are not issued before rendering the form.

  >>> schema = colander.Schema()
  >>> node = colander.SchemaNode(colander.String(),
  ...                            widget=deform.widget.RichTextWidget())
  >>> schema.add(node)
  >>> form = deform.Form(schema)
  >>> needed = fanstatic.get_needed()
  >>> len(needed.resources())
  0
  >>> html = form.render()
  >>> needed = fanstatic.get_needed()

Again all resources have been included for us:

  >>> jquery in needed.resources()
  True
  >>> tinymce in needed.resources()
  True
  >>> deform_js in needed.resources()
  True

CHANGES
=======

2.0.14 (2020-09-08)
-------------------

- Add support for Python 3.6 up to 3.9 and PyPy3.

- Drop support for Python 3.4 and 3.5.

- Adapt to ``deform >= 2.0.11``.


2.0.3 - 2016-11-20
------------------

- Depend on deform 2.0.3.

2.0a2-3 2015-01-31
------------------

- Add mapping for ``select2``.

------------------
2.0a2-1 2014-05-13
------------------

- Use the typeahead bundled with deform instead of ``js.typeahead`` as the
  latter fails on Python 2.6.

2.0a2 2014-05-13
----------------

- Depend on deform 2.0a2 (Bootstrap 3).
  THIS IS NOT BACKWARD COMPATIBLE AND WILL BREAK WITH OLDER DEFORMS!

0.9.8 - 2013-11-19
------------------

- Resolve ``modernizr`` dependency with js.modernizr; this was introduced
  in deform-0.9.6.

0.9.7 - 2013-03-14
------------------

- Add ``deform_basic`` to the available resource groupings. Using this
  includes just the basic CSS and JavaScript, without the 'beautify' CSS.
  [davidjb]

0.9.6 - 2013-02-23
------------------

- No changes.

0.9.5-6
-------

- Fix a bug that caused requirements not to be loaded on ValidationFailure
  (thanks icemac!).

0.9.5-5
-------

- Include ``js.jquery_form`` dependency in setup.py (thanks icemac!).

0.9.5-4
-------

- Make all items in resource_mapping a list, so that third party
  packages (e.g. kotti_tinymce) can append resources.

0.9.5-3
-------

- Add an includme for easy using in Pyramid projects.

- Change patching to only patch deform.form.Form instead of individual
  widgets.

0.9.5-2
-------

- Add ``auto_need`` method for automatically including Fanstatic resources
  for a given Deform form instance.

- Add ``patch_deform`` function for automagically including Fanstatic
  resources.  This feature will vanish when deform gets a FormRender
  event which we can subscribe to.

0.9.5-1
-------

- Make the CSS resources available separately as well as combined with
  the JS resource.

0.9.5
-----

- Initial release.