.. :contents:

Introduction

A simple Plone add-on / theme skeleton with instructions

This project is a sane Plone 4 add-on / theme template which provides youraddon code skeleton. It allows you to quicky start developing your own Python, CSS and JS code for Plone.

The skeleton is not limited to visual aspects, but allow customizing Plone UI aspects beyond simple CSS changes or HTML transformations easily. It is intended to replace the old ZopeSkel plone add-on template with a version embracing modern development best practices.

Supported Plone versions

Supported Plone versions are 4.1 and above. Dexterity pindowns are required, though there is no dependency on the plone.app.dexterity package, only on five.grok.

Goals

• EASY

• Well documented, follows best practices, references up-to-date documentation

• Provides a basic solution for basic theming and UI customizations needs with documented instructions

• Minimum boilerplate: no unnecessary ZCML or folder structure, etc. Based on Grok and Dexterity frameworks

• main.css and main.js where front-end developers can directly copy-paste their code

• Multilingual support (i18n)

• Good folder structure: flat is better than nested

This is a barebone code drop and does not depend on any more or less crappy Python templating solutions. There is no need for using code generators, because actions like adding a view are simple code copy-pastes following the sane defaults and Don't Repeat Yourself (DRY) principles.

Just clone it to your installation as src/youraddon, make sure the necessary buildout changes have been made, hack and go.

Benefits over through-the-web customizations

Old Zope 2 customization methods of using Zope Management Interface are seriously limited and rarely take you even half-way of your development needs. But youraddon template:

• Provides full power of Python. File system based editing, giving 100% full access to change everything vs. old ZMI based through-the-web overrides. Use real text editor instead of .</p> </li> <li> <p>Your code can go properly under version control</p> </li> <li> <p>Embraces modern development practices, like GitHub, jQuery and stuff</p> </li> <li> <p>You can still have the speed of instant code changes using the <code>sauna.reload</code>_ package as described below</p> </li> </ul> <p>NO MORE THROUGH-THE-WEB PYTHON SCRIPTS, EVER, FOR ANYONE. DO NOT DO ADD NEW... SCRIPT (PYTHON), COMPRENDE? NO MORE EDITING IN PUNY TEXTAREA, USE YOUR FAVORITE EDITOR, WITH SYNTAX HIGHLIGHTING. NO MORE UNAUTHORIZED EXCEPTION - IMPORT ALL PYTHON MODULES YOU WISH. NO MORE ZSQL METHODS. FEEL FREE.. OF ALL THAT LEGACY CRAP. FEEL THE AGILE DEVELOPMENT RUNNING IN YOUR VEINS. INVENT, CREATE, ENJOY. </p> <p>Of course, one cannot understand this pain unless has gone through Plone 2... Plone 4. Just forget all other tutorials and do as said here.</p> <h2>Prerequisites</h2> <ul> <li> <p>Working UNIX environment (Cygwin for Windows should be fine)</p> </li> <li> <p>Basic command-line usage knowledge</p> </li> </ul> <h2>Usage</h2> <p><strong>Follow these instructions carefully</strong>. No warranty for users who did not read the instructios.</p> <p>Get the template source code from GitHub and clone it to the <code>src/</code> folder under your Plone installation folder::</p> <pre><code>cd src git clone git@github.com:miohtama/sane_plone_addon_template.git youraddon</code></pre> <p>Add <code>Dexterity extends line <http://plone.org/products/dexterity/documentation/how-to/install></code>_ to your <code>buildout.cfg</code>::</p> <pre><code>extends = ... some lines here ... http://good-py.appspot.com/release/dexterity/1.2?plone=4.1.4</code></pre> <p>Note that this depends on Plone version. Fix to match to your version.</p> <p>Add the following bits to <code>buildout.cfg</code> to install the code skeleton add-on::</p> <pre><code>develop = src/youraddon eggs = ... youraddon</code></pre> <p>.. Note:: If you want to call Python package something different than <code>youraddon</code> you can change this by running the <code>personalize.py</code> command later. Renaming is not necessary for the code skeleton to work and the instructions have been written with the original name in mind.</p> <p>Then follow standard Plone add-on installation instructions of re-running buildout and activating the add-on:</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://plone.org/documentation/kb/installing-add-ons-quick-how-to">http://plone.org/documentation/kb/installing-add-ons-quick-how-to</a></li> </ul> <p>After the <em>youraddon</em> add-on is installed in the Plone control panel you should see a pony greeting you instead of the Plone site logo, showing that the code skeleton examples are active. </p> <p>Now you can proceed to start adding your own code bits. See the Tasks_ section below for recipes for most common Plone customization needs. </p> <h2>Bootstrapping the development of your own add-on</h2> <p>The default <code>youraddon</code> installation comes with some sample customizations highlighting the best pratices. These customizations are examples which are referred in documentation how to accomplish certain development tasks with Plone. <code>youraddon</code> installation is usable for tinkering as is.</p> <p>However, you are supposed to remove these example customizations and rename the add-on when you adapt the code skeleton for your own needs.</p> <p>You can do this with the <code>personalize.py</code> script. The script will remove all example view, viewlet, CSS and JS examples by removing source code lines between <code>EXAMPLES START</code> and <code>EXAMPLES END</code> markers. The script will also give a new name to the Python package.</p> <p>Before you run <code>personalize.py</code>, uninstall the <code>youraddon</code> add-on from your site if you installed it there.</p> <p>Then run personalize::</p> <p>cd src/youraddon</p> <h1>Will create a copy src/mycompanyaddon out of youraddon</h1> <h1>with all examples removed</h1> <p>./personalize.py mycompanyaddon </p> <p>Please note that the template discourages usage of namespaces. Namespaces are not needed for your own customizations and cause extra boilerplate. If you wish to use namespaces like <code>collective</code> or <code>plone.app</code> you can manually shuffle files and folders around later.</p> <p>Now <code>src/mycompanyaddon</code> has been created. <code>src/youraddon</code> will be still around for further templating.</p> <p>You need to do corresponding name changes in <code>buildout.cfg</code> and re-run buildout. Then restart Plone, and install the <code>mycompanyaddon</code> add-on.</p> <p><em>personalize</em> will also remove the original version control files from the new add-on.</p> <p>Note that currently <em>personalize</em> is a one-time operation, not incremental, and you cannot update to more recent version of the code skeleton. </p> <h2>Theme or add-on</h2> <p>The difference between Plone theme and Plone add-on is that only one theme can be active at a time. Resources like views, static media, etc. depend on whether the theme / add-on layer is active or not.</p> <ul> <li> <p>The theme layer is activated through the <code>portal_skins</code> <em>properties</em> tab (<em>Default skin</em> option matches <code>configure.zcml</code> declaration)</p> </li> <li> <p>Add-on layer is activated when add-on is <em>installed</em> (activated via <code>browserlayers.xml</code>)</p> </li> </ul> <p>The code skeleton default behavior is add-on like. You can change it to theme-like behavior by:</p> <ul> <li> <p>Uncommenting directives in <code>profiles/defaul/skins.xml</code>.</p> </li> <li> <p>Changing <code>grok.layer()</code> directives from <code>IAddonSpecific</code> to <code>IThemeSpecific</code>.</p> </li> </ul> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/layers.html">http://collective-docs.readthedocs.org/en/latest/views/layers.html</a></li> </ul> <h2>Theory of add-on development</h2> <p>You do not replace Plone functionality by messing with Plone files directly. Instead you:</p> <ul> <li> <p>extend Plone to add new functionality;</p> </li> <li> <p>override Plone to customize out-of-the-box functionality.</p> </li> </ul> <p>Overrides and extensions become effective when your add-on is installed and the effect disappears when your add-on is uninstalled.</p> <p>This way you keep your own customizations separate from Plone core. You do not ever edit Plone core source code files directly. If you do this, your edited files will be replaced by updated versions when Plone is updated. This holds true for all CMSes, not just for Plone. Never edit anything under the <code>parts/</code> or <code>eggs/</code> folders in your Plone installation.</p> <p>Plone has a mechanism called <em>layers</em>, specifying which add-on / theme parts are effective. Once your add-on is installed, its layer takes the highest priority in the Plone installation, overriding functionality with lower priority. </p> <p>Layers are the central element of well-functioning plug-in architecture, ensuring that add-ons don't step on each others toes, resulting in code conflicts.</p> <h2>Dive into</h2> <p>This source code provides the Python package (a.k.a. <em>egg</em>) <code>youraddon</code>. The package can be used as a Plone add-on to override Plone user interface functionality easily.</p> <p>The folder layout follows Python package layout where you have:</p> <ul> <li> <p>a top-level folder with <code>setup.py</code> package metadata;</p> </li> <li> <p><code>youraddon</code> Python module;</p> </li> <li> <p><code>static</code> <code>Grok static folder <http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/resourcefolders.html#grok-static-media-folder></code>_ for images, CSS and Javascript;</p> </li> <li> <p><code>views.py</code> and <code>viewlets.py</code> for Plone user interface element declarations;</p> </li> <li> <p>standard <code>configure.zcml</code> Zope 3 boiler-plate - no need to touch here.</p> </li> </ul> <h2>Tasks</h2> <p>Here are quick pointers for common theming / Plone UI customization related development tasks. </p> <h1>Automatic Plone restarts</h1> <p>Use <code>sauna.reload</code>_ on UNIX systems to reload your code automatically. This will considerably increase your working effectiveness.</p> <p>When in development mode, even if not using <code>sauna.reload</code>, Plone reloads the following bits automatically:</p> <ul> <li> <p><code>.pt</code> page templates</p> </li> <li> <p>CSS</p> </li> <li> <p>Javascript</p> </li> <li> <p><code>profiles/default</code> XML files</p> </li> </ul> <p>The following code is not reloaded:</p> <ul> <li> <p>Python</p> </li> <li> <p>ZCML</p> </li> </ul> <h1>Validating source files</h1> <p><code>VVV <http://pypi.python.org/pypi/vvv></code>_ is used to provide validation support for</p> <ul> <li> <p>CSS</p> </li> <li> <p>Javascript </p> </li> <li> <p>Python </p> </li> <li> <p>Restructured text files</p> </li> </ul> <p>Please consult <em>VVV</em> documentation how to install pre-commit hooks which prevent you to accidentally committing files containing validation or linting errors.</p> <h1>Add a view</h1> <p>Views present functionality or content. Views can be associated with content types or site root.</p> <p>A <em>HelloWorld</em> view example is provided in <code>views.py</code>. Feel free to copy-paste around.</p> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/browserviews.html">http://collective-docs.readthedocs.org/en/latest/views/browserviews.html</a></li> </ul> <h1>Finding view source code to override</h1> <p>Plone views can be:</p> <ul> <li> <p>view classes (new style): these come from Python packages.</p> </li> <li> <p>Pure page templates, no Python code attached (old style): these come from the <code>plone_skins</code> tool</p> </li> </ul> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/browserviews.html#finding-a-view-to-override">http://collective-docs.readthedocs.org/en/latest/views/browserviews.html#finding-a-view-to-override</a></li> </ul> <h1>Refer to static resources in page templates</h1> <p>Example::</p> <pre><code><img tal:attributes="src string:${context/portal_url}/++resource++youraddon/pony.png" alt="" /></code></pre> <p>More info:</p> <ul> <li> <p><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/resourcefolders.html">http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/resourcefolders.html</a></p> </li> <li> <p><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/images/templates.html">http://collective-docs.readthedocs.org/en/latest/images/templates.html</a></p> </li> </ul> <h1>Override a view template</h1> <p>Use <code>z3c.jbot</code> override by dropping a corresponding template in the <code>templates</code> folder.</p> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/browserviews.html">http://collective-docs.readthedocs.org/en/latest/views/browserviews.html</a> </li> </ul> <h1>Override a view class</h1> <p>Same as the add view, but you simply use <code>grok.name()</code> to declare the view name you want to override.</p> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/browserviews.html">http://collective-docs.readthedocs.org/en/latest/views/browserviews.html</a></li> </ul> <h1>Override an old style page template (skins overrides)</h1> <p>Use <code>z3c.jbot</code> override by dropping a corresponding template in the <code>templates</code> folder.</p> <p>More info</p> <ul> <li> <p><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/skin_layers.html#nested-folder-overrides-z3c-jbot">http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/skin_layers.html#nested-folder-overrides-z3c-jbot</a></p> </li> <li> <p><a rel="noreferrer nofollow" target="_blank" href="http://pypi.python.org/pypi/z3c.jbot">http://pypi.python.org/pypi/z3c.jbot</a></p> </li> </ul> <h1>Add a viewlet</h1> <p>An example provided in <code>viewlets.py</code> to adding a custom footer viewlet.</p> <p>More info:</p> <ul> <li> <p><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/browserviews.html">http://collective-docs.readthedocs.org/en/latest/views/browserviews.html</a></p> </li> <li> <p><a rel="noreferrer nofollow" target="_blank" href="http://grok.zope.org/doc/current/reference/components.html?highlight=viewlet#grok-viewlet">http://grok.zope.org/doc/current/reference/components.html?highlight=viewlet#grok-viewlet</a></p> </li> </ul> <p>Override a viewlet template ====================================================== </p> <p><code>z3c.jbot</code> override example provided for the site logo in <code>templates</code>.</p> <p>More info:</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://pypi.python.org/pypi/z3c.jbot">http://pypi.python.org/pypi/z3c.jbot</a></li> </ul> <h1>Override a viewlet</h1> <p>If you need to touch viewlet Python class code the easiest approach is to:</p> <ul> <li>copy-paste the orignal viewlet Python code as a whole;</li> <li>copy-paste the orignal viewlet template code as a whole.</li> </ul> <p>Then register your own viewlet with the name of the original using <code>grok.name()</code>.</p> <p>It's possible, though often suicidal, to try to extend the original viewlet and then override.</p> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/viewlets.html">http://collective-docs.readthedocs.org/en/latest/views/viewlets.html</a></li> </ul> <h1>Hide a viewlet</h1> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/viewlets.html">http://collective-docs.readthedocs.org/en/latest/views/viewlets.html</a></li> </ul> <h1>Changing viewlet manager layout</h1> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/views/viewlets.html">http://collective-docs.readthedocs.org/en/latest/views/viewlets.html</a></li> </ul> <h1>Override main template</h1> <p>To change Plone main presentation layout</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/template_basics.html#main-template">http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/template_basics.html#main-template</a></li> </ul> <h1>Add a portlet</h1> <h1>Override a portlet rendering</h1> <h1>Override CSS styles</h1> <h1>Override a logo</h1> <h1>Add a new CSS styles and file</h1> <p>Example provided in <code>main.css</code>.</p> <p>More info:</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/css.html">http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/css.html</a></li> </ul> <h1>Add new Javascript</h1> <p>Example provided in <code>main.js</code>.</p> <p>Plone should automatically reload CSS files in the development mode when you hit <em>Refresh</em>. in the browser.</p> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/javascript.html">http://collective-docs.readthedocs.org/en/latest/templates_css_and_javascripts/javascript.html</a></li> </ul> <h1>Change content type default view</h1> <h1>Creating new folder-like listing view</h1> <h1>Add a new dynamic view to a folder</h1> <h1>Add translated strings</h1> <p>You can add multilingual strings to user interface which are translated using <em>gettext</em>.</p> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/i18n/internalization.html">http://collective-docs.readthedocs.org/en/latest/i18n/internalization.html</a></li> </ul> <h1>Adding new language</h1> <p>You can include new languages in the translation mix.</p> <p>More info</p> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://collective-docs.readthedocs.org/en/latest/i18n/internalization.html">http://collective-docs.readthedocs.org/en/latest/i18n/internalization.html</a></li> </ul> <h2>Best practices</h2> <p>Here are listed some best practices which are recommended when working with Plone, Python and web development source code.</p> <h1>No tabs</h1> <p>All text editors: set save tabs as spaces, never use hard tabs.</p> <h1>Dynamically generated files</h1> <p><em>Never</em> add the following files to version control:</p> <ul> <li> <p>Various <code>.egg-info</code> folders (automatically generated when buildout runs)</p> </li> <li> <p><code>.mo</code> files (compiled gettext files recreated on Plone start-up)</p> </li> </ul> <h1>JSLint</h1> <ul> <li><a rel="noreferrer nofollow" target="_blank" href="http://opensourcehacker.com/2011/09/23/using-javascript-jslint-validator-in-eclipse-and-aptana-studio/">http://opensourcehacker.com/2011/09/23/using-javascript-jslint-validator-in-eclipse-and-aptana-studio/</a></li> </ul> <h1>PEP8</h1> <ul> <li>TODO </li> </ul> <h1>PyFlakes</h1> <ul> <li>TODO</li> </ul> <h2>Troubleshooting</h2> <p>If you get this::</p> <pre><code>PicklingError: Can't pickle <class 'youraddon.interfaces.IAddonSpecific'>: import of module youraddon.interfaces failed </code></pre> <p>This means that you did not follow uninstall instructions carefully. Re-add <code>youraddon</code> in <code>buildout.cfg</code>, re-run buildout, then uninstall it in Plone control panel and then re-remove from <code>buildout.cfg</code>. </p> <h2>Authors</h2> <ul> <li> <p><code>Mikko Ohtamaa <http://opensourcehacker.com></code>_</p> </li> <li> <p><code>Érico Andrei <https://twitter.com/#!/ericof></code>_</p> </li> <li> <p>Pony by <code>Lili / novotnaci <http://openclipart.org/detail/102193/foal-by-novotnaci></code>_</p> </li> </ul> <p>.. _sauna.reload: <a rel="noreferrer nofollow" target="_blank" href="http://pypi.python.org/pypi/sauna.reload">http://pypi.python.org/pypi/sauna.reload</a></p></div> </div> <div class="footer"> <ul class="body"> <li>© <script> document.write(new Date().getFullYear()) </script> Githubissues.</li> <li>Githubissues is a development platform for aggregating issues.</li> </ul> </div> <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script> <script src="/githubissues/assets/js.js"></script> <script src="/githubissues/assets/markdown.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/highlight.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/languages/go.min.js"></script> <script> hljs.highlightAll(); </script> </body> </html>