svn commit: r1627822 - in /isis/site/trunk/content: documentation.md more-advanced-topics/how-to-hide-part-of-a-title.md

[da...@apache.org]

Author: danhaywood
Date: Fri Sep 26 16:35:31 2014
New Revision: 1627822

URL: http://svn.apache.org/r1627822
Log:
ISIS-886

Added:
    isis/site/trunk/content/more-advanced-topics/how-to-hide-part-of-a-title.md
Modified:
    isis/site/trunk/content/documentation.md

Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1627822&r1=1627821&r2=1627822&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Fri Sep 26 16:35:31 2014
@@ -198,6 +198,7 @@ For both:
 
 #### <a name="more-advanced-topics-business-rules">Business rules</a>
 
+* [Hide part of a title](./more-advanced-topics/how-to-hide-a-portion-of-the-title.html)
 * [All members hidden](./more-advanced-topics/how-to-02-040-How-to-specify-that-none-of-an-object's-members-is-visible.html)
 * [All members unmodifiable](./more-advanced-topics/how-to-02-080-How-to-specify-that-none-of-an-object's-members-can-be-modified-or-invoked.html)
 * [Immutable object](./more-advanced-topics/how-to-02-090-How-to-specify-that-an-object-is-immutable.html)
@@ -266,7 +267,7 @@ Commonly-used domain services to use wit
 * [DomainObjectContainer interface](./reference/DomainObjectContainer.html)
 * [ClockService](./reference/services/ClockService.html)
 * [Exception Recognizers](./reference/services/exception-recognizers.html) [Impl](components/objectstores/jdo/services/exception-recognizers-jdo.html)
-* [Wrapper Factory](reference/services/wrapper-factory.html) [stub]
+* [Wrapper Factory](reference/services/wrapper-factory.html)
 
 #### <a name="domain-services-event-bus">Event Bus</a>
 

Added: isis/site/trunk/content/more-advanced-topics/how-to-hide-part-of-a-title.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/more-advanced-topics/how-to-hide-part-of-a-title.md?rev=1627822&view=auto
==============================================================================
--- isis/site/trunk/content/more-advanced-topics/how-to-hide-part-of-a-title.md (added)
+++ isis/site/trunk/content/more-advanced-topics/how-to-hide-part-of-a-title.md Fri Sep 26 16:35:31 2014
@@ -0,0 +1,57 @@
+How to hide part of a title
+--------------------------------
+
+Normally the visibility of doamin object properties is solely the framework viewers' concern; the domain objects do not
+need to know which class members are visible or not.
+ 
+However, one exception is when the title is built programmatically through the 
+[title()](../how-tos/how-to-01-040-How-to-specify-a-title-for-a-domain-entity.html) method.  In order to ensure that
+potentially sensitive information (that nevertheless is meant to be part of the title) does not "leak out", it may be 
+necessary for the domain object to programmatically determine whether the current user can view the information.
+
+One way to accomplish this is to use the [WrapperFactory](../reference/services/wrapper-factory.html), wrapping the
+domain object (`this`) and catching any exceptions:
+
+    String foo = "";
+    try {
+        foo = wrapperFactory.wrap(this).getFoo();
+    } catch(HiddenException ex) {
+        //ignore
+    }
+
+For example, in the todoapp example the `dueBy` date of a `ToDoItem` is part of the title:
+
+    public String title() {
+        final TitleBuffer buf = new TitleBuffer();
+        buf.append(getDescription());
+        if (isComplete()) {
+            buf.append("- Completed!");
+        } else {
+            if (getDueBy() != null) {
+                buf.append(" due by", getDueBy());
+            }
+        }
+        return buf.toString();
+    }
+
+However, this can be rewritten easily enough to suppress this portion if need be:
+
+    public String title() {
+        final TitleBuffer buf = new TitleBuffer();
+        buf.append(getDescription());
+        if (isComplete()) {
+            buf.append("- Completed!");
+        } else {
+            try {
+                final LocalDate dueBy = wrapperFactory.wrap(this).getDueBy();
+                if (dueBy != null) {
+                    buf.append(" due by", dueBy);
+                }
+            } catch(HiddenException ex) {
+                // ignore
+            }
+        }
+        return buf.toString();
+    }
+    
+We did debate whether to add an additional API in the `WrapperFactory` for this use case; for now we have decided against.
\ No newline at end of file