Metadata-Version: 1.0
Name: collective.editskinswitcher
Version: 1.3
Summary: Switch to the edit skin for certain domains.
Home-page: http://svn.plone.org/svn/collective/collective.editskinswitcher
Author: Maurits van Rees
Author-email: m.van.rees@zestsoftware.nl
License: GPL
Description: .. contents::
        
        Collective edit skin switcher
        =============================
        
        For a customer of `Zest Software`_ I [Maurits van Rees] created a
        package called ``collective.editskinswitcher``.  I gladly took some code
        from colleague Mark van Lent who did something similar for a different
        web site.  The package is on the Cheese Shop so it can be easy
        installed.  And the code is in the Plone collective_.
        
        .. _`Zest Software`: http://zestsoftware.nl
        .. _collective: http://svn.plone.org/svn/collective/collective.editskinswitcher/
        
        
        What does it do?
        ----------------
        
        Let's say you have a Plone Site.  I tested this with Plone 3.  I see
        no reason why it should fail on Plone 2.5.  Maybe it even works on a
        CMF site.  Anyway, whatever site you have is available on two urls:
        ``www.example.com`` and ``edit.example.com``.  Some day you
        should ask your local Apache guru how he did that.
        
        With ``collective.editskinswitcher`` installed (with the portal quick
        installer), visitors that go to the website with the url
        ``edit.example.com`` will see the Editor Skin.  (This can be set in
        a property, as we shall see later.)  Visitors to
        ``www.example.com`` will see whatever skin you have set as the
        default skin in portal_skins.  Can be pretty handy.
        
        To avoid confusion: we will call what you have set as "default skin"
        the Visitor Skin.  And the skin meant for editors we call the Editor
        Skin.
        
        Developer types probably like the fact that you also get the Visitor
        Skin when visiting ``localhost`` and the Editor Skin when you go to
        ``127.0.0.1``.
        
        Since version 1.1 you can also set a different default skin in a
        folder.  So you can set it up so that folder-1 uses a red theme,
        folder-2 a blue theme and when you edit either folder you still use
        Plone Default.  See also the `Per-folder default skin`_ section.
        
        
        Other options
        -------------
        
        There are some options you can set.  Go to ``portal_properties``, and
        then go to the ``editskin_switcher`` property sheet.  These options
        are available:
        
        - ``edit_skin``: set the skin that editors get.  The default is "Plone
        Default".
        
        - ``switch_skin_action``: choose the url condition that is used for
        switching to the edit skin.  **Note**: since version 0.9 this is a
        multiple select: if *one* of the selected options gives a positive
        result, then we switch to the edit skin.  Options are:
        
        - based on edit URL: With this you get the behaviour described above.
        This is the default.
        
        - based on specific domain: If this is specified the edit skin is used when the
        first part of the url matches one of the entries in the
        ``specific_domains`` property.  This url is the url for the root
        of the Plone Site; so usually this will be a domain, like
        ``http://special.example.com``.
        
        - based on admin header: If this is chosen you will need to set up your proxy
        server, eg. Apache, to add a 'HTTP_PLONEADMIN' header to the request. It can
        do this based on the url for instance. An example is given in
        /tests/ploneadmin_header.txt
        
        - based on SSL: If this is chosen, then any urls that are SSL
        will get the edit skin and others will get the default skin.
        
        - No URL based switching: do not base the skin switching on the url;
        instead we check the ``need_authentication`` option.
        
        - ``need_authentication``: when True you need to be logged in before
        your skin is switched.  By default this is set to False.  See
        the section `Am I authenticated?`_ below for some notes.
        
        - ``force_login_header``: when the request has this header, only
        authenticated use is allowed.  This does not actually switch the
        skin; you just get redirected to the login_form.  By default this is
        set to the string ``X_FORCE_LOGIN``.  Note that this is not done for
        the login_form and other pages like that.  Such a page probably
        looks ugly though, as you still are forced to login before you can
        get the css and images for that page.
        
        If you combine the switch skin action and the authentication, then you
        need to have the right url and you need to be logged in.
        
        When both are not used, nothing happens: then you might as well simply
        uninstall this product as it is not useful.
        
        
        Am I authenticated?
        -------------------
        
        The ``need_authentication`` option looks for the ``__ac`` cookie that
        Plone gives you when logged in.  There are a few possible problems
        with this:
        
        - Logging in via the Zope Management Interface is handled without
        cookies, so the editskin switcher regards you as anonymous then.
        
        - We do not check if the the cookie is actually valid.  This can
        mostly give a surprise when you are developing multiple websites on
        your own local computer: Plone stores the ``__ac`` cookie for the
        localhost domain, without differentiating between multiple Plone
        sites.  So if you are logged into Plone Site A on localhost with a
        cookie, then the skin switcher thinks you are authenticated for all
        websites on localhost.
        
        Alternatively, we could check ``getSecurityManager().getUser()``, but
        that check always thinks we are anonymous, presumably because our
        check is done during traversal, which apparently is too soon for
        anyone to be recognized as being logged in.
        
        
        Why not CMFUrlSkinSwitcher?
        ---------------------------
        
        I looked at CMFUrlSkinSwitcher first but it had not been touched in
        two years.  One import error (CMFCorePermissions) could easily be
        fixed as that import was not even used.  But after that tests were
        failing all over the place.  Theoretically always fixable of course,
        but rolling an own package seemed easier, cleaner and faster.
        
        Also, CMFUrlSkinSwitcher does some more things.  At least it messes
        around with some methods like absolute_url.  It could be that I find
        out later that this is necessary in ``collective.editskinswitcher`` too,
        but currently it does not look like that will be the case.
        
        
        How do I know this is working?
        ------------------------------
        
        The easiest way to test this package in a default plone site (apart
        from running the tests of course), is:
        
        - Install ``collective.editskinswitcher``.
        
        - Go to portal_skins in the ZMI.
        
        - Create a new skin selection based on Plone Default.  Call this
        "Visitor Skin".
        
        - Make Visitor Skin the default skin.
        
        - Remove the custom skin layer from Plone Default.
        
        - Customize the main template or the logo or something else that
        is easy to spot.
        
        - Visit ``127.0.0.1:8080/plonesite`` and you will see default Plone.
        
        - Visit ``localhost:8080/plonesite`` and you will see Plone with
        your customization.
        
        
        On Linux you can edit ``/etc/hosts`` and add a line like::
        
        127.0.0.1 edit.example.com www.example.com
        
        Now visiting ``edit.example.com`` should give you the Editor Skin
        and ``www.example.com`` should give you the Visitor Skin with the
        customizations.
        
        
        You can also let the edit urls begin with ``cms`` or ``manage``.  As
        long as the url is something like::
        
        ...//(edit|cms|manage).something.something....
        
        you end up in the edit skin.
        
        
        Preview
        -------
        
        The preview option allows you to see the default skin via the edit skin.
        
        It does so by using an iframe which accesses the edit skin content but flips
        it to the default skin. This allows you to easily view previous versions,
        private content etc. as it will appear in the default skin if published.
        
        This is particularly useful in cases where your default skin differs
        radically from the edit skin. It allows the edit interface to maintain some
        wysiwyg functionality.
        
        Preview can either be used as a separate preview tab, or as a replacement
        for the view tab content in the edit skin.
        
        Both are implemented within the tests folder and tested, but neither is
        used by default.
        
        For the preview of editskinswitcher to be of use it requires an
        accompanying theme.egg holding the configuration for the default (and
        edit) skins.  In order to use preview, it must be turned on within
        this accompanying theme egg. Example code to do this are within the
        tests folder.
        
        Instructions for replacing view with preview are given in
        tests/skins/README.txt
        
        To add it as a separate preview tab:
        
        1. Add the browser view by putting what is in tests/configure.zcml in
        your theme egg configure.zcml
        
        2. Within tests/add_preview.py there is ACTIONSCONFIG
        Add this as a profiles/default/actions.xml file.
        Change the default visible=False property to True.
        
        
        Per-folder default skin
        -----------------------
        
        Selecting a default skin for a specific folder is also supported. A
        'Skins' menu entry should show up in the content area, right next to
        the 'Display' and 'Actions' menu. Once you select a skin from that
        dropdown, it will be used as the default skin when visiting that
        folder instead of the site-wide default skin.
        
        This menu is available for everyone who has the ``Set default skin``
        permission, which by default is for Managers and Owners.  So if you do
        not want anyone to have this menu, you can do so by not giving anyone
        this permission.  In the rolemap.xml file of your GenericSetup profile
        that would look like this::
        
        <?xml version="1.0"?>
        <rolemap>
        <permissions>
        <permission name="Set default skin" acquire="False" />
        </permissions>
        </rolemap>
        
        
        Installation using zc.buildout
        ------------------------------
        
        For using collective.editskinswitcher with zc.buildout you have to add
        ``collective.editskinswitcher`` to the ``eggs`` and ``zcml`` sections::
        
        eggs = collective.editskinswitcher
        ...
        zcml = collective.editskinswitcher
        ...
        
        Note that the zcml line is not needed on Plone 3.3 or higher.
        
        
        Configuration without using zc.buildout
        ---------------------------------------
        
        If you are using collective.editskinswicher without zc.buildout, you need
        to add a ZCML slug ``collective.editksinswitcher-configure.zcml`` within
        your ``etc/package-includes`` directory containing::
        
        <include package="collective.editskinswitcher" />
        
        
        Upgrading
        ---------
        
        - In version 0.9 the ``switch_skin_action`` property was changed to a
        multiple selection field.  There is an upgrade step that migrates
        your previous setting correctly.  If you have changed this property
        in your custom theme or policy package in a ``propertiestool.xml``
        file, you will need to upgrade that file manually to the new setting
        like this::
        
        <property name="switch_skin_action"
        type="multiple selection"
        select_variable="editSwitchList">
        <element value="based on edit URL"/>
        </property>
        
        
        Have fun!
        
        Maurits van Rees
        
        
        Changelog for collective.editskinswitcher
        =========================================
        
        1.3 (2010-12-14)
        ----------------
        
        - Do not show the Styles menu when there are no styles to choose.
        [maurits]
        
        - Moved PAGE_WHITE_LIST and SUFFIX_WHITE_LIST from traversal.py to new
        config.py.
        [maurits]
        
        - Added SUFFIX_WHITE_LIST to avoid triggering a forced login for css
        or javascript files, otherwise the login form will look ugly.  Also
        added logo.jpg/png/gif and favicon.ico to the PAGE_WHITE_LIST for
        the same reason.
        [maurits]
        
        
        1.2 (2010-12-07)
        ----------------
        
        - Do not force logging in when you get this header for a login page
        (specified by the PAGE_WHITE_LIST).
        [maurits]
        
        
        1.1 (2010-12-07)
        ----------------
        
        - Use ``get_header`` instead of ``get`` when looking for headers to
        force logging in or force using the edit skin.
        [maurits]
        
        - Allow setting a default skin on a folder, using the new Styles
        context menu.
        [dreamcatcher]
        
        
        1.0 (2010-06-07)
        ----------------
        
        - Fix: when we need authentication and we are anonymous then we do
        *not* want to switch: we want to have the default behaviour of
        getting the standard skin instead of the edit skin.  Added some more
        inline documentation.
        [maurits]
        
        - Switch back to checking the ``__ac`` cookie to see if someone is
        anonymous or not; the getSecurityManager check always says we are
        anonymous, though I thought I had seen it working previously.
        [maurits]
        
        - Add logging lines for debugging.
        [maurits]
        
        
        0.9 (2010-04-19)
        ----------------
        
        - Change the switch skin action to a multiple selection.  When one
        of the selected actions returns True, we switch the skin.
        [maurits]
        
        - Also accept urls like admin.example.org as edit urls.
        [maurits]
        
        
        0.8 (2010-04-16)
        ----------------
        
        - Slightly better check for anonymous users, using getSecurityManager
        instead of checking for an ``__ac`` cookie.
        [maurits]
        
        - When a X_FORCE_LOGIN header is passed (exact spelling is configurable)
        only allow access to logged in users (you get redirected usually).
        [maurits]
        
        - Allow specifying the admin_header; defaults to HTTP_PLONEADMIN.
        [maurits]
        
        - Added z3c.autoinclude.plugin entry point for plone, to avoid having
        collective.editskinswitcher in the zcml option of your zope
        instance; only effective in Plone 3.3 or higher.  In earlier
        versions you still need to do this manually.
        [maurits]
        
        
        0.7 (2008-10-04)
        ----------------
        
        - Added switching option based on a request header flag set by the
        proxy server (eg. Apache)
        [Ed Crewe, ILRT - University of Bristol]
        
        
        0.6 (2008-08-27)
        ----------------
        
        - New preview feature so that the default skin can be seen via the
        edit skin interface to preserve some level of WYSIWYG for editing.
        (Based on part of an unreleased plone 2 product by Dominic Hiles.)
        Preview feature is available as a viewlet for use via a view or a
        viewletManager, but it is turned off by default.  Examples of how to
        enable it are included in the tests, where it is enabled and tested.
        [Ed Crewe, ILRT - University of Bristol]
        
        - Extra URL skin switching options of SSL or specific URLs
        [Ed Crewe, ILRT - University of Bristol]
        
        - Setting eol style in subversion correctly. [reinout]
        
        
        0.5 (2008-03-07)
        ----------------
        
        - Bug fix: when called on the zope root (can happen in some cases)
        portal_properties was not found, which was not caught correctly.
        [maurits]
        
        
        0.4 (2008-02-12)
        ----------------
        
        - Bug fix: if object has no changeSkin, try its context.  Happens at
        least on the sharing tab when searching for users, as object is a
        KSS view then.
        [maurits]
        
        
        0.3 (2008-01-30)
        ----------------
        
        - Instead of an Access Rule, use a pre-traversal hook.  Idea: David
        Convent.  Thanks!  Is a lot cleaner.
        [maurits]
        
        - Avoid confusion in README.txt: talk about Editor Skin and Visitor
        Skin instead of Plone Default and the default skin.
        [maurits]
        
        - Update README.txt to tell about the new options introduced in
        version 0.2.
        [maurits]
        
        
        0.2 (2008-01-28)
        ----------------
        
        - When testing if the user is logged in, check for the __ac cookie in
        the request instead of portal_membership.isAnonymousUser as this
        does not work in real life; probably because we use an AccessRule.
        [maurits]
        
        - Add based_on_url property (default: True).  When True, the skin
        switching is done when you visit the site via an edit url.  When
        combined with need_authentication=True, only logged-in users on the
        edit url get the edit skin.
        [maurits]
        
        - Add need_authentication property (default: False).  When True, the
        skin switching is only done when you are authenticated (logged in).
        [maurits]
        
        - In the base test cases, create the new default skin.
        [maurits]
        
        - Split tests/setup.txt in two files for separating some unrelated
        tests.
        [maurits]
        
        - Add a more readable README.txt and move the old one into the
        tests directory as it contains most of our tests.
        [maurits]
        
        
        0.1 (2008-01-25)
        ----------------
        
        - Add a property sheet editskin_switcher with property edit_skin.
        Default value: Plone Default.  Use that for determining which
        skin to give to editors.
        [maurits]
        
        - Initial package structure.
        [zopeskel]
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Framework :: Zope2
Classifier: Framework :: Zope3
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
