Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/collective/collective.cover

A sane, working, editor-friendly way of creating front pages and other composite pages. Working now, for mere mortals.
https://github.com/collective/collective.cover

Last synced: 3 months ago
JSON representation

A sane, working, editor-friendly way of creating front pages and other composite pages. Working now, for mere mortals.

Lists

README 

        
****************

collective.cover

****************



.. contents:: Table of Contents



Life, the Universe, and Everything

----------------------------------



``collective.cover`` is a package that allows the creation of elaborate covers

for website homepages, especially for news portals, government sites and

intranets that require more resources than a simple page or collection can

offer. However, despite offering rich resources to build a cover,

``collective.cover`` also provides a very easy mechanism for managing its

contents, built around a drag-and-drop interface.



``collective.cover`` is based on `Blocks `_ and `Tiles `_,

like `Mosaic `_,

the new layout solution for Plone.



.. note::

    Starting from version 2.0b1 this package is compatible with Plone 5.1;

    nevertheless, there are some `known issues `_.



Demo

^^^^



For impatient types, there is a demo installation of collective.cover on `Heroku `_.

It needs about 60 seconds to spin up and it will purge all changes after about an hour of non-usage.



Use cases

^^^^^^^^^



Suppose you are running The Planet, a news portal that has a bunch of editors

focused on getting news on different topics, like Economy, Health or Sports.



If you are the main publisher of the site, you may want to delegate the

construction of the front page of the Economy section to the people working on

that content area, but you might not want them messing around the Sports

section as well.



Also, suppose you have the final game of the World Cup and the match is going

to be defined on penalties: you may want to prepare a couple of cover pages

and publish the right one focused on the team that won in the end.



These are the kind of issues we want to solve with this package; we are still

far from it, but that is the idea.



Who is using it?

^^^^^^^^^^^^^^^^



These are some of the sites using ``collective.cover``:



* `CartaCapital `_ (BR)

* `Clean Clothes Campaign `_ (NL)

* `Conselho Federal de Administração `_ (BR)

* `La Jornada `_ (MX)

* `Palácio do Planalto `_ (BR)

* `Portal Brasil `_ (BR)

* `Rede Brasil Atual `_ (BR)

* `Venezolana de Televisión `_ (VE)

* `European Climate Adaptation Platform `_ (EU)



.. figure:: https://raw.github.com/collective/collective.cover/master/cover.png

    :align: center

    :height: 640px

    :width: 490px

    :target: http://www.planalto.gov.br/



    The Presidency of Brazil uses ``collective.cover`` on the front page of its site.



Mostly Harmless

---------------



.. image:: http://img.shields.io/pypi/v/collective.cover.svg

   :target: https://pypi.python.org/pypi/collective.cover



.. image:: https://img.shields.io/github/workflow/status/collective/collective.cover/Plone%20package/master?label=GitHub%20Actions

   :target: https://github.com/collective/collective.cover/actions/workflows/plone-package.yml



.. image:: https://codecov.io/gh/collective/collective.cover/branch/master/graph/badge.svg?token=rQ0kzJU0jt

   :target: https://codecov.io/gh/collective/collective.cover



Got an idea? Found a bug? Let us know by `opening a support ticket `_.



Known issues

^^^^^^^^^^^^



* `URI validation happens outside modal window `_.

  This is an issue present on Banner and Basic tiles.

* `Package is not compatible with standard Plone tiles `_.

  This will be addressed in a future release, if we get an sponsor.



See the `complete list of bugs on GitHub `_.



Don't Panic

-----------



We are currently working on the documentation of the package; this is what we have right now (contributions are always welcomed):



* `Quick Tour video on YouTube `_.

* `End user documentation `_

* `Developer documentation `_



Installation

^^^^^^^^^^^^



To enable this package in a buildout-based installation:



Edit your buildout.cfg and add the following to it:



.. code-block:: ini



    [buildout]

    ...

    eggs =

        collective.cover



If you want to use the relation field you must use the ``[relations]`` extra in your buildout configuration.



.. code-block:: ini



    [buildout]

    ...

    eggs =

        collective.cover [relations]



After updating the configuration you need to run ''bin/buildout'', which will

take care of updating your system.



Go to the 'Site Setup' page in a Plone site and click on the 'Add-ons' link.



Check the box next to ``collective.cover`` and click the 'Activate' button.



.. note::

    You may have to empty your browser cache and save your resource registries

    in order to see the effects of the product installation.



Development

-----------



We use `webpack `_ to process static resources on this package.

`webpack`_ processes SCSS and JS files, minifies the resulting CSS and JS, and optimizes all images.



To contribute, you should start the instance in one shell and start webpack watcher on another with the following command:



.. code-block:: console



    $ bin/watch-cover



Then go to ``webpack/app`` folder and edit SCSS and JS files;

`webpack`_ watcher will automatically create the final resources in the right place.



There are also other commands added to handle more complex scenarios.



The following command will set the buildout node installation in the system PATH,

this way you can use `webpack`_ as described on their documentation.



.. code-block:: console



    $ bin/env-cover



The following command generates JS and CSS without the minify step (it can be used to check the code being generated in a human readable way).



.. code-block:: console



    $ bin/debug-cover



The following command rebuilds static files and exit (insted of keep watching the changes):



.. code-block:: console



    $ bin/build-cover



Upgrading from 1.x to 2.x

^^^^^^^^^^^^^^^^^^^^^^^^^



In version 2.0b1 we removed a hard dependency on ``plone.app.relationfield``.

You must use the ``[relations]`` extra in your buildout configuration as stated above,

or your site will break with the following error:



.. code-block:: pytb



    AttributeError: type object 'ICatalog' has no attribute '__iro__'



Not entirely unlike

-------------------



Over the years there have been some packages designed to solve the problem of

creating section covers in Plone. We have used and have taken ideas from the

following:



`CompositePack `_

    Very old; the legacy code is so complex that is not maintainable anymore.

    It has (arguably) the best user interface of all. Layouts can not be

    created TTW. Viewlets are just page templates associated with content

    types; you can drag&drop viewlets around the layout. Publishers love it.



`CMFContentPanels `_

    Code is very old, but still maintained (at least works in Plone 4). Allows

    to create complex layouts TTW and use any layout as a template. Easy to

    extend and edit (but is terrible to find a content to use). Needs a lot of

    memory to work and aggressive cache settings.



`Collage `_

    Allows the creation of layouts TTW but it has (arguably) the worst user

    interface of all. It is easily extended and there are several add-ons

    available that provide new functionality for it.



`Home Page Editor of the Brazilian Chamber of Deputies Site `_

    Strongly based on `Collage`_, this package was presented at the `World Plone Day 2012 Brasilia `_.

    It allows editing of home pages and the definition of permissions on blocks of content.

    Works under Plone 3 only.



`collective.panels `_

    A new package that lets site editors add portlets to a set of new

    locations: above and below page contents, portal top and footer. The

    package comes with a number of flexible layouts that are used to position

    the portlets, and locations can be fixed to the nearest site object, to

    facilitate inheritance. In ``collective.cover`` (this package), we don't

    want to use portlets at all.



Releasing using zest.releaser

-----------------------------



Static resources on this package are generated using `webpack`_ and aren't included in VCS.

If you release using zest.releaser you have to `upload manually the files to PyPI `_ or you will end with a broken distribution:



* run ``longtest`` and ``fullrelease``, as usually

* answer "no" when asked to upload to PyPI and continue normally

* do a checkout to the tag you're releasing

* run ``bin/build-cover`` to update static files

* create the distribution files using ``python setup.py sdist bdist_wheel`` as usual

* upload the files using ``twine upload dist/*``



In case of errors you will have to create a new release as the PyPI Warehouse `doesn't allow for a filename to be reused `_.