Author: danhaywood
Date: Fri Nov 14 14:52:08 2014
New Revision: 1639654
URL: http://svn.apache.org/r1639654
Log:
titles, icons
Modified:
isis/site/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.md
Modified:
isis/site/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.md
URL:
http://svn.apache.org/viewvc/isis/site/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.md?rev=1639654&r1=1639653&r2=1639654&view=diff
==============================================================================
---
isis/site/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.md
(original)
+++
isis/site/trunk/content/how-tos/how-to-01-070-How-to-specify-the-icon-for-a-domain-entity.md
Fri Nov 14 14:52:08 2014
@@ -5,64 +5,76 @@ Apache Isis viewers identify objects thr
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 `Order` could
indicate its status (pending, shipped), or a `ToDoItem` could indicate if it is
complete or not.
-The mechanism to locate up the icon is viewer-specific. In the [Wicket
viewer](../components/viewers/wicket/about.html) there are two mechanisms for
locating an icon/image, though one applies only to static icons.
+In the [Wicket viewer](../components/viewers/wicket/about.html) 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:
-If the icon is static then it is located either:
+* if the icon is dynamically specified, then it attempts to load an image file
(`.png`, `.gif` or `.jpg`) from a well-known location on the classpath; else
-* (1.8.0-SNAPSHOT onwards) by specifying a [font
awesome](http://fortawesome.github.io/Font-Awesome/) icon
- for the class using either the
[`@CssClassFa`](../reference/recognized-annotations/CssClassFa.html)
annotation, or
- an equivalent entry in the
[.layout.json](../components/viewers/wicket/dynamic-layouts.html) file.
+* (1.8.0-SNAPSHOT onwards) if the icon is statically specified, then it:
-* else, provide an image file for the class, eg `ToDoItem.png`, picked up from
a well-known location on the
- classpath.
-
-If the icon is dynamic then it is located by the second mechanism only, that
is:
+ * first attempts to load a [font
awesome](http://fortawesome.github.io/Font-Awesome/) icon if defined; else
+ * otherwise attempts to load an image file (`.png`, `.gif`, `.jpeg` or
`.jpg`) from a well-known location on the classpath
+
+* if all the above fail, then a default icon is provided
-* provide an image file for the object, eg `ToDoItem-completed.png`, again
picked up from a well-known location on
- the classpath.
+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.
-The sections below explain this in more detail.
+## Dynamically-specified image file
-## Statically specified 'font awesome' icon
+To specify that an object should have a specific icon, implement an
`iconName()` method. This should return the *suffix* for an icon name; this is
appended to the class name
-The framework has a number of mechanisms to locate the image.
-By default, the framework will look for an image in the `images`
-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 `.png`, `.gif` and `.jpg` (in order of preference). For
-example, fan object of type Customer it will look for `Customer.png`,
-`Customer.gif`, `Customer.jpg` etc.
-
-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 `default.png`,
-`default.gif` or `default.jpg` in the images directory, and if this has
-not been specified, then the framework will use its own default image
-for an icon.
-
-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 `OrderLine.png`. Actually, the framework will also recognise
-`orderline.png`, but some operating systems and deployment environments
-are case sensitive, so it is good practice to adopt an unambiguous
-convention.
+For example, to indicate that a `com.mycompany.todoapp.dom.TodoItem` object is
either complete or incomplete, use:
-## Statically-specified image file
+ public String iconName() {
+ return isComplete()? "complete": "notComplete";
+ }
+If the method returns "complete", then the viewer will look for an icon file
on the classpath as follows:
+* first, it will search in the same package as the domain class
(1.8.0-SNAPSHOT):
-## Dynamically-specified image file
+ * com/mycompany/todoapp/dom/TodoItem-complete.png
+ * com/mycompany/todoapp/dom/TodoItem-complete.gif
+ * com/mycompany/todoapp/dom/TodoItem-complete.jpeg
+ * com/mycompany/todoapp/dom/TodoItem-complete.jpg
+
+* failing that, it will search in the `images` package:
+ * images/TodoItem-complete.png
+ * images/TodoItem-complete.gif
+ * images/TodoItem-complete.jpeg
+ * images/TodoItem-complete.jpg
+The viewer stops searching as soon as a image file is found.
+## Statically-specified font awesome icon (1.8.0-SNAPSHOT)
-Alternatively, you can use the `iconName`() method instead:
+If a dynamic icon has not been specified, then the viewer will next attempt to
load a [font awesome](http://fortawesome.github.io/Font-Awesome/) icon.
- public String iconName() {
- return "Person";
+For this, the class needs to be annotated with the
[`@CssClassFa`](../reference/recognized-annotations/CssClassFa.html) annotation:
+
+ @CssClass("fa fa-check-square-o")
+ public class TodoItem {
+ ...
}
-This makes it easy for more than one class to use the same icon, without
-having to duplicate the image file.
+## Statically-specified image file
+
+If neither an `iconName()` nor an `@CssClassFa` annotation has been found,
then the viewer will search for an image file based on the class's name.
+
+For example, a `com.mycompany.todoapp.dom.TodoItem` object will search:
+
+* first, in the same package as the domain class (1.8.0-SNAPSHOT):
+
+ * com/mycompany/todoapp/dom/TodoItem.png
+ * com/mycompany/todoapp/dom/TodoItem.gif
+ * com/mycompany/todoapp/dom/TodoItem.jpeg
+ * com/mycompany/todoapp/dom/TodoItem.jpg
+
+* and failing that, it will search in the `images` package:
+
+ * images/TodoItem-complete.png
+ * images/TodoItem-complete.gif
+ * images/TodoItem-complete.jpeg
+ * images/TodoItem-complete.jpg
+So, this is basically the same algorithm as for dynamically specified icons,
without the suffix specified in the `iconName()` method.
\ No newline at end of file
