js.deform 0.9.8

Fanstatic packaging of deform

js.deform

Introduction

This library packages deform for fanstatic.

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)

• TinyMCE (http://pypi.python.org/pypi/js.tinymce)

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()

This will include Deform’s default form.css as well as the beautify.css. If you only want one or the other, you can need them like so:

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

>>> from js.deform import deform_beautify_css
>>> deform_beautify_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)

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

>>> needed = fanstatic.get_needed()
>>> needed.resources()
[<Resource 'css/beautify.css' in library 'deform'>, <Resource 'css/form.css' in library 'deform'>, <Resource 'jquery.js' in library 'jquery'>, <Resource 'tinymce.js' in library 'tinymce'>, <Resource 'scripts/deform.js' in library 'deform'>]

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()
>>> needed.resources()
[]
>>> html = form.render()
>>> needed = fanstatic.get_needed()
>>> needed.resources()
[<Resource 'css/beautify.css' in library 'deform'>, <Resource 'css/form.css' in library 'deform'>, <Resource 'jquery.js' in library 'jquery'>, <Resource 'tinymce.js' in library 'tinymce'>, <Resource 'scripts/deform.js' in library 'deform'>]

CHANGES

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.