svn commit: r929192 - in /websites/staging/isis/trunk: cgi-bin/ content/ content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.html

[bu...@apache.org]

Author: buildbot
Date: Fri Nov 14 14:52:15 2014
New Revision: 929192

Log:
Staging update by buildbot for isis

Modified:
    websites/staging/isis/trunk/cgi-bin/   (props changed)
    websites/staging/isis/trunk/content/   (props changed)
    websites/staging/isis/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.html

Propchange: websites/staging/isis/trunk/cgi-bin/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Nov 14 14:52:15 2014
@@ -1 +1 @@
-1639635
+1639654

Propchange: websites/staging/isis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Nov 14 14:52:15 2014
@@ -1 +1 @@
-1639635
+1639654

Modified: websites/staging/isis/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.html
==============================================================================
--- websites/staging/isis/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.html (original)
+++ websites/staging/isis/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.html Fri Nov 14 14:52:15 2014
@@ -428,65 +428,93 @@
 <p>The icon can be either static and fixed - meaning it is based on the object's class - or dynamic and changing - meaning
 it can change according to the object's state.  For example, an <code>Order</code> could indicate its status (pending, shipped), or a <code>ToDoItem</code> could indicate if it is complete or not.</p>
 
-<p>The mechanism to locate up the icon is viewer-specific.  In the <a href="../components/viewers/wicket/about.html">Wicket viewer</a> there are two mechanisms for locating an icon/image, though one applies only to static icons.</p>
+<p>In the <a href="../components/viewers/wicket/about.html">Wicket viewer</a> there are two mechanisms for locating an icon/image, though one applies only to static icons.  The viewer searches for a viewer in the following way:</p>
 
-<p>If the icon is static then it is located either:</p>
+<ul>
+<li>if the icon is dynamically specified, then it attempts to load an image file (<code>.png</code>, <code>.gif</code> or <code>.jpg</code>) from a well-known location on the classpath; else</li>
+<li>(1.8.0-SNAPSHOT onwards) if the icon is statically specified, then it:</p>
 
 <ul>
-<li>(1.8.0-SNAPSHOT onwards) by specifying a <a href="http://fortawesome.github.io/Font-Awesome/">font awesome</a> icon 
-for the class using either the <a href="../reference/recognized-annotations/CssClassFa.html"><code>@CssClassFa</code></a> annotation, or
-an equivalent entry in the <a href="../components/viewers/wicket/dynamic-layouts.html">.layout.json</a> file.</li>
-<li>else, provide an image file for the class, eg <code>ToDoItem.png</code>, picked up from a well-known location on the
-classpath.</li>
+<li>first attempts to load a <a href="http://fortawesome.github.io/Font-Awesome/">font awesome</a> icon if defined; else</li>
+<li>otherwise attempts to load an image file (<code>.png</code>, <code>.gif</code>, <code>.jpeg</code> or <code>.jpg</code>) from a well-known location on the classpath</li>
+</ul></li>
+<li>if all the above fail, then a default icon is provided</li>
 </ul>
 
-<p>If the icon is dynamic then it is located by the second mechanism only, that is:</p>
+<p>The sections below provide explain (a) what code to add to the domain object and (b) where to put any image files on the classpath.</p>
+
+<h2>Dynamically-specified image file</h2>
+
+<p>To specify that an object should have a specific icon, implement  an <code>iconName()</code> method.  This should return the <em>suffix</em> for an icon name; this is appended to the class name</p>
+
+<p>For example, to indicate that a <code>com.mycompany.todoapp.dom.TodoItem</code> object is either complete or incomplete, use:</p>
+
+<pre><code>public String iconName() {
+    return isComplete()? "complete": "notComplete";
+}
+</code></pre>
+
+<p>If the method returns "complete", then the viewer will look for an icon file on the classpath as follows:</p>
 
 <ul>
-<li>provide an image file for the object, eg <code>ToDoItem-completed.png</code>, again picked up from a well-known location on 
-the classpath.</li>
-</ul>
+<li>first, it will search in the same package as the domain class (1.8.0-SNAPSHOT):</p>
 
-<p>The sections below explain this in more detail.</p>
+<ul>
+<li>com/mycompany/todoapp/dom/TodoItem-complete.png</li>
+<li>com/mycompany/todoapp/dom/TodoItem-complete.gif</li>
+<li>com/mycompany/todoapp/dom/TodoItem-complete.jpeg</li>
+<li>com/mycompany/todoapp/dom/TodoItem-complete.jpg</li>
+</ul></li>
+<li>failing that, it will search in the <code>images</code> package:</p>
 
-<h2>Statically specified 'font awesome' icon</h2>
+<ul>
+<li>images/TodoItem-complete.png</li>
+<li>images/TodoItem-complete.gif</li>
+<li>images/TodoItem-complete.jpeg</li>
+<li>images/TodoItem-complete.jpg</li>
+</ul></li>
+</ul>
 
-<p>The framework has a number of mechanisms to locate the image.
-By default, the framework will look for an image in the <code>images</code>
-directory (either from the classpath or from the filesystem) that has
-the same name as the object class. Multiple file extensions are searched
-for, including <code>.png</code>, <code>.gif</code> and <code>.jpg</code> (in order of preference). For
-example, fan object of type Customer it will look for <code>Customer.png</code>,
-<code>Customer.gif</code>, <code>Customer.jpg</code> etc.</p>
-
-<p>If the framework finds no such file, then it will work up the
-inheritance hierarchy to see if there is an icon matching the name of
-any of the super-classes, and use that instead. If no matching icon is
-found then the framework will look for an image called <code>default.png</code>,
-<code>default.gif</code> or <code>default.jpg</code> in the images directory, and if this has
-not been specified, then the framework will use its own default image
-for an icon.</p>
-
-<p>We strongly recommend that you adopt 'pascal case' as the convention for
-icon file names: if you have a class called OrderLine, then call the
-icon <code>OrderLine.png</code>. Actually, the framework will also recognise
-<code>orderline.png</code>, but some operating systems and deployment environments
-are case sensitive, so it is good practice to adopt an unambiguous
-convention.</p>
+<p>The viewer stops searching as soon as a image file is found.</p>
 
-<h2>Statically-specified image file</h2>
+<h2>Statically-specified font awesome icon (1.8.0-SNAPSHOT)</h2>
 
-<h2>Dynamically-specified image file</h2>
+<p>If a dynamic icon has not been specified, then the viewer will next attempt to load a <a href="http://fortawesome.github.io/Font-Awesome/">font awesome</a> icon.</p>
 
-<p>Alternatively, you can use the <code>iconName</code>() method instead:</p>
+<p>For this, the class needs to be annotated with the <a href="../reference/recognized-annotations/CssClassFa.html"><code>@CssClassFa</code></a> annotation:</p>
 
-<pre><code>public String iconName() {
-    return "Person";
+<pre><code>@CssClass("fa fa-check-square-o")
+public class TodoItem { 
+    ...
 }
 </code></pre>
 
-<p>This makes it easy for more than one class to use the same icon, without
-having to duplicate the image file.</p>
+<h2>Statically-specified image file</h2>
+
+<p>If neither an <code>iconName()</code> nor an <code>@CssClassFa</code> annotation has been found, then the viewer will search for an image file based on the class's name.</p>
+
+<p>For example, a <code>com.mycompany.todoapp.dom.TodoItem</code> object will search:</p>
+
+<ul>
+<li>first, in the same package as the domain class (1.8.0-SNAPSHOT):</p>
+
+<ul>
+<li>com/mycompany/todoapp/dom/TodoItem.png</li>
+<li>com/mycompany/todoapp/dom/TodoItem.gif</li>
+<li>com/mycompany/todoapp/dom/TodoItem.jpeg</li>
+<li>com/mycompany/todoapp/dom/TodoItem.jpg</li>
+</ul></li>
+<li>and failing that, it will search in the <code>images</code> package:</p>
+
+<ul>
+<li>images/TodoItem-complete.png</li>
+<li>images/TodoItem-complete.gif</li>
+<li>images/TodoItem-complete.jpeg</li>
+<li>images/TodoItem-complete.jpg</li>
+</ul></li>
+</ul>
+
+<p>So, this is basically the same algorithm as for dynamically specified icons, without the suffix specified in the <code>iconName()</code> method.</p>