Theming¶
Description
Creating mobile themes for Plone with Web and Mobile
- Introduction
- Namespace and Python package name recommendations
- Creating a mobile theme
- Writing your first theme
- Theme examples
- Plone 3 compatibility
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.
Overring the logo¶
Change the generated gomobile.yourcompany.viewlets.Logo class. In the example below we set it to use logo from our web theme.
class Logo(base.Logo):
# Change logo URI here def getLogoPath(self):
return "++resource++plonetheme.yourwebtheme.images/logo.png"
If you are using logo from the web theme resource directory, make sure <resourceDirectory> in theme browser/configure.zcml does not have <resourceDirectory layer=""> set. If it's set the resource directory is not activate for the mobile theme and the mobile theme cannot access the logo file.
The logo image is resized automatically by gomobiletheme.basic.viewlets.Logo
base class
for different mobile screen resolutions.
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
.
Making your own touch friendly link listing¶
Use the following mark-up in the template:
<ul class="button-links">
<li>
<a tal:attributes="href item/absolute_url">
<span class="button-body">
<span class="button-inner" tal:content="item/Title" />
</span>
</a>
</li>
</ul>
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¶
- <img> images should be run through mobile image resize
HTML content transformations¶
All template code which contains WYSIWYG editable HTML should run through HTML processor to make it mobile compatible.
Plone 3 compatibility¶
gomobiletheme.basic
has some special arrangemenets
to maintain backwards compatibility with Plone 3.
Please see gomobiltheme.basic
README.txt