Metadata-Version: 1.0
Name: grokcore.view
Version: 1.13.5
Summary: Grok-like configuration for Zope browser pages
Home-page: http://grok.zope.org
Author: Grok Team
Author-email: grok-dev@zope.org
License: ZPL
Download-URL: http://pypi.python.org/pypi/grok/
Description: This package provides support for writing browser pages for Zope
        and registering them directly in Python (without ZCML).
        
        .. contents::
        
        Setting up ``grokcore.view``
        ============================
        
        This package is essentially set up like the `grokcore.component`_
        package, please refer to its documentation for details.  The
        additional ZCML line you will need is::
        
          <include package="grokcore.view" file="meta.zcml" />
          <include package="grokcore.view" />
        
        Put the first line somewhere near the top of your root ZCML file (but
        below the line where you include ``grokcore.component``'s
        configuration) and the second line somewhere next to your other
        dependency includes.
        
        
        Examples
        ========
        
        Simple browser page
        -------------------
        
        A browser page is implemented by subclassing the
        ``grokcore.view.View`` baseclass.  At a minimum, a browser page must
        have
        
        1. an associated template (for a render() method, use CodeView)
        
        2. a context that it's registered for as a view
        
        3. a name (which is, if not specified explicitly, the class's name in
           lower case characters).
        
        A browser page that does not use a template but just outputs some computed
        data should subclass ``grokcore.view.CodeView``.  At a minimum, such a view
        must have
        
        1. a render() method
        
        2. a context that it's registered for as a view
        
        3. a name (which is, if not specified explicitly, the class's name in
           lower case characters).
        
        
        For example, the following class defines a view that's registered for
        all objects and simply prints "Hello World!".  This is done with a CodeView::
        
          import grokcore.view
          import zope.interface
        
          class Hello(grokcore.view.CodeView):
              grokcore.view.context(zope.interface.Interface)
        
              def render(self):
                  self.response.setHeader("Content-Type", "text/plain")
                  return "Hello World!"
        
        Here we've made use of the implicit name feature.  This class will be
        available as the ``hello`` view for all objects.  So for instance,
        you'll be able to invoke it with URLs like::
        
          http://localhost/some/obj/hello
        
        We could also have spelled this out explicitly::
        
          class Hello(grokcore.view.View):
              grokcore.view.context(zope.interface.Interface)
              grokcore.view.name('hello')
        
              ...
        
        Browser page with template
        --------------------------
        
        Of course, more than often a view should render HTML which you would
        construct using some sort of templating engine.  ``grokcore.view``
        comes with built-in support for Zope's PageTemplate engine.  By
        convention, PageTemplate templates end with the ``.pt`` extension.
        
        So let our ``Hello`` view render HTML instead of plain text, we remove
        the ``render()`` method from the class and instead we create a
        template, e.g. like so::
        
          <html>
          <body>
            <p>Hello <span tal:replace="request/principal/title" />!</p>
          </body>
          </html>
        
        This will greet a logged in user with his or her actual name.
        
        Such a template-using page is a subclass of ``grokcore.view.View``.
        
          import grokcore.view
          import zope.interface
        
          class Hello(grokcore.view.View):
              grokcore.view.context(zope.interface.Interface)
        
        
        To associate the template with the view, we have to put it in a
        certain place.  Let's say the ``Hello`` view class from above was in
        an ``app.py`` module.  Then we create an ``app_templates`` directory
        next to it and place the template file in there (the name of this
        directory can be customized with the ``templatedir`` directive, see
        below).  The file name can be anything as long as the extension is
        ``.pt``.  However, we can again make use of a convention here.  If we
        name the template like the class (except in lower case characters),
        then the template and the class are associated automatically.  If not,
        we would have to use the ``template`` directive on the view class to
        spell out the name of the template file explicitly.
        
        To cut a long story short, if we named it ``app_templates/hello.pt``,
        it would be found automatically.
        
        Static resources
        ----------------
        
        Browser pages often need additional static resources like CSS and JavaScript
        files. These can be conveniently placed into a directory called ``static`` in
        the package that contains the view code. When this directory exists it will
        automatically be registered as a resource directory. It then is available as
        the ``static`` variable in all views of this package and you can refer to files
        inside this directory like so::
        
          <img src="hello.png" tal:attributes="src static/hello.png" />
        
        DirectoryResource
        -----------------
        
        In addition to the very convenient "static resources", one can use more
        explicitly configured and flexible DirectoryResource components.
        DirectoryResource component allow for differentiating resources based on layers
        and names and provide a way to register resources in one package and make use
        of these resources in another package's views::
        
          class FooResource(grokcore.view.DirectoryResource):
              grokcore.view.path('foo')
        
        Or with an explicit name::
        
          class BarResource(grokcore.view.DirectoryResource):
              grokcore.view.name('bar')
              grokcore.view.path('bar')
        
        Registered for a layer::
        
          class BazResource(grokcore.view.DirectoryResource):
              grokcore.view.layer(ISomeLayer)
              grokcore.view.path('baz/qux')
        
        Layers and skins
        ----------------
        
        To define a browser layer, simply extend the ``IBrowserRequest``
        interface::
        
          class IGreenLayer(grokcore.view.IBrowserRequest):
              pass
        
        If you then wanted to define a skin, simply inherit from all the layer
        interfaces that should be in the skin and use the ``skin()`` directive
        to give the layer a name::
        
          class IGreenSkin(IGreenLayer, grokcore.view.IDefaultBrowserLayer):
              grokcore.view.skin('Green')
        
        To place a view on a layer, simply use the ``layer`` directive::
        
          class Hello(grokcore.view.View):
              grokcore.view.context(zope.interface.Interface)
              grokcore.view.layer(IGreenLayer)
        
              ...
        
        
        API overview
        ============
        
        Base classes
        ------------
        
        ``View``
            Base class for browser pages.  Use the ``context`` directive to
            specify the view's context.  Use the ``name`` directive to set the
            view's name; if not used, the view's name will be the class's name
            in lower case characters.  You may also use the ``template``
            directive to specify the name of the template file that should be
            associated with the view as well as the ``layer`` directive to
            specify which layer it should be on if not the default layer.
        
        ``CodeView``
            Base class for browser pages.  Use the ``context`` directive to specify
            the view's context.  Use the ``name`` directive to set the view's name; if
            not used, the view's name will be the class's name in lower case
            characters.  The ``layer`` directive specifies which layer it should be on
            if not the default layer.
        
        
        View API
        --------
        
        ``grokcore.view.View`` is a regular Zope browser page, so it behaves
        exactly like a regular browser page from the outside.  It provides a
        bit more to the developer using it as a base class, though:
        
        ``context``
            The view's context object.  This can be discriminated by using the
            ``context`` directive on the view class.
        
        ``request``
            The request object, typically provides ``IBrowserRequest``.
        
        ``response``
            The response object, typically provides ``IHTTPResponse``.
        
        ``static``
            Directory resource representing the package's ``static`` directory or None
            if no such directory was found during grokking.
        
        ``redirect(url)``
            Redirect to the given URL.
        
        ``url(obj=None, name=None, data=None)``
            Constructs a URL:
        
            * If no arguments are given, the URL to the view itself is
              constructed.
        
            * If only the ``obj`` argument is given, the URL to that object is
              constructed.
        
            * If both ``obj`` and ``name`` arguments are supplied, construct
              the URL to the object and append ``name`` (presumably the name
              of a view).
        
            Optionally, ``data`` can be a dictionary whose contents is added to
            the URL as a query string.
        
        Method for developers to implement:
        
        ``update(**kw)``
            This method will be called before the view's associated template
            is rendered.  If you therefore want to pre-compuate values for the
            template, implement this method.  You can save the values on
            ``self`` (the view object) and later access them through the
            ``view`` variable from the template.  The method can take
            arbitrary keyword parameters which are filled from request values.
        
        
        The CodeView class can have abovementioned ``update()`` method and
        additionally *has* to implement ``render()``
        
        ``render(**kw)`` 
            Return either an encoded 8-bit string or a unicode string.  The method can
            take arbitrary keyword parameters which are filled from request values.
        
        
        Directives
        ----------
        
        ``templatedir(dirname)``
             Module-level directive that tells the template machinery which
             directory to look in for templates that should associated with
             views in a particular module.  If not used, it defaults to
             ``<module_name>_templates``.
        
        ``template(filename_wo_ext)``
            Class-level directive that specifies the name a template file
            that's associated with a view class, *without* the file extension.
            If not used, it defaults to the class's name in lower case
            characters.  Only used for View, not CodeView.
        
        ``layer(layer_interface)``
            Class-level directive that defines which layer the view is
            registered on.  If not used, it defaults to the
            ``IDefaultBrowserLayer``.
        
        ``skin(skin_name)``
            Directive used on a layer interface to register it as skin using a
            human-readable name (``skin_name``).
        
        ``path(relative_or_absolute_path)``
            Directove used in a DirectoryResource registration to point to a non-
            package directory(hierarchy) containing resources like images, css files,
            etc.
        
        Other
        -----
        
        ``url(request, obj, name=None, data=None)``
            Generate the URL to an object, with an optional view name
            attached.  The ``data`` argument can be a dictionary whose
            contents is converted into the a query string that's appended to
            the URL.
        
        ``PageTemplate(template_code)``
            Create an inline PageTemplate object.
        
        ``PageTemplateFile(filename)``
            Create a PageTemplate object from a file.
        
        ``IBrowserRequest``
            Browser request interface from ``zope.publisher``.
        
        ``IDefaultBrowserLayer``
            Default layer for browser components from ``zope.publisher``.
        
        
        In addition, the ``grokcore.view`` package exposes the
        `grokcore.component`_ and `grokcore.security`_ APIs.
        
        .. _grokcore.component: http://pypi.python.org/pypi/grokcore.component
        .. _grokcore.security: http://pypi.python.org/pypi/grokcore.security
        .. _grokcore.view: http://pypi.python.org/pypi/grokcore.view
        
        
        Upgrade notice
        ==============
        
        In grokcore.view 1.8, grokcore.view.View was splitted into View (that only
        works with templates) and CodeView (that only accepts a ``render()`` method).
        
        So views that have a render method must subclass from CodeView instead of
        View.  That should be the only change needed.
        
        Changes
        =======
        
        1.13.5 (2010-06-03)
        -------------------
        
        - Fix the url() function to behave properly while passed an empty data dict.
        
        
        1.13.4 (2010-06-01)
        -------------------
        
        - Fix the url() method to accept the "status" and "trusted" arguments, passed
          on to the redirect method on the response object.
        
        
        1.13.3 (2010-05-27)
        -------------------
        
        - Make package comply to zope.org repository policy.
        
        - Update tests not to require zope.app.testing anymore.
        
        - Update tsets not to require zope.app.zcmlfiles anymore.
        
        - Warnings are now emitted as log messages with level
          ``logging.WARNING`` to a logger named ``grokcore.view`` with level
          ``logging.ERROR``. That means that by default no warnings are
          emitted anymore (while errors will still appear).
        
          You have to tweak the mentioned logger to get the warnings back. For
          instance you can set its level to ``logging.INFO`` or similar. This
          has to be done before code is grokked using `grokcore.view`.
        
        
        1.13.2 (2010-01-09)
        -------------------
        
        - Require zope.login.
        
        - Require newer versions of zope.app.exception and zope.app.pagetemplate
          addressing launchpad issue 499633.
        
        
        1.13.1 (2009-12-15)
        -------------------
        
        - Removed duplicate 'tests_require' from setup.py that prevented installation.
        
        
        1.13 (2009-12-13)
        -----------------
        
        - Added missing dependencies in setup.py (copied from trunk).
        
        
        1.13a2 (2009-11-27)
        -------------------
        
        - Factor out generally useful methods and properties for view-ish
          components into components.ViewSupport mixin.
        
        
        1.13a1 (2009-11-15)
        -------------------
        
        - Use zope.container instead of deprecated zope.app.container, use zope.site
          instead of zope.app.folder.
        
        - Some imports have been modified, to avoid deprecation warnings,
          while using ZTK 1.0dev. [trollfot]
        
        - Added support for ZTK 1.0dev. This was possible by changing
          slightly the DirectoryResource implementation. The DirectoryResource
          now uses `zope.browserresource` where DirectoryResourceFactory's factories
          are no longer a class-level dict entry but utilities. [trollfot]
        
        
        1.12.2 (2009-09-17)
        -------------------
        
        - Test fix: support windows paths.
        
        1.12.1 (2009-09-17)
        -------------------
        
        - A compatibility fix to support ``grokcore.viewlet``.
        
        1.12 (2009-09-17)
        -----------------
        
        - Use 1.0b1 versions.cfg in Grok's release info instead of a local
          copy; a local copy for all grokcore packages is just too hard to
          maintain.
        
        - Revert the splitting CodeView/View. The original reasons for the
          split have been obsoleted by the recent martain developments
          regarding inheritted module level directives. At the same time the
          split up components proved cumbersome to use and a too big a change
          between the 1.0a and 1.0b releases of Grok.
        
          View components will now again behave like it did up until the latest alpha
          release of Grok.
        
          ``CodeView`` is still available as a backwards compatibility alias
          for ``View``. Please update all references to ``CodeView`` to
          ``View``.
        
        - Fix the template registry and grokker for views to let View and
          other components using View as base class to be associated with a
          template directly by setting it as 'template' attribute on the view
          class. Example::
        
            class MyView(grokcore.view.View):
        
                template = grokcore.view.PageTemplate('<p>hello</p>')
        
          This isn't exactly *officially* supported but enough people depend
          on it and have documented it so that we don't want to just break it.
        
        1.11 (2009-09-15)
        -----------------
        
        - The response attribute needs to be available in CodeView as well.
        
        1.10 (2009-09-14)
        -----------------
        
        - Up the version requirement for grokcore.security to 1.2.
        
        - Bring versions.cfg in line with current grok versions.cfg.
        
        
        1.9 (2009-07-04)
        ----------------
        
        - Fix needed for grokcore.formlib: allow a base_method'ed render() on view.
          This allows grokcore.formlib to have a render() in addition to a template.
        
        - Reverted change to checkTemplates: for some formlib edge cases it detects
          the right templates again.
        
        
        1.8 (2009-07-04)
        ----------------
        
        - Add validator to templatedir directive to disallow path separator.
        
        - Splitted CodeView out of View.  View only uses templates, CodeView only uses
          a render() method.  So views that have a render method must subclass from
          CodeView instead of View (that should be the only change needed).
        
        - Add grok.View permissions to functional tests (requires grokcore.security 1.1)
        
        
        1.7 (2009-05-19)
        ----------------
        
        - Revert dependency from zope.container back to zope.app.container.
        
        
        1.6 (2009-04-28)
        ----------------
        
        - Simplify the DirectoryResource and DirectoryResourceFactory
          implementations by making better use of the hook points provided by
          zope.app.publisher.browser.directoryresource.
        
        1.5 (2009-04-10)
        ----------------
        
        - Don't register a 'static' resource directory if the 'static' directory does
          not exist.
        
        - Make it possible to instantiate an ungrokked view by being slightly more
          defensive in __init__. This makes it easier to write unit tests.
        
        1.4 (2009-04-08)
        ----------------
        
        * Page template reloading now also works for macros. Fixes
          https://bugs.launchpad.net/grok/+bug/162261.
        
        * Use zope.container instead of zope.app.container.
        
        * Ignore '<tpl>.cache' files when looking up template files in a
          template dir. Fix bug https://bugs.launchpad.net/grok/+bug/332747
        
        1.3 (2009-01-28)
        ----------------
        
        * Adapt tests to work also from eggs not only source checkouts by
          avoiding `src` in directory comparisons.
        
        * Fix the factory for subdirectories of the DirectoryResource implementation
          by using hooks in zope.app.publisher.browser.directoryresource.
        
        * Update APIs interfaces to include the new ``path`` directive and
          new ``DirectoryResource`` component.
        
        1.2 (2008-10-16)
        ----------------
        
        * Expose the ``DirectoryResource`` class as a component for registering
          directories as resources. This is accompanied by the ``path`` directive that
          is used to point to the directory holding resources by way of an relative (to
          the module) or absolute path. ``DirectoryResource`` components can be
          differentiated by name and layer.
        
        1.1 (2008-09-22)
        ----------------
        
        * ``meta.py`` module containing the grokkers has been split in a
          package with separate modules for the view, template, skin and
          static resources grokkers. This allows applications to use only
          grokkers they need (and maybe redefine others).
        
        1.0 (2006-08-07)
        ----------------
        
        * Created ``grokcore.view`` in July 2008 by factoring security-related
          components, grokkers and directives out of Grok.
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Framework :: Zope3
