[Checkins] SVN: bluebream/website/docs/v1.0/manual/skinning.rst ready for review !
Baiju M
baiju.m.mail at gmail.com
Wed Aug 11 02:36:12 EDT 2010
Log message for revision 115623:
ready for review !
Changed:
U bluebream/website/docs/v1.0/manual/skinning.rst
-=-
Modified: bluebream/website/docs/v1.0/manual/skinning.rst
===================================================================
--- bluebream/website/docs/v1.0/manual/skinning.rst 2010-08-11 06:14:12 UTC (rev 115622)
+++ bluebream/website/docs/v1.0/manual/skinning.rst 2010-08-11 06:36:12 UTC (rev 115623)
@@ -6,100 +6,79 @@
Introduction
------------
-It is often required to build web applications with equal/similar
-features, but different look and feel. Variation of look and feel
-can be simple or complex. It can be either just an exchange of a CSS
-file and some images. Sometimes, you will be required to reconfigure
-the application to have different user interface components, such as
-widgets, tables etc. Also you will be required to mix and match user
-interface components from multiple packages.
+It is often required to build web applications with equal/similar features,
+but different look and feel. Variation of look and feel can be simple or
+complex. It can be either just an exchange of a CSS file and some images.
+Sometimes, you will be required to reconfigure the application to have
+different user interface components, such as widgets, tables etc. Also you
+will be required to mix and match user interface components from multiple
+packages.
-In BlueBream, the skin concept is implemented to use the Zope
-component architecture.
+There are two terms associated with skinning named, `layer` and `skin`.
+Before proceeding, it would be better to understand the meaning of these two
+terms in BlueBream skinning.
-There are two terms associated with skinning named, `layer` and
-`skin`. Before proceeding, it would be better to understand the
-meaning of these two terms in BlueBream skinning. Skins are directly
-provided by a request
-
Layers
~~~~~~
-* Define the "feel" of a site
+A layer define the **feel** of an application user interface. Layer
+contains the presentation logic of the application. Presentation logic
+involves the layout of pages and placement of widgets. Some common
+artifacts of layer are pages, content providers, viewlet managers and
+viewlets. Layers are normally developed by BlueBream (Python) developers.
-* Contain presentation logic
-
-* Common artifacts: pages, content providers, viewlet managers, and
- viewlets
-
-* Developed by BlueBream (Python) developers
-
-
Skins
~~~~~
-* Define the "look" of a site
+A skin define the **look** of a an application user interface. Common
+artifacts of skins are templates (ZPT) and resources (CSS, Javascript,
+etc.). Skin use layers to retrieve the data for templates. Skins are
+normally developed by HTML and graphic designers.
-* Common artifacts: templates and resources (CSS, Javascript, etc.)
-
-* Use layers to retrieve the data for templates
-
-* Developed by HTML and Graphic Designer/Scripter
-
-
Layers versus skins
~~~~~~~~~~~~~~~~~~~
-* Both are implemented as interfaces
+Both layers and skins are implemented as interfaces. Technically speaking,
+BlueBream does not differentiate between layers and skins. In fact, the
+distinction of layers defining the **feel** and skins the **look** is a
+convention. You may not want to follow the convention, if it is too
+abstract for you, but if you are developing application with multiple look
+and feel, it is strongly suggested using this convention, since it cleanly
+separates concerns.
-* BlueBream does not differentiate between the two
+Both layers and skins support inheritance/acquisition. This is realized
+through a combination of interface inheritance and component lookup
+techniques.
-* In fact, the distinction of layers defining the "feel" and skins
- the "look" is a convention. You may not want to follow the
- convention, if it is too abstract for you, but if you are
- developing application with multiple look and feel, it is strongly
- suggested using this convention, since it cleanly separates
- concerns.
+There are some skins available with BlueBream. Unfortunately, it is hard to
+reuse the UI components developed for these skins, since they still rely on
+the not so flexible macro pattern. Thus, it is better if you start from
+scratch. This will also avoid a lot of the overhead that comes with the
+over-generalized core skins. In future, those core skins will be removed or
+replaced.
-* Both support inheritance/acquisition
-
-This is realized through a combination of interface inheritance and
-component lookup techniques. This book will discuss this in more
-detail later.
-
-Unfortunately, it is hard to reuse the UI components developed for
-these skins, since they still rely on the not so flexible macro
-pattern. Thus, it is better if you start from scratch. This will
-also avoid a lot of the overhead that comes with the over-generalized
-core skins.
-
A new skin
----------
-* Views registered for default layer by default
- ``zope.publisher.interfaces.browser.IDefaultBrowserLayer``
+All views are registered for ``default`` layer by default. So, you need not
+to explicitly mention the layer to get registered for ``default`` layer.
+The interface which define the default layer is located here:
+``zope.publisher.interfaces.browser.IDefaultBrowserLayer``. The default
+layer contains a lot of things you do not need (security concerns). Since
+pretty much everything in ``zope.app`` is registered into the default layer,
+it has an uncontrollable amount of junk in it. It is very hard to verify
+that all those registrations fulfill your security needs. Another problem
+is that views might be available that you do not want to be available. It
+is reccommended to develop skins from scratch. But some registrations in
+the default layer are very useful. Examples of those useful registrations
+include error views, traversal registrations, and widgets.
-* Default layer contains a lot of things you do not need (security
- concerns)
-* Since pretty much everything in ``zope.app`` is registered into the
- default layer, it has an uncontrollable amount of junk in it. It
- is very hard to verify that all those registrations fulfill your
- security needs. Another problem is that views might be available
- that you do not want to be available.
-
-* Always want to develop skins from scratch
-
-* Some registrations in the default layer are very useful
-
-* Examples of those useful registrations include error views,
- traversal registrations, and widgets.
-
-
Setting up a layer
~~~~~~~~~~~~~~~~~~
-Write an interface for the layer that inherits the minimal layer::
+To create a new layer, you need to write an interface of the type:
+``IBrowserSkinType`` as given here::
from zope.publisher.interfaces.browser import IBrowserSkinType
@@ -107,68 +86,69 @@
"""Hello World Application Layer"""
-Change all page, viewletmanager, and viewlet directives to specify
-this layer::
+.. note:: **Interface type**
- layer=".interfaces.IHelloWorldLayer"
+ The ``IBrowserSkinType`` is an interface type similar to ``Interface``.
+ To create an interface type, you can create an interface inheritting from
+ ``zope.interface.interfaces.IInterface``. For example::
-Once you changed those registrations, the `helloworld.html` page will
-not be available anymore in the core skins. The templates by themselves
-do not matter.
+ from zope.interface.interfaces import IInterface
+ class IMyInterfaceType(IInterface):
+ """My interface type"""
-Using layer
-~~~~~~~~~~~
+To use this layer, you can change all page, viewletmanager, and viewlet
+directives to specify this layer::
-Registering views and resources is not any different now, but you can
-simply register them on the skin directly::
+ layer=".interfaces.IHelloWorldLayer"
+Once you changed those registrations, the `helloworld.html` page will not be
+available anymore in the default layer used by core skins. The templates by
+themselves do not matter.
+
+Some examples::
+
<browser:resource
name="zope3logo.gif"
file="images/zope3logo.gif"
- layer=".interfaces.IBasicSkin"
+ layer=".interfaces.IHelloWorldLayer"
/>
-As you can see, you don't have to create an extra layer just to
-create a custom skin. You were also able to use standard Component
-Architecture ZCML directives instead of custom ones whose special
-syntax the developer needs to remember additionally.
-
-A typical ``browser:page`` with with layer specified is like this::
-
<browser:page
for="*"
name="dialog_macros"
permission="zope.View"
- layer=".interfaces.IBasicSkin"
+ layer=".interfaces.IHelloWorldLayer"
template="dialog_macros.pt"
/>
+You were able to use standard component architecture ZCML directives instead
+of custom ones whose special syntax the developer needs to remember
+additionally.
Setting up a skin
~~~~~~~~~~~~~~~~~
-Skins are technically interfaces defined using ``zope.interface``
-package. Write an interface for each new skin that inherits the Hello
-World application layer::
+Skins are also interfaces defined using ``zope.interface`` package. You can
+created skin interfaces by inheritting from the layer interface. For
+example, here is a ``IHelloWorldSkin`` inheritted from Hello World
+application layer (``IHelloWorldLayer``)::
- class IBasicSkin(IHelloWorldLayer):
+ class IHelloWorldSkin(IHelloWorldLayer):
"""Basic Skin for Hello World App."""
-To register this you can use ``interface`` and ``utility`` directives
-in ``zope`` namespace. The type of the ``IShanghaiSkin`` skin is
-``zope.publisher.interfaces.browser.IBrowserSkinType``. Here is a
-sample ``configure.zcml``::
+To register this you can use ``interface`` and ``utility`` directives in
+``zope`` namespace. Here is a sample ``configure.zcml``::
<interface
- interface=".interfaces.IBasicSkin"
+ interface=".interfaces.IHelloWorldSkin"
type="zope.publisher.interfaces.browser.IBrowserSkinType"
/>
<utility
- component=".interfaces.IBasicSkin"
+ component=".interfaces.IHelloWorldSkin"
provides="zope.publisher.interfaces.browser.IBrowserSkinType"
- name="BasicSkin"
+ name="HelloWorldSkin"
/>
As a shortcut, you can also just use the ``interface`` directive and
@@ -176,37 +156,41 @@
same effect as the two above regarding the skin registration::
<interface
- interface=".interfaces.IBasicSkin"
+ interface=".interfaces.IHelloWorldSkin"
type="zope.publisher.interfaces.browser.IBrowserSkinType"
- name="BasicSkin"
+ name="HelloWorldSkin"
/>
-Register all templates for this skin by adding the layer attribute::
+You can register all templates for this skin by adding the layer attribute::
- layer=".interfaces.IBasicSkin"
+ layer=".interfaces.IHelloWorldSkin"
+As you can see, you don't have to create an extra layer just to create a
+custom skin. But it is not reccommended to declare any views for the skin
+directly, rather you can register for the layer.
Using the skin
~~~~~~~~~~~~~~
To access a skin, you need to use ``++skin++`` in the begining of the
path followed by the skin name. For example, if the skin name is
-``BasicSkin``, the site can be accessed like this:
-``http://localhost:8080/++skin++BasicSkin``
+``HelloWorldSkin``, the site can be accessed like this:
+``http://localhost:8080/++skin++HelloWorldSkin``
You can hide the skin traversal step by using Apache's virtual
hosting feature.
To change the default skin to something else use the
-``browser:defaultSkin`` directive. You can set ``BasicSkin`` as the
+``browser:defaultSkin`` directive. You can set ``HelloWorldSkin`` as the
default skin like this::
- <browser:defaultSkin name="BasicSkin" />
+ <browser:defaultSkin name="HelloWorldSkin" />
-You can add this declaration in the ZCML file where you are defining
-the skin & layer interfaces.
+You can add this declaration in the ``etc/overrides.zcml`` file. So that it
+will be overridden by the previous declaration, if there is any.
Summary
-------
-This chapter introduced skinnig in BlueBream.
+This chapter introduced concepts related to BlueBream skinning. This
+chapter also explained howto create layers and skins from scratch.
More information about the checkins
mailing list