raptus.article.core 2.2

Provides a configurable article content type (replaces the default Page content type).

Introduction

This package provides a configurable article content type, which replaces the default Page content type.

The following features for raptus.article are provided by this package:

Content

• Article - Page Type - folderish

Components

• Related Items - Component - Component showing related Items.

Other

• zcml namespace (article) - used to initialize new components.

Installation

Standard range raptus.article

Important:

• Note that it is recommended to use the raptus.article.default package which depends on the base components of raptus.article for more details have a look at the install documentation of raptus.article.default. This installation only installs the core package.

• Note as well that it does not make sense to only install raptus.article.core if you don’t develop your own add-ons or install other packages of raptus.article as it provides more or less the same functionality as the default Page content type.

Install raptus.article.core

To install raptus.article.core into your Plone instance, locate the file buildout.cfg in the root of your Plone instance directory on the file system, and open it in a text editor.

Add the actual raptus.article.core add-on to the “eggs” section of buildout.cfg. Look for the section that looks like this:

eggs =
    Plone

This section might have additional lines if you have other add-ons already installed. Just add the raptus.article.core on a separate line, like this:

eggs =
    Plone
    raptus.article.core

Next step is to add the zcml files to the “zcml” section of buildout.cfg. Look for the section that looks like this:

zcml =

This section might have additional lines if you have other zcml’s already registered. Just add the raptus.article.core* on separate lines like this:

zcml =
    raptus.article.core-meta
    raptus.article.core
    raptus.article.core-overrides

Once you have added these lines to your configuration file, it’s time to run buildout, so the system can add and set up raptus.article.core for you. Go to the command line and from the root of your Plone instance (same directory as buildout.cfg is located in) run buildout like this:

$ bin/buildout

If everything went according to plan you now have raptus.article.core installed in your Zope instance.

Next, start up Zope using:

$ bin/instance fg

Next go to the “Add-ons” control panel in Plone as an administrator and install the “raptus.article.core” product. You should then be able to add a new content type called Article.

Usage

Add article

If you add a new article you will get the standard plone form to add content.

Components

By navigating to the “Components” tab you may select the components you would like to have displayed by this article.

Note if you only installed the raptus.article.core package there is just the component “Related Items” available. To add other components like image, files or links visit the pypi-site or install the package raptus.article.default.

Additional components

If you install the default package like the core package, you will get automatically the usual types like link, image, etc.. Besides if you install the article with default, you will not have to register all packages in buildout.cfg. The default package find automatically all component packages of raptus.article. For details read the doc of default package.

• raptus.article.default (Installs all raptus article components present in your buildout.cfg).

If you decide to group your components by yourself, here is a list of all currently available components. Install the selected packages like ratpus.article.core. Just be careful not all packages have an overrides.zcml and meta.zcml:

• raptus.article.additionalwysiwyg (Provides an additional WYSIWYG text field for the articles)

• raptus.article.contentfader (Provides a component which continually fades in and out the contained articles)

• raptus.article.contentflow (Provides a content flow component like the one used in iTunes)

• raptus.article.fader (Provides a component which continually fades in and out the contained images)

• raptus.article.files (Provides support for adding attachments to articles)

• raptus.article.flash (Provides support for flash movies)

• raptus.article.form (Provides support for PloneFormGen)

• raptus.article.gallery (Provides basic gallery components)

• raptus.article.header (Provides header image support by integrating raptus.header in article)

• raptus.article.hidecolumns (Provides functionality to hide the left or right portlet column per article)

• raptus.article.images (Provides support for adding images to articles)

• raptus.article.lightbox (Provides an inline lightbox component showing the images contained in the article)

• raptus.article.lightboxgallery (Provides an inline lightbox component with a horizontal gallery showing the images contained in the article)

• raptus.article.links (Provides support for adding links to articles)

• raptus.article.listings (Provides basic listing components which display articles contained in the article)

• raptus.article.maps (Provides a maps content type to be added to articles)

• raptus.article.media (Provides audio and video support for articles)

• raptus.article.multilanguagefields (Provides support for raptus.multilanguagefields in article)

• raptus.article.nesting (Provides nesting support for articles)

• raptus.article.randomcontent (Provides a component which displays a random article)

• raptus.article.randomimage (Provides components which display a random image contained in the article)

• raptus.article.reference (Provides support for internal or external references on nested articles)

• raptus.article.table (Provides a table component for articles)

• raptus.article.teaser (Provides support for a teaser image)

• raptus.article.upload (Provides multiupload functionality for articles using collective.uploadify)

• raptus.article.supersized (Provides an autoadjustung background-image slider component for articles)

Copyright and credits

raptus.article is copyrighted by Raptus AG and licensed under the GPL. See LICENSE.txt for details.

Developer Manual

This manual will give you an overview of the code of and teach you how to build components for raptus.article.

This manual will cover:

• Introduction

  • Target

  • Architecture

  • Features / key benefits

• Code overview

  • The component adapter

  • ZCML

  • Content

  • Interfaces

  • Indices

  • Overrides

• Package dependencies

• Adding a new component

  • Introduction

  • Provider for MyContent objects

  • Component selection

  • Components and viewlets

  • Update profile

• FAQ

Introduction

Target

The main target of raptus.article is to provide the content editor with a pre configured set of layout parts (called components) which he may use to build his page layout. The Article content type provided by raptus.article.core is a drop in replacement for the default Page content type.

Note that the components (layout parts) used by raptus.article are not linked directly to the zope 3 component architecture although they are built on it. We will use the word component for the components of raptus.article in the following document and will explicitly note if it is about a component of the zope 3 architecture.

Architecture

The architecture of raptus.article makes heavy use of the zope 3 viewlet architecture. A component is basically a viewlet with some metadata like a title, a descriptive text and an image. The viewlets used by the components are bound to the marker interface of the view of the article content type which ensures that they are only rendered when viewing an article. The viewlets are also bound to a unique marker interface which makes it possible to show and hide them in context by providing this interface or not.

Features / key benefits

• raptus.article uses the existing zope 3 architecture, there is no new architecture you have to learn

• Heavily based on the viewlets architecture and using its features to: - Order our components globally (viewlets.xml / @@manage-viewlets) - Activate/deactivate our components globally (viewlets.xml / @@manage-viewlets) - Show/Hide our components in context (marker interface)

Components View

The components view of is available for the article content type and is accessed through the content views tabs. The view is basically a enhanced and filtered version of the interfaces tab in the ZMI. It lists all registered and activated components by their title, description and image and allows to show or hide them. By saving the view simply sets or unsets the marker interfaces mapped to the components which will show or hide them in the view of the article. This basic functionality is provided by the raptus.article.core package.

Code overview

The component adapter

A component is an adapter implementing IComponent and adapting IArticle which links the required parts for selecting and rendering. The following parts are part of a component:

Viewlet

As mentioned earlier each component needs a viewlet which is responsible for rendering the component in the article view.

Unique marker interface

Each viewlet also requires a unique marker interfaces responsible for hiding and showing it in context of an article.

Title

The title is used in the components view of the article.

Description

A short descriptive text for the component used in the components view of the article.

Image

A small presentation image showing how the component will displayed in the article used in the components view of the article.

ZCML

New components are registered through zcml by using the component directive of the newly provided article namespace.:

<article:component
    name="related"
    component=".related.Component"
    viewlet=".related.Viewlet"
    manager="plone.app.layout.viewlets.interfaces.IBelowContentBody" />

The definition for the zcml directive is located in the file meta.zcml in the IComponentDirective interface.

The schema of the component directive consists of the following parameters:

Attribute	Description
name	Component name
component	Component class
viewlet	Viewlet class
manager	Viewlet manager
selection	For which object this component may be selected used if renders child objects like images
image	Defaults to the one specified in the component
permission	Permission needed to view the viewlet defaults to “zope.Public”

The directive will then register the component adapter, the viewlet for the specified manager using the specified permission, the image if present and the component selection adapter if specified.

Content

• article - Base content for the raptus.article

Interfaces

The following interfaces are defined by raptus.article.core.

• IArticle (Marker interface for the article content type)

• IArticleView (Marker interface for the article view)

• IComponents (Provides information about available and active components)

  • getComponents - method (Returns a list of available components)

  • activeComponents - method (Returns a list of the active components)

• IComponent (A component definition)

  • title - attribute (User friendly title of the component)

  • description - attribute (User friendly description of the component)

  • image - attribute (Presentation image for the component)

  • interface - attribute (The unique marker interface the viewlet is bound to)

  • viewlet - attribute (The name of the viewlet rendering the component)

• IComponentFilter (Filters and sorts components based on the registration of their viewlets)

  • filter - method (Returns a filtered list of components)

• IComponentSelection (A component selection registering a component for selection on a content type)

• IDefaultComponents (Provider to define default components for newly created articles)

  • getComponents - method (Returns a list of components which should be activated)

• INamedDefaultComponent (Provider to define a default component using a named adapter)

• IManageable (Catalog results converter used for the manage macro for objects which are manageable)

  • getList - method (Returns a list of dicts holding the specific links for viewing, editing, sorting and deleting the object based on a list of catalog brains)

Indices

raptus.article.core adds a new index named “component” used for the component selection on content types contained in articles.

Overrides

In the zcml file /browser/overrides.zcml we override the following browser components:

• plone_contentmenu_factory (/browser/menu.py)

• folder_factories (/browser/folderfactories.py)

Which allows adding new content to default pages set on a folder.

Package dependencies

List of dependencies between the different raptus.article packages

• raptus.article.additionalwysiwyg

  • archetypes.schemaextender

  • raptus.article.core

• raptus.article.contentfader

  • raptus.article.nesting

    • raptus.article.core

  • raptus.article.teaser

    • archetypes.schemaextender

    • raptus.article.core

  • raptus.inlinelightbox

• raptus.article.contentflow

  • raptus.article.nesting

    • archetypes.schemaextender

    • raptus.article.core

  • raptus.article.teaser

    • archetypes.schemaextender

    • plone.app.imaging

    • Products.jsImagePopups

    • raptus.article.core

  • raptus.contentflow

• raptus.article.default

  • raptus.article.files

    • raptus.article.core

  • raptus.article.gallery

    • raptus.article.images

      • archetypes.schemaextender

      • plone.app.imaging

      • raptus.article.core

  • raptus.article.links

    • raptus.article.core

  • raptus.article.listings

    • raptus.article.nesting

      • archetypes.schemaextender

      • raptus.article.core

  • raptus.article.reference

    • raptus.article.nesting

      • archetypes.schemaextender

      • raptus.article.core

  • raptus.article.teaser

    • raptus.article.core

• raptus.article.fader

  • raptus.article.images

    • raptus.article.core

  • raptus.inlinelightbox

• raptus.article.flash

  • hexagonit.swfheader

  • Products.ContentTypeValidator

  • raptus.article.core

• raptus.article.form

  • Products.PloneFormGen

  • raptus.article.core

• raptus.article.header

  • raptus.article.core

  • raptus.header

• raptus.article.hidecolumns

  • archetypes.schemaextender

  • raptus.article.core

• raptus.article.lightbox

  • raptus.article.images

    • raptus.article.core

  • raptus.inlinelightbox

• raptus.article.lightboxgallery

  • raptus.article.images

    • archetypes.schemaextender

    • plone.app.imaging

    • raptus.article.core

  • raptus.carousel

  • raptus.inlinelightbox

• raptus.article.maps

  • raptus.article.core

  • raptus.googlemaps

• raptus.article.media

  • collective.flowplayer

  • plone.app.imaging

  • Products.ContentTypeValidator

  • raptus.article.core

• raptus.article.multilanguagefields

  • raptus.article.core

  • raptus.multilanguageplone

    • archetypes.schemaextender

    • raptus.multilanguagefields

• raptus.article.randomcontent

  • raptus.article.nesting

    • archetypes.schemaextender

    • raptus.article.core

• raptus.article.randomimage

  • raptus.article.images

    • archetypes.schemaextender

    • plone.app.imaging

    • raptus.article.core

• raptus.article.table

  • archetypes.schemaextender

  • raptus.article.core

• raptus.article.upload

  • collective.uploadify

  • raptus.article.files

    • raptus.article.core

  • raptus.article.images

    • archetypes.schemaextender

    • plone.app.imaging

    • raptus.article.core

• raptus.article.supersized

  • raptus.article.core

  • raptus.supersized

Add new component

Introduction

This is a short manual on how to create a new content type used in the article. If you already have a content type and you would like to integrate with raptus.article this manual is of use too.

In this example we will be adding a new content type called MyContent which will be addable in articles and two component which will render a list of the contained MyContent objects one above and one below the content body.

Provider for MyContent objects

First we write a new adapter which will return all MyContent objects contained in an article. To do so we need an interface defining the functionality of the adapter which we place in interfaces.py:

from zope.interface import Interface

class IMyContents(Interface):
    """ Provider for mycontent objects contained in an article
    """

    def getMyContents(**kwargs):
        """ Returns a list of mycontents (catalog brains)
        """

Now we write an adapter implementing this interface and adapting IArticle and place it in adapters.py:

from zope import interface, component

from Products.CMFCore.utils import getToolByName

from raptus.article.core.interfaces import IArticle
from my.content.interfaces import IMyContents

class MyContents(object):
    """ Provider for mycontent objects contained in an article
    """
    interface.implements(IMyContents)
    component.adapts(IArticle)

    def __init__(self, context):
        self.context = context

    def getMyContents(self, **kwargs):
        """ Returns a list of MyContent (catalog brains)
        """
        catalog = getToolByName(self.context, 'portal_catalog')
        return catalog(portal_type='MyContent', path={'query': '/'.join(self.context.getPhysicalPath()),
                                                      'depth': 1}, sort_on='getObjPositionInParent', **kwargs)

Last but not least we have to register the adapter using zcml:

<adapter
  factory=".adapters.MyContents" />

Component selection

To allow the selection of the components a MyContent object shall be displayed in a new field called components is required. We therefor have to alter the schema of the MyContent class and add one new field:

...

from raptus.article.core.componentselection import ComponentSelectionWidget

...

atapi.LinesField('components',
    enforceVocabulary = True,
    vocabulary_factory = 'componentselectionvocabulary',
    storage = atapi.AnnotationStorage(),
    schemata = 'settings',
    widget = ComponentSelectionWidget(
        description = _(u'description_component_selection_table', default=u'Select the components in which this content should be displayed.'),
        label= _(u'label_component_selection', default=u'Component selection'),
    )
),

...

To allow the component to search for the MyContent objects who have him selected we use the index created by raptus.article.core named “component”. To do so we need to register a new indexer for this field which we place in index.py:

from zope import interface, component
from plone.indexer.interfaces import IIndexer
from Products.ZCatalog.interfaces import IZCatalog
from my.content.interfaces import IMyComponent

class Index(object):
    interface.implements(IIndexer)
    component.adapts(IMyContent, IZCatalog)
    def __init__(self, obj, catalog):
        self.obj = obj
    def __call__(self):
        return self.obj.Schema()['components'].get(self.obj)

We also have to register this index using zcml:

<adapter
  factory=".index.Index"
  name="component" />

And if we would like to have all available components selected in the components field we have to register a default provider for archetypes which is already implemented in raptus.article.core and only has to be registered in zcml:

<adapter
  factory="raptus.article.core.componentselection.ComponentSelectionDefault"
  for=".interfaces.IMyContent"
  name="components" />

This manual will not cover the basic steps to create a new content type documentation to do so is available on plone.org

The next step is to create the components itself.

Components and viewlets

As earlier described a component consists of the following parts:

• title: Title of your component

• description: Description of your component

• image: If you want, design an own image, but you can also choose one of the existing images. Have a look on the existing extensions.

• interface: Unique marker interface for the viewlet

• viewlet: Name of your viewlet

Marker interface

So we first create our marker interface and place it in browser/mycontents.py:

from zope import interface

...

class IMyContentAbove(interface.Interface):
    """ Marker interface for the mycontent viewlet displayed above the content body
    """

Component

The next step is to create the component adapter responsible for providing meta data used in the components view and linking it with the viewlet. We place also it in browser/mycontents.py:

from zope import interface, component

from raptus.article.core import RaptusArticleMessageFactory as _
from raptus.article.core import interfaces

...

class ComponentAbove(object):
    """ Component which lists mycontent objects above the content body
    """
    interface.implements(interfaces.IComponent, interfaces.IComponentSelection)
    component.adapts(interfaces.IArticle)

    title = _(u'MyContent above body')
    description = _(u'List of mycontents contained in the article above the content body.')
    image = '++resource++mycontent_above.gif'
    interface = IMyContentAbove
    viewlet = 'my.content.mycontent.above'

    def __init__(self, context):
       self.context = context

Viewlet

Now we will write the corresponding viewlet class based on ViewletBase.

Note that if we define our template with using the index attribute we will be able to overwrite it using zcml in a theme project.

from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile
from plone.app.layout.viewlets.common import ViewletBase
from raptus.article.core.interfaces import IManageable
from my.content.interfaces import IMyContents

...

class ViewletAbove(ViewletBase):
    """ Viewlet listing the mycontents above the content body
    """
    index = ViewPageTemplateFile('mycontents.pt')
    component = 'mycontent.above'

    def mycontents(self):
      provider = IMyContents(self.context)
      manageable = interfaces.IManageable(self.context)
      items = manageable.getList(provider.getMyContents(component=self.component), self.component)
      for item in items:
          item.update({'title': item['brain'].Title,
                       'description': item['brain'].Description})
      return items

Next we will write the page template and place it in mycontents.pt:

<ul class=""
    i18n:domain="raptus.article"
    tal:condition="view/mycontents"
    tal:attributes="class string:visualNoMarker manageableList mycontents">
  <tal:item repeat="item view/mycontents">
  <li class="component"
      tal:attributes="class string:component">
    <metal:manage use-macro="context/raptus_article_macros/macros/manage" />
    <h2 tal:content="item/title">
      Title
    </h2>
    <p tal:condition="item/description"
       tal:content="item/description">
      Description
    </p>
  </li>
  </tal:item>
</ul>

Second component

The same we do for our second component and also place it in the file browser/mycontents.py:

class IMyContentBelow(interface.Interface):
    """ Marker interface for the mycontent viewlet displayed below the content body
    """

class ComponentBelow(object):
    """ Component which lists mycontent objects below the content body
    """
    interface.implements(interfaces.IComponent, interfaces.IComponentSelection)
    component.adapts(interfaces.IArticle)

    title = _(u'MyContent above body')
    description = _(u'List of mycontents contained in the article below the content body.')
    image = '++resource++mycontent_below.gif'
    interface = IMyContentBelow
    viewlet = 'my.content.mycontent.below'

    def __init__(self, context):
       self.context = context

class ViewletBelow(ViewletAbove):
    """ Viewlet listing the mycontents below the content body
    """
    component = 'mycontent.below'

ZCML

Now we have to register our newly created components using zcml:

<configure
    xmlns="http://namespaces.zope.org/zope"
    xmlns:article="http://namespaces.zope.org/article"
    i18n_domain="raptus.article">

  <article:component
    name="mycontent.above"
    component=".mycontents.ComponentAbove"
    selection="..interfaces.IMyContent"
    viewlet=".mycontents.ViewletAbove"
    manager="plone.app.layout.viewlets.interfaces.IAboveContentBody" />

  <article:component
    name="mycontent.below"
    component=".mycontents.ComponentBelow"
    selection="..interfaces.IMyContent"
    viewlet=".mycontents.ViewletBelow"
    manager="plone.app.layout.viewlets.interfaces.IBelowContentBody" />

</configure>

Update profile

Last but not least we edit our generic setup profile. First we have to add MyContent to the addable types of the Article to make it possible to add MyContent objects in articles. To do so we have to add the Article to the types.xml file and create a Article.xml in profiles/default/types.

types.xml:

<?xml version="1.0"?>
<object name="portal_types" meta_type="Plone Types Tool">

  ...

  <object name="Article"
    meta_type="Factory-based Type Information with dynamic views" />

  ...

</object>

Article.xml:

<?xml version="1.0"?>
<object name="Article"
   meta_type="Factory-based Type Information with dynamic views"
   i18n:domain="raptus.article" xmlns:i18n="http://xml.zope.org/namespaces/i18n">
  <property name="allowed_content_types" purge="False">
    <element value="MyContent" />
  </property>
</object>

Next we add our newly created viewlets into viewlets.xml to define their default position:

<?xml version="1.0"?>
<object>

  ...

  <order manager="plone.abovecontentbody" skinname="*">
    <viewlet name="my.content.mycontent.above" insert-before="*" />
  </order>
  <order manager="plone.belowcontentbody" skinname="*">
    <viewlet name="my.content.mycontent.below" insert-after="*" />
  </order>

  ...

</object>

FAQ

Q:

If I start my instance, I’ll get this Error: ConfigurationError: (‘Unknown directive’, u’http://namespaces.zope.org/article’, u’component’)

A:

You have to include the raptus.article.core package in your configure.zcml. Otherwise the article zcml namespace is not defined

Q:

I would like to add my new content type in my article. If I’ll save and create the content, I’ll get the this Error: KeyError: ‘components’

A:

The problem is you have to extend the schema of your content type with the ComponentSelectionDefault field. Have a look to “add new component”

Changelog

2.2 (2016-12-19)

• Move translations to locales/ to be able to add/modify translations in none-Zope2 packages too [fRiSi]

2.1 (2014-10-23)

• Support different image fieldnames within the same component (fixed js scope bug) and use .component as selector for an item (cropping is compatible with raptus.article.listing and gallery this way)

2.0 (2014-07-28)

• Introduce a new marker interface (INamedDefaultComponent) and ready to use adapter implementation to allow simple registrations of default components by using named adapters (this fixes #5) [skaeser]

• Make textfield a primary field (as it’s the case for default document type) to prevent certain versions of plone’s TinyMCE integration to raise AttributeErrors when searching for anchors (this fixes #3) [fRISi]

2.0b19 (2014-07-22)

• Refactored the related items component of raptus articles (fixed issue #7).

  The previous implementation was based on the deprecated python script named computeRelatedItems, no more available on Plone 4.3.2. [davidemoro]

2.0b18 (2014-06-16)

• Show Link to plone.app.imagecropping croppingeditor if the component adds a crop property to the manageable list items pointing to the editor (eg path/to/image/@@croppingeditor?scalename=thumb)

  The croppingeditor is opened in an overlay and the cropped image gets updated when the editor is closed. [fRiSi]

• rename resource component.js to raptus.article.component.js to prevent name conflicts. [fRiSi]

2.0b17 (2013-12-17)

• The article view now implements IViewView to support plone.app.discussion when manually activated see: http://stackoverflow.com/questions/10402918/can-not-activate-discussions-on-plone-dexterity-types-folderish

• Replaced deprecated getIcon() with getIconExprObject()

2.0b16 (2013-07-22)

• CSS adjustments (added z-index for article-toggle and article-manage)

• Plone 4.3 compatibility [tmassman]

2.0b15 (2013-07-02)

• Made some minor CSS adjustments

• Implemented drag’n’drop for raptus.article.table

2.0b14 (2013-07-02)

• Removed event dispatch function to prevent double event notifications

2.0b13 (2013-07-01)

• Component management reimplementation

• Added drag’n’drop support

• Added component activated and deactivated events

• PEP 8

2.0b12 (2013-05-03)

• Improved component filter to no longer update every viewlet when filtering and sorting

2.0b11 (2013-03-11)

• Italian translations [vito80ba]

2.0b10 (2012-03-21)

• Changed permission for view of articles from zope.Public to zope2.View to prevent odd behaviour if accessing private article with title and description hidden where a completely unstyled login form was presented

2.0b9 (2012-01-23)

• plone 4.1 compatibility by importing cmfcore permissions

2.0b8 (2011-03-21)

• Added links to the manageable adapter to show and hide items in a component

2.0b7 (2011-01-20)

• Fixed AttributeError raised if a Viewlet has been customized ttw, which resulted in a TTWViewletRenderer object which has no __name__ attribute (Thanks to Ron Zayac for reporting it)

2.0b6 (2010-11-25)

• Fix Namespace on related items

2.0b5 (2010-11-10)

• Added French translations

2.0b4 (2010-10-21)

• Updated readme and manual

2.0b3 (2010-10-20)

• First public release