Theming

Description

Introduction

Go 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 Go Mobile theme is that Go Mobile theme name is read from the property:

portal_properties.mobile_properties.mobile_skin

Instead of standard:

portal_skins.default_skin

Best practices

  • Use namespace "gomobiletheme" for Go Mobile themes
  • Read Transformations for info about different CSS files and their purposes.

Creating your 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.

gomobiletheme.basic

A basic Plone 4 Sunburst like theme is supplied with Go Mobile for Plone (gomobiletheme.basic package). It is recommended that you recycle theme viewlets from this package.

See plonecommunity.app example how to do this.

Below are some notes for theming, used by gomobiletheme.basic You may or may not opt-in to use these practices.

Notes

  • Top actions viewlet (search icon, contact icon) is not supported on Plone 3

Customization 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 file for more information.

five.grok used

gomobiletheme.basic uses five.grok for viewlets and static media - this differs from old Plone 3 practice.

Inheriting templates

You can recycle and modify viewlets given in gomobiletheme.basic package in your custom theme.

Make sure five.grok is initializer properly in your product (five.grok directive in configure.zcml).

Create a viewlets.py code with the followind content:

from zope.interface import Interface
from five import grok

from collective.fastview.utilities import fix_grok_template_inheritance
from gomobiletheme.basic import viewlets as base
from gomobiletheme.basic.viewlets import MainViewletManager
from plonecommunity.app.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 the theme layer is activated
# 1) You must run add-on installer for your add-on product quick installer
# 2) You must access the site through mobile URL
grok.layer(IThemeLayer)

# Use this viewlet manager for mobile viewlets
grok.viewletmanager(MainViewletManager)

Since there is a problem with Grok 1.0 template inheritance (only Grok 1.0 works with Plone), you need to specially define if you want to use parent class templates instead of overriding templates in your viewlets.py code:

class Logo(base.Logo):
    """ Mobile site logo """

    def getLogoName(self):
        return "++resource++plonecommunity.app/plone-logo-white-on-blue.png"

# Fix for grok 1.0 template inheritance
# https://bugs.launchpad.net/grok/+bug/255005
fix_grok_template_inheritance(Logo, base.Logo)

Static media

Static media is provided by five.grok static folder mechanism.

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.

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.

See plonecommunity.app.interfaces for the example.

Avoid old style skins folder

For basic themes you generally don't need to customize main_template or old skin layers files, so you do not need to have skins structure in your own theme

  • <img> images should be run through mobile image resize
  • All template code which contains WYSIWYG editable HTML should run through HTML processor to make it mobile compatible.

Mobile theme specials

apple-touch-icon.png

This image is used as a bookmark icon by iPod/iPad/iPhone.

Examples

Full examples

See

  • plonecommunity.app for basic customizations (how to change logo, CSS files) and declare your own skin

Creating a theme skeleton

TODO: Full tutorial will be done.

Use Paster command to create a Plone 3 application.

Copy necessary changes by looking example in plonecommunity.app

  • setup.py

  • configure.zcml

  • interfaces.py

  • viewlets.py

  • profiles/default/skins.xml

  • profiles/defaukt/propertiestool.xml

  • Copy static media folder from gomobiletheme.basic as is.

  • Override head viewlet in viewlets.py

  • Override logo viewlet in viewlets.py

  • If you need to change main_template.pt, you need to also copy and modify from gomobiletheme.basic

    • skins/gomobiletheme_basic/main_template.pt to skins/yourtheme/main_template.pt
    • profiles/default/skins.xml
    • Add skins registration to configure.zcml

Declaring your theme

The following steps are needed to make Plone site aware of your theme, it is installable through add-on instalelr and it correctly extends the existing Go Mobile Default Theme.

  • Create propertiestool.xml which will set your theme as active mobile theme:

    <?xml version="1.0"?>
<object name="portal_properties" meta_type="Plone Properties Tool">
 <object name="mobile_properties" meta_type="Plone Property Sheet" title="Mobile site specific settings">
  <property name="mobile_skin" type="string" purge="False">mFabrik Mobile Theme</property>
 </object>
</object>

  • Declare dependency to Go Mobile Default Theme skin layer in skins.xml:

    <?xml version="1.0"?>
<object name="portal_skins" allow_any="False" cookie_persistence="False">

 <skin-path name="mFabrik Mobile Theme" based-on="Go Mobile Default Theme">
 </skin-path>

</object>

  • Declare your add-on installer profile

<genericsetup:registerProfile
    name="default"
    title="mFabrik Mobile Theme"
    directory="profiles/default"
    description='mFabrik theme for mobile sites'
    provides="Products.GenericSetup.interfaces.EXTENSION"
    />

  • Declare your theme interface which subclasses Go Mobile Default Theme:

    import gomobiletheme.basic.interfaces as base

class IThemeLayer(base.IThemeLayer):
    """ mFabrik mobile theme layer.

    """

  • Declare your theme layer for Zope

<interface
  interface=".interfaces.IThemeLayer"
  type="zope.publisher.interfaces.browser.IBrowserSkinType"
  name="mFabrik Mobile Theme"
  />

Note that two latter steps differ if five.grok grok.skin() directive is used.

Declaring dependency to gomobiletheme.basic

To use its main_template.pt add profiles/default/skins.xml to your theme package:

<?xml version="1.0"?>

<object name="portal_skins" allow_any="False" cookie_persistence="False">

         <!-- Declare dependency to gomobiletheme.basic so that its skin layeres are also included when this theme is installed -->
         <skin-path name="plonecommunity_mobi theme" based-on="Go Mobile Default Theme">
         </skin-path>


</object>

Plone 3 support

Your theme skins.xml must declare support for gomobiletheme_plone3:

<?xml version="1.0"?>
<object name="portal_skins" allow_any="False" cookie_persistence="False">

 <object name="saariselka_mobi"
    meta_type="Filesystem Directory View"
    directory="saariselka.mobi:skins/saariselka_mobi"/>

 <skin-path name="saariselka.mobi" based-on="Plone Go Mobile Default Theme">
  <layer name="saariselka_mobi" insert-after="custom"/>
  <layer name="gomobiletheme_plone3" insert-after="saariselka_mobi"/>
 </skin-path>

</object>
Last modified: Nov 17, 2010
Left arrow Previous: 2.3. Extending and customizing Next: 2.5. Transformations Right arrow