You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by jw...@apache.org on 2009/08/13 02:22:51 UTC
svn commit: r803748 -
/myfaces/trinidad/branches/1.2.11.4-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/context/RenderingContext.java
Author: jwaldman
Date: Thu Aug 13 00:22:51 2009
New Revision: 803748
URL: http://svn.apache.org/viewvc?rev=803748&view=rev
Log:
TRINIDAD-1196 RenderingContext members are not commented
added some javadoc
Modified:
myfaces/trinidad/branches/1.2.11.4-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/context/RenderingContext.java
Modified: myfaces/trinidad/branches/1.2.11.4-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/context/RenderingContext.java
URL: http://svn.apache.org/viewvc/myfaces/trinidad/branches/1.2.11.4-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/context/RenderingContext.java?rev=803748&r1=803747&r2=803748&view=diff
==============================================================================
--- myfaces/trinidad/branches/1.2.11.4-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/context/RenderingContext.java (original)
+++ myfaces/trinidad/branches/1.2.11.4-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/context/RenderingContext.java Thu Aug 13 00:22:51 2009
@@ -29,6 +29,14 @@
import org.apache.myfaces.trinidad.util.ThreadLocalUtils;
/**
+ * The RenderingContext holds context information about the current rendering.
+ * The RenderingContext is useful for Renderers. The
+ * RenderingContext is passed in to the CoreRenderer. For example,
+ * a renderer may need to render differently if it is rendering to a browser
+ * in right-to-left mode, or if accessibility mode is on, etc.
+ * Some values are promoted up from RequestContext for ease of use while rendering.
+ * @see org.apache.myfaces.trinidad.render.CoreRenderer#encodeAll
+ * @see RequestContext
*/
abstract public class RenderingContext
{
@@ -46,14 +54,42 @@
}
/**
- * A map of properties specific to rendering.
+ * Get a map of properties specific to rendering. You can then call the
+ * Map's put to save things on the RenderingContext for later retrieval.
*/
abstract public Map<Object, Object> getProperties();
-
+ /**
+ * Get the Agent attached to the RenderingContext.
+ * @return the Agent attached to the RenderingContext
+ */
abstract public Agent getAgent();
+
+ /**
+ * Get the LocaleContext attached to the RenderingContext
+ * @return the LocaleContext attached to the RenderingContext
+ */
abstract public LocaleContext getLocaleContext();
+
+ /**
+ * Get the FormData that is on the RenderingContext. You can then add more
+ * form data once you have the FormData object. This is a way to render
+ * hidden fields form data.
+ * @return returns the FormData that is on the RenderingContext. This could
+ * return null if there is no FormData
+ */
abstract public FormData getFormData();
+
+ /**
+ * Set FormData on the RenderingContext. This is a way to render hidden fields
+ * form data. This is a cleaner way to handle form data than using the
+ * getProperties.put mechanism.
+ * @param data
+ */
abstract public void setFormData(FormData data);
+
+ /**
+ * Clear the FormData that is on the RenderingContext
+ */
abstract public void clearFormData();
//
@@ -61,12 +97,22 @@
//
/**
- * Get the Skin. Icons, properties, etc. should never be retrieved directly
+ * Get the Skin that is attached to this RenderingContext.
+ * Icons, properties, etc. should never be retrieved directly
* from the skin, but always through the RenderingContext so they
* can be properly transformed.
+ * @return the Skin object attached to this RenderingContext
*/
abstract public Skin getSkin();
+ /**
+ * Get the translated String given a translation key.
+ * The default implementation
+ * gets the string from the Skin for the current LocaleContext
+ * that is used during this rendering.
+ * @param key
+ * @return the translated String attached to this RenderingContext
+ */
public String getTranslatedString(String key)
{
if (key == null)
@@ -84,33 +130,118 @@
return "???" + key + "???";
}
}
-
+
+ /**
+ * Get the Icon attached to this RenderingContext, give the iconName.
+ * This could be the Icon that is on the Skin objec that is on the
+ * current RenderingContext.
+ * @param iconName
+ * @return the Icon attached to this RenderingContext
+ */
abstract public Icon getIcon(String iconName);
-
+ /**
+ * Get a styleClass given a styleClass. With other information that is on
+ * the RenderingContext, the styleClass may be transformed.
+ * For example, you might want to return a compressed styleclass
+ * given the full styleClass.
+ * e.g., getStyleClass("SomLongName") could return "x1"
+ * You should always run your styleClass through this method before rendering
+ * it out.
+ * @param styleClass the styleClass name that you want to render
+ * @return the StyleClass that may be the given styleClass transformed to
+ * be suitable for this rendering context.
+ */
abstract public String getStyleClass(String styleClass);
+
/**
- * Return the Styles object that is attached to this RenderingContext.
+ * Get the Styles object that is attached to this RenderingContext.
* Styles is a useful object if you need to know the css properties for a given
- * selector.
- * @return Styles or null if there are no Styles.
- * for backward compatibility this is not an abstract method.
+ * selector. (For backward compatibility this is not an abstract method.)
+ * @return Styles or null if there are no Styles.
+ *
*/
public Styles getStyles()
{
return null;
}
+
+ /**
+ * Set the skin resource key map on the RenderingContext.
+ * Store a Map that maps a skin's resource keys from one key to another
+ * on the RenderingContext. This way we can share Rendering code, but use
+ * unique skinning keys for the Renderer. For example, we can use tree's
+ * rendering code for treeTable, but we want to be sure to use tree skinning
+ * keys (aka selectors) for tree and treeTable skinning keys for the treeTable
+ * component. You can create a map of tree's selectors to treeTable's selectors,
+ * and then save off the current map (getSkinResourceKeyMap),
+ * set the new map, render using the tree's renderer code, then set back
+ * the original map.
+ * @param mapping
+ * @see #getSkinResourceKeyMap()
+ */
abstract public void setSkinResourceKeyMap(Map<String, String> mapping);
+
+ /**
+ * Get the skin resource key map that is attached to the RenderingContext.
+ * This will usually be a Map of Skinning selectors. The key is the selector
+ * that the renderer code is rendering, and the value is the selector that
+ * that will be the actual selector to render. This facilitates sharing
+ * renderer code between components but render unique selectors for each
+ * component. The convention is to have each component have their own unique
+ * skinning selectors. Tree has af|tree selectors, treeTable has af|treeTable
+ * selectors, for example.
+ * @return a Map of selector to selector to faciliate renderer-code sharing.
+ * @see #setSkinResourceKeyMap
+ */
abstract public Map<String, String> getSkinResourceKeyMap();
+
+ /**
+ * Returns a boolean to indicate whether or not the RenderingContext is
+ * in right-to-left reading direction mode. This can be true if the browser
+ * requesting rendering is set to a right-to-left language.
+ * @return true if right-to-left is true
+ */
abstract public boolean isRightToLeft();
+ /**
+ * Returns the output mode for this RenderingContext. Example output-modes
+ * are printable and portlet.
+ * @return the outputMode for this RenderingContext.
+ */
abstract public String getOutputMode();
+
+ /**
+ * Get the accessibility mode (e.g., DEFAULT, INACCESSIBLE, etc)
+ * that is attached to this RenderingContext
+ * @return RequestContext.Accessibility enum attached to this RenderingContext
+ */
abstract public RequestContext.Accessibility getAccessibilityMode();
+
+ /**
+ * Get the AccessibilityProfile (a set of accessibility-related properties
+ * that are applied to the current request, e.g., color contrast, font size, etc)
+ * that is attached to this RenderingContext.
+ * @return AccessibilityProfile attached to this RenderingContext
+ */
abstract public AccessibilityProfile getAccessibilityProfile();
+
+ /**
+ * Returns true or false for whether animation is enabled.
+ * @return true if animation is enabled for this RenderingContext
+ */
abstract public boolean isAnimationEnabled();
// TODO This is a hack API to enable caching of the client ID.
// All fine, but we should have a more general mechanism.
+ /**
+ * Get the current client id for this RenderingContext
+ * @return
+ */
public String getCurrentClientId() { return _currentClientId; }
+ /**
+ * Set the current client id for this RenderingContext
+ * @param currentClientId
+ */
public void setCurrentClientId(String currentClientId)
{
_currentClientId = currentClientId;
@@ -119,7 +250,10 @@
private String _currentClientId;
-
+ /**
+ * Get the ParialPageContext that is attached to this RenderingContext
+ * @return
+ */
abstract public PartialPageContext getPartialPageContext();