adding documentation for thumbs/icons ....

.gitignore

@@ -8,4 +8,4 @@ _locales
 develop/coredev
 develop/plone.api
 develop/addons/bobtemplates.plone
-
+.project

CHANGES.rst

@@ -5,16 +5,18 @@ Changelog
 
 Unreleased
 ==========
-
+- Documentation for Thumbs and Iconhandling in Plone 
+  https://github.com/plone/Products.CMFPlone/issues/1995
+  [fgrcon]
+- New metadata catalog column `mime_type`
+  https://github.com/plone/Products.CMFPlone/issues/1995
+  [fgrcon]
 - Add security guidelines for developers[vangheem]
 - Overhaul of vocabularies section. [jensens]
 - Remove Deliverance info for theming and refer to diazo.org deployment [fredvd]
 - Improve ReStructuredText Style Guide [svx]
 - Add documentation about TinyMCE styles and formats [davilima6]
 
-- New metadata catalog column `mime_type`
-  https://github.com/plone/Products.CMFPlone/issues/1995
-  [fgrcon]
 
 20160606
 ========

adapt-and-extend/config/intro.rst

@@ -44,7 +44,7 @@ Mail
 Navigation
     Configure :doc:`how navigation is constructed <navigation>`. Which content types should appear in navigation, should folders on the top level become tabs, and which workflows to show.
 Site
-    Various :doc:`site wide settings <site>`: Site name, logo, metadata, settings for search engines and more.
+    Various :doc:`site wide settings <site>`: Site name, logo, metadata, default settings for handling of icons and preview images, toolbar options, settings for search engines and more.
 Add-ons
     :doc:`Activate and deactivate <add-ons>` add-ons that enhance Plone's functionality.
 Search

adapt-and-extend/config/site.rst

@@ -35,7 +35,29 @@ JavaScript for web statistics support
 Display publication date
     Show the date a content item was published in the byline.
 Icon visibility
-    Controls whether to show different icons for different types of content. Can be useful for content editors, but distracting for anonymous visitors. You can set it to show only for logged-in users.
+    Master control for enabling content type icons (Different icons for different types of content). Content type icons can be useful for content editors, but distracting for anonymous visitors.
+    You can set it to show only for logged-in users, all users or none at all. If this option is set to none or logged-in users only it will override all other settings  in portlets or content item settings.
+Thumb visibility
+    Master control for enabling preview images (aka thumbs) in list views, tables views  or portlets.
+    You can set it to show only for logged-in users, all users or none at all. If this option is set to none or logged-in users only it will override all related settings below as well those in individual portlet- or content item settings.
+
+
+No Thumbs in portlets
+   Suppress thumbs (preview images) in all portlets; this default can be overridden individually in selected portlets
+No thumbs in list views
+   Suppress thumbs in all list views; this default can be overriden individually
+No thumbs in summary views
+   Suppress thumbs in all summary views; this default can be overriden individually
+No thumbs in table views
+   Suppress thumbs in all tableviews and in folder contents view; this default can be overriden individually
+Thumb size for portlets
+   Choose from a pull down populated by available scales defined in the :doc:`Image handling control panel<image-handling.rst>`. This default can be overriden individually
+Thumb size for listings
+   E.g. for standard view; this default can be overriden individually
+Thumb size for tables
+   E.g. for tabular view,  this default can be overriden individually. **This setting is also used for the folder content listing (can not be overridden).**
+Thumb size for summary view
+   This default can be overriden individually
 Toolbar position
     On modern wide-screen monitors, having the Toolbar to the side provides most usable space. But some people prefer it to be on the top of their screen.
 Site based relative URL for toolbar Logo

develop/addons/upgrade_to_50.rst

@@ -81,3 +81,9 @@ The version of plone.app.iterate used in Plone 5 implements this already making
 You should remove any hard dependency on plone.app.stagingbehavior from your add-on to avoid issues.
 
 See https://github.com/collective/collective.cover/pull/577/files for an example on how to achieve that.
+
+Content type icons
+==================
+
+A major breaking change from Plone 4.x to Plone 5 is how content type icons are handled.
+See :ref:content-type-icons-changed` for details. 

develop/addons/upgrade_to_51.rst

@@ -386,7 +386,138 @@ When you do not need them both, you can let the other return an empty list, or y
         @implementer(INonInstallable)
         class NonInstallable(object):
             ...
+.. _content-type-icons-changed
 
+Content type icons
+==================
+Since Plone 3 there have been several breaking changes relating to content type icon rendering.
+
+**Plone 3**
+
+Content type icons where rendered as HTML tags, which were rendered with methods from plone.app.layout.icon ...:
+
+.. code-block:: html
+
+   <span class="contenttype-document summary">
+          <img width="16" height="16" src="http://192.168.1.230:8322/Plone/document_icon.gif" alt="Page">
+          <a href="http://192.168.1.230:8322/Plone/front-page" class="state-published url">Welcome to Plone</a>
+   </span>
+
+
+.. note::
+
+    Related code in plone.app.layout  (especially `getIcon()` and  `IContentIcon`) and other locations was more then deprecated - it is obsolete and confusing and is getting removed.
+    The catalog metadata item getIcon used to be a string containing the file name of the appropriate icon (unused since Plone 4).
+
+    Since Plone 5.02 the catalog metadata item **getIcon** is reused for another purpose.
+    Now it is boolean and it is set to `True` for items which are images or have an image property (e.g. a lead image).
+
+
+
+**Plone 4**
+
+Content type icons are rendered as background images using a sprite image and css:
+
+.. code-block:: html
+
+   <span class="summary">
+         <a href="http://192.168.1.230:8412/Plone/front-page" class="contenttype-document state-published url">Welcome to Plone</a>
+   </span>
+
+   .icons-on .contenttype-document {
+       background: no-repeat transparent 0px 4px url(contenttypes-sprite.png);
+
+**Plone 5**
+
+Content type icons are rendered as ¸`fontello fonts <http://fontello.com/>`_ using css elements *before* or *after*.
+
+.. code-block:: html
+
+   <span class="summary" title="Document">
+        <a href="http://192.168.1.230:8082/Plone/front-page"
+             class="contenttype-document state-published url"
+             title="Document">Welcome to Plone</a>
+   </span>
+
+   body#visual-portal-wrapper.pat-plone .outer-wrapper [class*="contenttype-"]:before, .plone-modal-body [class*="contenttype-"]:before {
+       font-family: "Fontello";
+       font-size: 100%;
+       padding: 0;
+       margin: 0;
+       position: relative;
+       left: inherit;
+       display: inline-block;
+       color: inherit;
+       width: 20px;
+       height: 20px;
+       text-align: center;
+       margin-right: 6px;
+       content: '\e834';
+   }
+
+Example from plonetheme.barceloneta/plonetheme/barceloneta/theme/less/contents.plone.less:
+
+.. code-block:: 
+
+     body#visual-portal-wrapper.pat-plone .outer-wrapper, .plone-modal-body{
+      [class*="contenttype-"]:before {
+         font-family:"Fontello"; font-size: 100%;
+         padding: 0; margin:0; position: relative; left: inherit; display: inline-block; color: inherit;
+         width: 20px; height: 20px; text-align: center; margin-right: @plone-padding-base-vertical;
+         content: '\e834';
+      }
+      .contenttype-folder:before {  content: '\e801';}
+      .contenttype-document:before {   content: '\e80e';}
+      .contenttype-file:before {   content: none;}
+      .contenttype-link:before {    content: '\e806';}
+      .contenttype-image:before {      content: '\e810';}
+      .contenttype-collection:before {content: '\e808';}
+      .contenttype-event:before {      content: '\e809';}
+      .contenttype-news-item:before {  content: '\e80f';}
+   }
+The wildcard definition :code:`[class*="contenttype-"]:before ....content: '\e834'` renders the default icon for dexterity content types for all dexterity items 
+which have no specific css rule (e.g. custom dexterity content types). 
+
+
+The rule :code:`.contenttype-file:before {   content: none;}` prevents rendering a fontello font for **file** type items (e.g. *.pdf, *.docx, etc..).
+
+Instead a **mimetype icon** (fetched from the mime type registry) is rendered as html tag ( - there would be too many fonts needed for all the mime types)in affected templates e.g. in plone.app.contenttypes.browser.templates.listing.pt:
+
+.. code-block:: 
+   <span class="summary" tal:attributes="title item_type">
+     <a tal:condition="python:item_type == 'File' and showicons" 
+       tal:attributes="href item_link;
+                       class string:$item_type_class $item_wf_state_class url;
+                       title item_type">
+       <image class="mime-icon" 
+               tal:attributes="src item/MimeTypeIcon">
+     </a>
+     <a tal:attributes="href item_link;
+                          class string:$item_type_class $item_wf_state_class url;
+                          title item_type"
+         tal:content="item_title">Item Title
+     </a>
+    .....
+   </span>
+          .
+
+.. image:: /_static/content-type-icons.png
+   :align: center
+   :alt: content type icons
+
+The design decision to use Fontello fonts throws up the question how to easily create custom fonts for new created custom dexterity items.
+
+A workaround for that is to use an icon url in the :before clause.
+For the custom dexterity type *dx1* you might add the line :code:`.contenttype-dx1:before {content: url('dx1_icon.png')}` to your less file and place the icon file in to the same folder.
+
+Preview Images (Thumbs)
+=======================
+
+Preview images (aka thumbs) can be shown in listings, tables and portlets. 
+
+
+.. TODO::
+   to be ctd.
 
 Retina image scales
 ===================

develop/plone/searching_and_indexing/indexing.rst

@@ -383,7 +383,12 @@ Some interesting columns
 
 * getRemoteURL: Where to go when the object is clicked
 
-* getIcon: Since Plone 5.0.2 - Boolean value which is set to :guilabel:``True``, when item has or is an image (used for showing thumbs in lists, portlets, etc. ). Content type icons (aka portaltype-icons) ( e.g.: for folder, document, news item etc.) are rendered as fontello fonts since Plone 5.0.
+* getIcon: **This might be confusing:** 
+           Since Plone 5.0.2 - **getIcon is a boolean value which is set to ``True``, when the item is an image ore has an image property (named image)
+           e.g.: lead image or teaser image).** The value of getIcon is used for showing previoew images (thumbs) in lists, tables, content view, portlets, etc.). 
+
+           Content type icons (aka portaltype-icons) ( e.g.: for folder, document, news item etc.) are now rendered as fontello fonts since Plone 5.0.
+           Mime type icons are read from the mime type registry for all file content types instead a fontello font (since Plone 5.1) 
 
 * exclude_from_nav: If True the object won't appear in sitemap, navigation tree
 

working-with-content/introduction/visual-design-of-plone.rst

@@ -57,3 +57,54 @@ What does a Plone web site look like?
 Traditionally, the out-of-the-box look is like that shown at the top of this page, with header, menu, columns, and a footer.
 
 But using the flexible "Diazo" theme engine of Plone, each aspect can be made to look any way the designer chooses, and can also be shown different depending on the device of the visitor.
+
+
+.. _content-type-icons-intro
+Content Type Icons
+------------------
+
+**Icons** are used to highlight actions, options etc. in menu bars, property sheets and the like:
+
+.. image:: /_static/icons.png
+   :align: center
+   :alt: Icons used in Plone user interface
+
+
+
+Furthermore **icons** can be used to help to visually identify **content types** in any kind of listing or tables.
+For the content type *File* mime type icons are used to visualize the format of the given file.
+
+This feature is adjustable to a very high degree. There are default settings which can be configured in the :doc:`Site Configuration panel </adapt-and-extend/config/site>`.
+This default settings can be overidden for each content item (edit: settings) or portlet respectively. 
+
+
+.. image:: /_static/icons2.png
+   :align: center
+   :alt: Content type icons
+
+Preview Images (aka Thumbnails, Thumbs)
+---------------------------------------
+**Preview Images (or thumbnails, thumbs)**  for image items or any other content items which have a lead image
+(or teaser image) can be shown in any listing or table. 
+Additional to the same configuraion options for icons above you can define default sizes for the preview images for, tables, lists or portlets and also overwrite these settings individually.  
+
+
+.. image:: /_static/thumbs-example-1.png
+   :align: center
+   :alt: Example: preview images and icons with different settings
+
+
+Depending on the default settings for table views the  content view of a folder will show preview images or not:
+
+
+.. image:: /_static/contents-with-thumbs-suppressed.png
+   :align: center
+   :alt: Example: content view with thumbs not shown
+
+
+.. image:: /_static/contents-with128x128.png
+   :align: center
+   :alt: Example: content view with thumbs  shown
+
+
+The second option (here with image size set to 128x128) is very handy whenever you need to rearrange a big number of images whith mkore or less meaningless title.