Package: raptus.article.core
IntroductionThis 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:ContentArticle - Page Type - folderishComponentsRelated Items - Component - Component showing related Items.Otherzcml namespace (article) - used to initialize new components.InstallationStandard range raptus.articleImportant: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 ofraptus.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.coreTo 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 =
    PloneThis 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.coreNext 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-overridesOnce 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/buildoutIf everything went according to plan you now have raptus.article.core installed
in your Zope instance.Next, start up Zope using:$ bin/instance fgNext 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.UsageAdd articleIf you add a new article you will get the standard plone form to add content.ComponentsBy 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 thepypi-siteor install the packageraptus.article.default.Additional componentsIf 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 ofdefault 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 creditsraptus.article is copyrighted byRaptus AGand licensed under the GPL.
See LICENSE.txt for details.Developer ManualThis manual will give you an overview of the code of and teach you how to build
components for raptus.article.This manual will cover:IntroductionTargetArchitectureFeatures / key benefitsCode overviewThe component adapterZCMLContentInterfacesIndicesOverridesPackage dependenciesAdding a new componentIntroductionProvider for MyContent objectsComponent selectionComponents and viewletsUpdate profileFAQIntroductionTargetThe 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.ArchitectureThe 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 benefitsraptus.article uses the existing zope 3 architecture, there is no new architecture you
have to learnHeavily 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 ViewThe 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 theraptus.article.corepackage.Code overviewThe component adapterA 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:ViewletAs mentioned earlier each component needs a viewlet which is responsible for rendering
the component in the article view.Unique marker interfaceEach viewlet also requires a unique marker interfaces responsible for hiding and
showing it in context of an article.TitleThe title is used in the components view of the article.DescriptionA short descriptive text for the component used in the components view of the article.ImageA small presentation image showing how the component will displayed in the article
used in the components view of the article.ZCMLNew 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:AttributeDescriptionnameComponent namecomponentComponent classviewletViewlet classmanagerViewlet managerselectionFor which object this component may be selected
used if renders child objects like imagesimageDefaults to the one specified in the componentpermissionPermission 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.Contentarticle - Base content for the raptus.articleInterfacesThe 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)Indicesraptus.article.core adds a new index named “component” used for the component selection on content types
contained in articles.OverridesIn 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 dependenciesList of dependencies between the different raptus.article packagesraptus.article.additionalwysiwygarchetypes.schemaextenderraptus.article.coreraptus.article.contentfaderraptus.article.nestingraptus.article.coreraptus.article.teaserarchetypes.schemaextenderraptus.article.coreraptus.inlinelightboxraptus.article.contentflowraptus.article.nestingarchetypes.schemaextenderraptus.article.coreraptus.article.teaserarchetypes.schemaextenderplone.app.imagingProducts.jsImagePopupsraptus.article.coreraptus.contentflowraptus.article.defaultraptus.article.filesraptus.article.coreraptus.article.galleryraptus.article.imagesarchetypes.schemaextenderplone.app.imagingraptus.article.coreraptus.article.linksraptus.article.coreraptus.article.listingsraptus.article.nestingarchetypes.schemaextenderraptus.article.coreraptus.article.referenceraptus.article.nestingarchetypes.schemaextenderraptus.article.coreraptus.article.teaserraptus.article.coreraptus.article.faderraptus.article.imagesraptus.article.coreraptus.inlinelightboxraptus.article.flashhexagonit.swfheaderProducts.ContentTypeValidatorraptus.article.coreraptus.article.formProducts.PloneFormGenraptus.article.coreraptus.article.headerraptus.article.coreraptus.headerraptus.article.hidecolumnsarchetypes.schemaextenderraptus.article.coreraptus.article.lightboxraptus.article.imagesraptus.article.coreraptus.inlinelightboxraptus.article.lightboxgalleryraptus.article.imagesarchetypes.schemaextenderplone.app.imagingraptus.article.coreraptus.carouselraptus.inlinelightboxraptus.article.mapsraptus.article.coreraptus.googlemapsraptus.article.mediacollective.flowplayerplone.app.imagingProducts.ContentTypeValidatorraptus.article.coreraptus.article.multilanguagefieldsraptus.article.coreraptus.multilanguageplonearchetypes.schemaextenderraptus.multilanguagefieldsraptus.article.randomcontentraptus.article.nestingarchetypes.schemaextenderraptus.article.coreraptus.article.randomimageraptus.article.imagesarchetypes.schemaextenderplone.app.imagingraptus.article.coreraptus.article.tablearchetypes.schemaextenderraptus.article.coreraptus.article.uploadcollective.uploadifyraptus.article.filesraptus.article.coreraptus.article.imagesarchetypes.schemaextenderplone.app.imagingraptus.article.coreraptus.article.supersizedraptus.article.coreraptus.supersizedAdd new componentIntroductionThis 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 objectsFirst 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 selectionTo allow the selection of the components a MyContent object shall be displayed in
a new field calledcomponentsis 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 onplone.orgThe next step is to create the components itself.Components and viewletsAs earlier described a component consists of the following parts:title: Title of your componentdescription: Description of your componentimage: 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 viewletviewlet: Name of your viewletMarker interfaceSo 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
    """ComponentThe 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 = contextViewletNow 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 itemsNext 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 componentThe 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'ZCMLNow 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 profileLast 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>FAQQ: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 definedQ: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”Changelog2.2 (2016-12-19)Move translations tolocales/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 namedcomputeRelatedItems, 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 acropproperty 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 resourcecomponent.jstoraptus.article.component.jsto 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-folderishReplaced 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 adjustmentsImplemented drag’n’drop for raptus.article.table2.0b14 (2013-07-02)Removed event dispatch function to prevent double event notifications2.0b13 (2013-07-01)Component management reimplementationAdded drag’n’drop supportAdded component activated and deactivated eventsPEP 82.0b12 (2013-05-03)Improved component filter to no longer update every viewlet when filtering
and sorting2.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 presented2.0b9 (2012-01-23)plone 4.1 compatibility by importing cmfcore permissions2.0b8 (2011-03-21)Added links to the manageable adapter to show and hide items in a component2.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 items2.0b5 (2010-11-10)Added French translations2.0b4 (2010-10-21)Updated readme and manual2.0b3 (2010-10-20)First public release