Metadata-Version: 1.0
Name: collective.editskinswitcher
Version: 2.2
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/``.  Note that you need to very
            explicitly use the exact url to your Plone Site root.  For
            example, when trying this locally you may need something like
            this: ``http://localhost:8080/Plone``
        
          - 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>
        
        
        Sub sites with navigation root
        ------------------------------
        
        Using the `Per-folder default skin`_ menu you already mostly have a to
        make simple subsites.  The only other basic thing needed is to set the
        folder as a navigation root, so giving it the
        ``plone.app.layout.navigation.interfaces.INavigationRoot`` marker
        inferface.  This option has now been added to the menu, guarded by new
        permission "Set navigation root", by default only for Manager.
        
        
        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>
        
        - In version 2.0 the ``PAGE_WHITE_LIST`` and ``SUFFIX_WHITE_LIST``
          were replaced with a list of regular expressions
          (``WHITELIST_REGEXPS``).  If you were monkey patching those config
          settings in a package of your own, you will have to update your
          patch.  If you do not update your patch, then either Zope will not
          start or your patch will have no effect.
        
        
        Have fun!
        
        Maurits van Rees
        
        
        Changelog for collective.editskinswitcher
        =========================================
        
        2.2 (2012-02-15)
        ----------------
        
        - Fixed broken release by fixing MANIFEST.in.
          [maurits]
        
        
        2.1 (2012-02-15)
        ----------------
        
        - Changed the calculation for the iframe height.  With the original
          code Firefox was behaving quircky, the height was 150px.  That is
          too small.  With help of Mark we could fix this.
          [mirella]
        
        
        2.0 (2011-09-28)
        ----------------
        
        - Added MANIFEST.in so we can automatically include .mo files with
          zest.pocompile.
          [maurits]
        
        - Replace the PAGE_WHITE_LIST and SUFFIX_WHITE_LIST with a list of
          regular expressions (WHITELIST_REGEXPS). Using regexps we can also
          whitelist more complex URLs, e.g. for the password reset tool
          (/passwordreset/1234...). [markvl]
        
        
        1.6 (2011-06-11)
        ----------------
        
        - Also set the theme specific browser layers when switching skins.
          Code heavily inspired by themetweaker.themeswitcher. [markvl]
        
        
        1.5 (2011-01-04)
        ----------------
        
        - Always show the Styles menu when the user has the "Set navigation
          root" permission.
          [maurits]
        
        - Check our permissions on the folder when we are on a default page.
          This might give a difference.
          [maurits]
        
        
        1.4 (2010-12-31)
        ----------------
        
        - Added menu item to set the context as a navigation root
          (plone.app.layout.navigation.interfaces.INavigationRoot) guarded by
          new permission "Set navigation root", by default only for Manager.
          [maurits]
        
        
        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
