Metadata-Version: 1.0
Name: js.deform
Version: 0.9.8
Summary: Fanstatic packaging of deform
Home-page: https://github.com/Kotti/js.deform
Author: Andreas Kaiser
Author-email: disko@binary-punks.com
License: BSD
Description: 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)
          - 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.
        
Platform: UNKNOWN
