1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303

======================
 Theming
======================

.. admonition:: Description

        Creating mobile themes for Plone with Web and Mobile

.. contents :: :local:

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 <http://svn.plone.org/svn/collective/collective.developermanual/trunk/source/tutorials/paste.txt>`_ 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 <http://collective-docs.plone.org/components/grok.html>`_.

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.

Change footer
===================

In viewlets.py add::
        
        class FooterText(base.FooterText):
            """ Free-form HTML text at the end of the page """
        
            # the presence of this viewlet includes a new page template 
            # and overrides default footertext
            
           
Add new file to the your theme package ``templates/footertext.pt``::

.. code-block:: html

        <div id="footer-text" i18n:domain="isleofback.app">
                Your text goes here.
        </div>


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 :doc:`Transformations </developer-manual/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 :doc:`mobile image resize </developer-manual/transformations>`

HTML content transformations
============================== 

All template code which contains WYSIWYG editable HTML should run through 
:doc:`HTML processor </developer-manual/transformations>` to make it mobile compatible.

Theme examples
-----------------------

One maintained public example exists

* plonecommunity.mobi `site <http://plonecommunity.mobi>`_ and the `source code <http://plonegomobile.googlecode.com/svn/trunk/gomobile/plonecommunity.app>`_

Plone 3 compatibility
---------------------------

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