Theming

Description

Creating mobile themes for Plone with Web and Mobile

Introduction

Web and Mobile uses standard Plone skin mechanism. You can use whatever theming technique you wish, as long as it can be used as a Plone skin.

The only difference between a normal Plone theme and Web and Mobile theme is that Web and Mobile theme name is read from the property:

portal_properties.mobile_properties.mobile_skin

Instead of standard:

portal_skins.default_skin

Namespace and Python package name recommendations

Use namespace gomobiletheme.yourthemename for Web and Mobile themes

Creating a mobile theme

You can include paster command in your buildout.cfg with gomobile.templates package included. This will you give a paster command with the template gomobile_theme.

buildout.cfg:

parts =
        ...
        paster

[paster]
recipe = zc.recipe.egg
eggs =
        PasteScript
        gomobile.templates
        ${instance:eggs}

Then you can create your own theme skeleton with:

bin/buildout # reruns to build paster command
cd src
../bin/paster create -t gomobile_theme gomobiletheme.yourcompanyname
# Answer questions
# Source code is generated for a mobile theme add-on skeleton

Then follow generic paster instructions for Plone how to include the generated source code egg in buildout.cfg.

Writing your first theme

Theme layer is mobile aware

All mobile views and viewlets are registered against your theme layer, which is a sublass of mobile layer - this way mobile views do not conflict with web views and cannot be accidentally exposed to web. When you generate a new theme you will get .interfaces.IThemeLayer class for this purpose.

Also there exists an old tyle skins layer folder for mobile specific page template overrides.

five.grok used

gomobiletheme.basic uses five.grok for viewlets and static media.

For more information see developer manual documentation regarding grok and five.grok.

Overriding a browser view for mobile

This example will override some Zope 3 browser:page based view for your mobile theme.

Add file views.py where all overriden views will be placed:

"""

    View overrides

"""

__docformat__ = "epytext"
__license__ = "GPL"

from zope.component import getMultiAdapter

from zope.interface import Interface

from five import grok

from gomobiletheme.basic import viewlets as base
from gomobile.mobile.interfaces import IMobileImageProcessor

from isleofback.mobi import MessageFactory as _

# Layer for which against all our viewlets are registered
from interfaces import IThemeLayer

# Viewlets are on all content by default.
grok.context(Interface)

# Use templates directory to search for templates.
grok.templatedir('templates')

# Viewlets are active only when gomobiletheme.basic theme layer is activated
grok.layer(IThemeLayer)

class FrontPageView(grok.View):
    """ """

    # The name of the view we override
    grok.name("isleofbackfrontpage_view")

    # Use grok.context() here if your view is specific to some content type

Then templates/frontpageview.pt:

.. code-block:: html
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
lang="en" metal:use-macro="here/main_template/macros/master" i18n:domain="isleofback.app">
<body>
<div metal:fill-slot="main">
<tal:main-macro metal:define-macro="main">
This is your page payload.

</tal:main-macro>

</div>

</body> </html>

Controlling automatic mobile folder listing

Mobile folder listing is enabled automatically to all content types. To fine-tune its usage for your site you can override the viewlet:

class MobileFolderListing(grok.Viewlet):

    def hasListing(self):
        """
        Check whether mobile folder listing is enabled for a particular content type.
        """
        return False

Remember to add (empty) mobilefolderlisting.pt also, or copy it from gomobiletheme.basic.

Setting CSS and JS locations

Mobile theme static CSS and Javascript resources are provided by five.grok static folder mechanism.

Different CSS files

Read Transformations chapter for info about different CSS files and their purposes.

Extending the default theme with more CSS and JS files

AdditionalHead viewlet's purpose is to extend the default theme with new CSS and JS files by adding more content to the end of HTML <head> element.

AdditionalHead viewlet and template is generated by paster. See source code for more information.

Overriding gomobiletheme.basic static media

References to static media are set in Head viewlet. You can override this viewlet and make static media to point to your own set of files. In this case, you need to copy the whole static folder from gomobiletheme.basic to your own theme product.

Example:

class Head(base.Head):
    """
    Override <head> generation so that we use CSS files
    and static resources specific to this skin.
    """

    def resource_url(self):
        """ Get static resource URL.

        See gomobiletheme.basic.viewlets.Head for more information.
        """

        # You need to copy whole gomobiletheme.basic/gomobiletheme/basic/statuc
        # folder to your own product and refer it here to use its CSS

        # return self.portal_url + "/" + "++resource++plonecommunity.app"

If you a running a very simple site and you do not wish to override any resources inherited from base theme package, you can use AdditionalHead viewlet to mix in <head> resources without overriding existing ones.

No viewlet managers

collective.fastview add-on is used to render viewlets directly and there are no viewlet managers in mobile theme. All mobile viewlets are registered against viewlet manager gomobiletheme.basic.viewlets.MainViewletManager.

Image transformations

HTML content transformations

All template code which contains WYSIWYG editable HTML should run through HTML processor to make it mobile compatible.

Theme examples

One maintained public example exists

Plone 3 compatibility

gomobiletheme.basic has some special arrangemenets to maintain backwards compatibility with Plone 3. Please see gomobiltheme.basic README.txt