{ "info": { "author": "Rob Gietema", "author_email": "rob@fourdigits.nl", "bugtrack_url": null, "classifiers": [ "Framework :: Plone", "Programming Language :: Python", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "Introduction\n============\n\nDeco is a graphical editor for Plone.\n\n.. contents:: Table of contents\n\nInstallation\n============\n\nTo install Deco, add ``plone.app.deco`` to your buildout and install the\n``Deco`` extension profile into a Plone site. This will install:\n\n* ``plone.app.deco``, the Deco editor and resources\n* ``plone.app.page``, the base ``page`` content type and supporting logic\n to manage page types, site layouts and template page layouts.\n* ``plone.app.blocks``, the Blocks rendering engine\n* ``plone.tiles`` and ``plone.app.tiles``, which allow tiles to be created\n and managed.\n* ``plone.app.standardtiles``, which contains tiles commonly used in Plone\n sites.\n* ``plone.app.cmsui``, which provides the separation of Plone's CMS UI\n into a separate, isolated toolbar.\n\nTo test it, add an item of the newly installed ``Page`` type to your site.\n\nNote that Deco and ``plone.app.cmsui`` significantly affect the way a Plone\nsite is used and operates. You should take care if installing on an existing\nsite and test carefully.\n\nConcepts\n========\n\nDeco, Blocks and Tiles provider a simple, yet powerful way to manage the pages\non your Plone website. At their core, they rely on semantic HTML and resources\nwith valid, publishable URLs. Below, we will provide an overview of the core\nconcepts that make up Deco, Blocks and Tiles.\n\nDeco\n----\n\nDeco is a visual editor for pages rendered using Blocks. It relies on the\nDeco Grid System to place tiles onto a page in an intuitive, WYSIWYG,\ndrag-and-drop manner. Using Deco, it is easy to compose pages with complex,\nbalanced and visually appealing layouts.\n\nThe Deco editor is invoked when the user switches a page into Edit mode using\nthe CMS UI toolbar.\n\nThe Deco Grid System\n--------------------\n\nThe Deco Grid System is a simple CSS grid framework. It uses robust,\ncross-browser CSS techniques to allow a page to be divided up into logical,\nproportionate rows and columns.\n\nThe Deco editor uses the CSS classes in the Deco Grid System to allow the\nuser to resize rows and columns to predefined, visually consistent\nproportions.\n\n**Note:** The Deco Grid CSS needs to be included in every Deco-managed page\nthat is rendered.\n\nBlocks\n------\n\nBlocks is a rendering algorithm based on HTML markup conventions. A page\nmanaged by Deco is stored as a simple HTML document representing the actual\ncontent of that page as a standalone, publishable resource devoid of any site\nlayout content (e.g. global navigation elements). This is referred to as the\n**page layout**.\n\nIn its ```` a page layout will have a data attribute like this::\n\n \n\nBlocks runs as a post-publication transformation that turns the page layout\ninto the final page that is returned to the user's browser by merging the page\nlayout into the referenced **site layout**, and then incorporating tiles into\nthe page.\n\n**Note:** If Blocks rendering is disabled, requesting a page will return\njust the page's content, in a valid, standalone HTML document.\n\nIt is important to realise that Blocks does not care how a page was rendered:\nit could be a verbatim chunk of HTML fetched from the database (as is usually\nthe case with Deco-managed pages), the result of rendering a page template, or\nsome other dynamically generated content. If it has a ``data-layout`` attribute in the\nhtml tag, it will be transformed and merged into the site layout.\n\n**Note:** When ``plone.app.deco`` is installed, it will enable a theme called\n``deco`` in portal_skins and switch to it as the default. This installs an\noverride for Plone's ``main_template`` that lets non-Deco-managed pages\nparticipate in Blocks rendering (i.e. use the current site layout and\ntiles).\n\nYou can read more about Blocks\n`here `_.\n\nSite layout\n-----------\n\nAs alluded to, the site layout controls the global elements on the final,\nrendered page, such as global navigational aids, a search box, header/footer\ncontent and so forth.\n\nThe site layout is also just an HTML document as far as Blocks is concerned.\nIt could be rendered by a page template belonging a view, for example. The\nmost common approach, however, is to use a **resource directory** of type\n``sitelayout``. The Deco control panel and page editing UI provide tools for\nmanaging such resources.\n\nResource directories are provided by `plone.resource`_. Resources can be\ncreated through the web (including from the Deco control panel), on the\nfilesystem in a global resource directory (e.g. inside a buildout), or in a\nfilesystem Python package using a ```` ZCML directive such\nas::\n\n \n\nInside the resource directory, the site layout should be placed in a file\ncalled ``site.html``. There can optionally also be a file ``manifest.cfg``,\nwhich contains metadata about the layout, e.g.::\n\n [sitelayout]\n title = My site layout\n description = An interesting site layout\n\nIf a layout is created through the web, it will be placed in the\n``portal_resources`` directory in the ZODB. See `plone.resource`_ for more.\n\nThere is always a site-wide default site layout. This can be changed through\nthe Deco control panel or with GenericSetup in a ``registry.xml`` file::\n\n \n \n \n \n ./++sitelayout++mylayout/site.html\n \n \n \n\nNote that this provides a relative path from the context to the site layout.\nA URL starting with a ``/`` will be relative to the portal root. The\n``++sitelayout++`` traversal namespace allows access to resources of that\ntype. ``mylayout`` is the name of the layout and ``site.html`` the name of\nthe file containing the actual layout HTML document.\n\nFor Deco-managed pages, site layouts can also be managed per page and per\nsection:\n\n* Per-page layouts allow the user to switch from, say, a three-column site\n layout with global elements on the left and right to a full-width splash\n page, presuming two site layouts (e.g. ``three-column`` and ``splash-page``)\n have been defined.\n \n* Per-section layouts allow the default site layout for all pages underneath\n a given section (i.e. all children and children's children of a given page)\n to be changed.\n\nFor this to work without having to modify every page each time the default\nor section layout is changed, most page will use a layout attribute like the\nfollowing::\n\n ...\n\nThe ``@@page-site-layout`` view will locate the correct page layout to\nuse in any given context and return its contents, taking per-page layouts into\naccount.\n\nFor other views, there is a more appropriate site layout indirection view::\n\n ...\n\nThis still respects global and section layouts, but will not utilise the\npage's site layout, which should only apply to the specific view of that page.\n\nPanels\n------\n\nPanels are the means by which content from the page layout and site layout\nget merged. A panel is a region on the site layout, identified by an ``id``,\nthat *may* be replaced by a corresponding region on the site.\n\nA panel is defined in the site layout using a link in its head like so::\n\n \n\nIn the body of the *site layout*, there should be a placeholder element with\nan ``id`` attribute value corresponding to the placeholder id (the ``target``\nattribute). If there is an element in the body of the *page layout* with an id\ncorresponding to the panel name (the ``rev`` attribute), then that element\nwill replace the corresponding placeholder in the site layout.\n\n**Note:** Any content in the body of the page that is not inside a panel that\nis registered in the site layout is discarded when panel merging takes place.\n\nContent in the head of the page layout is merged into the head of the site\nlayout automatically. For elements such as ```` or ``<base />`` that\ncan only appear once, any corresponding element in the site layout is replaced\nif it exists in both layouts. For other elements, the page layout's head\ncontents are merged into the site layout after the site layout's own head\ncontent.\n\nSee the `plone.app.blocks`_ documentation for more detailed examples about\nthis algorithm.\n\nTiles\n-----\n\nTiles represent the dynamic portions of a page. At its most basic level, a\ntile is simply an HTML document with a publishable URL.\n\nIn practice, tiles are usually implemented as browser views deriving from the\n``Tile`` base class and registered with the ``<plone:tile />`` ZCML directive.\nThis allows tiles to have some basic metadata and automatically generated edit\nforms for any configurable aspects , which Deco will expose to users. See\n`plone.tiles`_ for examples.\n\nWhen work with tiles in Deco, there are three types of tiles:\n\nText tiles\n Static HTML markup (WYSIWYG-edited text) placed into the page or site\n layout. Strictly speaking, text tiles are not tiles in that they do not\n involve any tile fetching or merging - instead they are stored as part of\n the page or site layout. To the user, however, a text tile can be moved\n around and managed like any other.\n\nField tiles\n Render the value of a metadata field such as the title or description. The\n values of field tiles may be edited in-place in the page, but the value is\n stored in the underlying field and can be indexed in the catalog, used for\n navigation and so on. In practice, a field tile is an instance of the\n special tile ``plone.app.standardtiles.fields`` with the field name passed\n as a parameter.\n\nApp tiles\n Any other type of dynamic tile. Examples may include a folder listing,\n a media player, a poll or pretty much anything else you can think of.\n\nFor Deco to know about a tile and make it insertable in the WYSIWYG editor, it\nmust be registered in ``portal_registry``, usually using the ``registry.xml``\nGenericSetup import step. Here is a snippet for the calendar tile::\n\n <records prefix=\"plone.app.deco.app_tiles.plone_app_standardtiles_calendar\"\n interface=\"plone.app.deco.interfaces.ITile\">\n <value key=\"name\">plone.app.standardtiles.calendar</value>\n <value key=\"label\">Calendar</value>\n <value key=\"category\">applications</value>\n <value key=\"tile_type\">app</value>\n <value key=\"default_value\"></value>\n <value key=\"read_only\">false</value>\n <value key=\"settings\">true</value>\n <value key=\"favorite\">false</value>\n <value key=\"rich_text\">false</value>\n <value key=\"weight\">10</value>\n </records>\n <record name=\"plone.app.deco.app_tiles.plone_app_standardtiles_calendar.available_actions\">\n <field type=\"plone.registry.field.List\">\n <title>Available actions for the Calendar tile\n \n \n \n blur\n tile-align-block\n tile-align-right\n tile-align-left\n \n \n\nNote the ``plone_app_standardtiles_calendar`` unique id that is used in both\nrecords, and the reference to the tile name\n(``plone.app.standardtiles.calendar``), which should correspond to the name\nused in the ```` ZCML directive.\n\nTiles may be placed in both page layouts and site layouts. In both cases, they\nconsist of a placeholder element with a unique id and a tile link in the head\nof the page, such as::\n\n \n\nWith this link, Blocks will look for the element with id ``logo`` and replace\nit with the contents of the tile found by traversing to\n``./@@plone.app.standardtiles.logo`` relative to the current context.\n\nIf a tile has configuration parameters, these will usually be embedded in a\nquery string. Tiles with such parameters are known as **transient tiles**::\n\n \n\nIf the tile requires more complex configuration that cannot be marshalled into\na query string, it may look up data stored in a persistent annotation on the\ncurrent context; in this case, it is known as a **persistent tile**.\n\n**Note:** Where possible, it is best to avoid persistent tiles, as they are\nslower and store their data opaquely.\n\nWhen a tile is rendered (i.e. when its URL is invoked), it should return a\nfull HTML document. The contents of the ```` tag will be used to\nreplace the tile placeholder. Any contents in the tile's ```` tag will\nbe merged into the final rendered page's head section. This allows tiles to\nrequest specific CSS or script resources, for instance.\n\n**Note:** In many cases, it will be better to register resources with the\n``portal_css`` and ``portal_javascripts`` registries to allow proper merging\nand managing of cache headers.\n\nSome tiles are intended for use in the head only, and will have no \n```` element. In this case, the placeholder id in the tile link (the\n``target`` attribute) can be skipped.\n\nSee `plone.app.blocks`_ and `plone.tiles`_ for more information about tiles\nand how they are incorporated into the page.\n\nPage types (categories)\n-----------------------\n\nWhen Deco is installed, it adds a new type in ``portal_types`` called, simply,\n``page``. This is a Dexterity content type that uses the ``ILayoutAware``\nbehaviour to manage page- and section-specific site layouts as well as the\nDeco page layout itself. This in turn is used by the ``@@page-site-layout``\nand ``@@default-site-layout`` views.\n\nThe ``page`` type uses a special *Factory Type Information* (FTI) type called\nthe ``Page FTI``. This is an extension of the standard Dexterity FTI that also\nstores the default site layout and the template page layout for a site.\n\nA **template page layout** is a resource (in the `plone.resource`_ sense) of\ntype ``pagelayout``. When a new instance of a given page type is created,\nthe contents of its template page layout are used as the starting point for\nthe new content item. \n\nA page may be *saved as* a new type - which will be addable from the standard\n*Add content* user interface - from within the content page editing screens.\nBehind the scenes, this results in a copy of the ``page`` portal type being\nmade with a new title and description as well as a new template page\nlayout based on the contents of the current page.\n\n**Note:** Page types are sometimes referred to as page *categories*.\n\nTemplate page layouts, site layouts and page types can all be managed from\nthe *Deco* control panel.\n\nFAQ\n===\n\nBelow, we will attempt to answer some frequently asked questions about Deco,\nBlocks and Tiles.\n\nHow do I theme a site using Deco and Blocks?\n--------------------------------------------\n\nYou may have realised that it is possible to \"theme\" a site using site\nlayouts, by placing global elements and branding on the site layout itself.\n\nThis may be appropriate for simple sites with minimal branding needs: as a\nrule of thumb, if you think you could construct your branding with the Deco\nvisual editor only, using site layouts to contain your visual identity may\nbe appropriate.\n\nThere are some caveats, however:\n\n* It is best to keep your site layouts focused on semantic layout, e.g. using\n names such as \"Article\" or \"Landing page\". If content authors choose site\n layouts for their pages and sections based mainly on visual identity, it\n will be harder to reuse content or rebrand the site later.\n* You may choose to let content authors or site administrators have the\n permission to create new site layouts or edit the contents of site layouts\n (e.g. to manage global elements such as advertisement or notifications). If\n the site layout is complex, it may be difficult to maintain visual\n consistency across multiple site layouts.\n\nHence, we would generally recommend that you keep your site layouts as\nsemantic and simple as possible, and apply a visual identity using `Diazo`_\nand `plone.app.theming`_. Deco and Diazo are designed to work together, with\nDeco focused on site layout as it pertains to content management and editing,\nand Diazo focused on branding and theming.\n\nWhat happens to viewlets?\n-------------------------\n\nIn Plone 3 and 4, viewlets are used for two purposes:\n\n1. As a means of breaking the main site layout templates up into smaller\n chunks that can be independently managed.\n2. As a means for third-party add-ons to inject bits of markup into the page\n at predefined locations (e.g. \"above content\" or \"below content\") without\n the need to customise global page templates.\n\nThe first of these is problematic in a some ways. For example, it relies on a\nmixture of global registration (ZCML) and local, persistent configuration (the\n``viewlets.xml`` GenericSetup import step) to control what is shown and in\nwhat order. It also makes it difficult to understand how the final page will\nlook by inspecting ``main_template``.\n\nHence, this pattern of using viewlets is superseded by tiles. Tiles are simply\nplaced into the relevant site layout. The ordering of tiles is controlled by\nthe ordering of the relevant tile placeholders. As a bonus, tiles are easier\nto write than viewlets and can have associated configuration.\n\nThe second use of viewlets is entirely legitimate, of course. Here, specific\nordering should matter less (a third-party add-on cannot know which other\nthird-party add-ons may be adding content in the same viewlet managers), and\nthe focus becomes on semantic or semi-semantic locations on the page in which\nviewlets can be inserted. This is indeed closer to the original purpose of\nviewlets.\n\nFor this pattern, there is a tile called\n``@@plone.app.standardtiles.viewletmanager``, which looks up and renders a\nviewlet manager. For example, the default sitelayout in Deco contains::\n\n \n\nNote that the tile takes a parameter, ``manager``, giving the name of the\nviewlet manager to look up and render. For viewlet managers rendered in the\nhead of the page, we use::\n\n \n\nThis ensures the contents of the viewlet manager are rendered in the\n```` of the tile, not the ````.\n\nWhat happens to portlets?\n-------------------------\n\nPortlets should likely be replaced by tiles. This will require some\nrefactoring, as tiles are considerably simpler than portlets. This simplicity\nis a good thing though: tiles are faster and easier to write and much easier\nto understand.\n\nThere is a conceptual difference too: Instead of having portlet managers that\nacquire and block portlets from the content hierarchy, the sort of content and\ndynamic behaviour that is managed in portlets in Plone 3 and 4 would instead\nbe modelled by tiles placed directly onto the appropriate site layout(s).\n\nIf the situation warrants, the relevant tile could of course use some more\nabstraction e.g. to model inheritance of settings. In most cases, this should\nnot be necessary, though: websites generally have only a handful of different\nlayouts, which in Plone 4 sometimes require an elaborate dance of portlet\nassignment, inheritance and blocking.\n\nTo users, there is really no distinction between app tiles used for things\nlike a navigation tree or a listing of news items (both of which are portlets\nin Plone 4) and app tiles used for things like a poll or content listing on\na page. With Deco-managed site layouts, tiles can be placed onto the layout\nwherever they are most appropriate, and there is no need to write ZCML and/or\nPython code to insert another portlet manager if you don't have a three-column\nlayout.\n\nThere is, however, a \"legacy\" tile that can be used to render a the contents\nof a portlet manager, thus allowing existing portlets to be managed and\nrendered in the same way they are in Plone 4. For example::\n\n \n\nWhat happens to content types?\n------------------------------\n\nTraditionally, achieving a particular non-trivial layout in a way that is\nconsistent site wide has required the creation of a new content type. With\nDeco and page categories, many existing types can be thought of simply as\npages with different layouts.\n\nFor example:\n\n+--------------+-------------------------------------------------------------+\n| Plone 4 type | Deco equivalent |\n+==============+=============================================================+\n| Page | The standard page type with a simple default layout. |\n+--------------+-------------------------------------------------------------+\n| Event | A new category of page with a template page layout that |\n| | includes the relevant metadata field tiles such as start |\n| | and end dates. |\n+--------------+-------------------------------------------------------------+\n| News Item | A new category of page with a layout that places a lead |\n| | image underneath the title. |\n+--------------+-------------------------------------------------------------+\n| Folder | Pages can have sub-pages. This replaces the insanely |\n| | confusing (to most users) \"default page\" concept. If you |\n| | need a folder listing, you can place a folder listing |\n| | tile on the page. |\n+--------------+-------------------------------------------------------------+\n| Collection | The collections query builder is a tile: hence, a |\n| | Collection becomes simply a page with an instance of |\n| | that tile on it. |\n+--------------+-------------------------------------------------------------+\n\nOf course, page categories are treated as first-class content types everywhere\nin Plone, so they can used in catalog queries, for example.\n\nThe remains are:\n\n* *Page* and its variants\n* *File*, which should handle both files and images, making image operations\n and behaviours available when dealing with a binary of an image MIME type.\n* Any custom, forms-driven types: Dexterity (and in particular its\n through-the-web) types creation facilities provide an excellent way to model\n organisation-specific data structures with forms-driven data entry as the\n primary content management paradigm. Such types can have view templates that\n specify a site layout, or simply use the standard ``main_template`` macros,\n which in turn will use the default (global or section-specific) site layout.\n\nWorking on Deco\n===============\n\nDeco is still work in progress. If you want to help finish it, there are\nsome pointers below for how to get involved.\n\nDevelopment buildout\n--------------------\n\nThere is a development buildout at\nhttps://svn.plone.org/svn/plone/plone.app.deco/buildouts/dev.\n\nSource code\n-----------\n\nThe code for ``plone.app.deco``, ``plone.app.page``, and the other packages\nall live in the primary Plone source code repository at\nhttps://svn.plone.org/svn/plone/. Note that you must have signed a Plone\nContributor Agreement before you can have access to commit to this repository.\n\nReporting bugs\n--------------\n\nPlease report bugs in JIRA until Deco is part of Plone. The JIRA project for\nDeco is at: http://projects.plone.org/browse/DC\n\ni18n\n----\n\nAll message strings should be in the Plone domain. If you need to add any\nPlone 5 packages to extract messages, you only have to add in to plone5\nvariable in experimental/i18n.cfg and run the buildout. You can do bin/i18n\nplone5 at any moment and if there is no error you can commit the changes from\nsrc/plone.app.locales/plone/app/locales/locales-future\n\n.. _plone.resource: http://pypi.python.org/pypi/plone.resource\n.. _plone.tiles: http://pypi.python.org/pypi/plone.tiles\n.. _plone.app.blocks: http://pypi.python.org/pypi/plone.app.blocks\n.. _Diazo: http://diazo.org\n.. _plone.app.theming: http://pypi.python.org/pypi/plone.app.theming\n\nChangelog\n=========\n\n1.0 (2012-06-22)\n----------------\n\n- initial release.\n [garbas]", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/plone/plone.app.deco", "keywords": "deco plone editor toolbar", "license": "GPL", "maintainer": null, "maintainer_email": null, "name": "plone.app.deco", "package_url": "https://pypi.org/project/plone.app.deco/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/plone.app.deco/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/plone/plone.app.deco" }, "release_url": "https://pypi.org/project/plone.app.deco/1.0/", "requires_dist": null, "requires_python": null, "summary": "Package for Deco UI functionality", "version": "1.0" }, "last_serial": 745857, "releases": { "1.0": [ { "comment_text": "", "digests": { "md5": "8afbf9d9b391ee747023bed16850ac15", "sha256": "32043ccf256febd97895035650d3a8994780744cf2cc6895965136d19c1ca0a3" }, "downloads": -1, "filename": "plone.app.deco-1.0.tar.gz", "has_sig": false, "md5_digest": "8afbf9d9b391ee747023bed16850ac15", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 199419, "upload_time": "2012-06-23T08:16:24", "url": "https://files.pythonhosted.org/packages/b0/12/c835844dc12d2ae86f8a1db7c716162d1863d60eadc100e188e5b03e54aa/plone.app.deco-1.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "8afbf9d9b391ee747023bed16850ac15", "sha256": "32043ccf256febd97895035650d3a8994780744cf2cc6895965136d19c1ca0a3" }, "downloads": -1, "filename": "plone.app.deco-1.0.tar.gz", "has_sig": false, "md5_digest": "8afbf9d9b391ee747023bed16850ac15", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 199419, "upload_time": "2012-06-23T08:16:24", "url": "https://files.pythonhosted.org/packages/b0/12/c835844dc12d2ae86f8a1db7c716162d1863d60eadc100e188e5b03e54aa/plone.app.deco-1.0.tar.gz" } ] }