|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object ATagInfrastructure com.plumtree.portaluiinfrastructure.tags.ATag
public abstract class ATag
This is the base class that developers will use to write their own custom tags.
In order to implement a Tag, developers need to follow the steps below:
E.G. <pt:thistag/> would need
public static final ITagMetaData TAG;
static ThisTag() (or just static in c#)
{
TAG = new TagMetaData("thistag", "This tag displays some HTML ...");
}
Note that the TagMetaData class automatically converts the tag name to lowercase, which means that all references to the tag in HTML need to use the lowercase name.
E.G. <pt:thistag pt:firstattribute="foo" pt:secondattribute="bar"/>
would need
public static final RequiredTagAttribute FIRST_ATTRIBUTE;
public static final OptionalTagAttribute SECOND_ATTRIBUTE;
static ThisTag() (or just static in c#)
{
FIRST_ATTRIBUTE = new RequiredTagAttribute(
"firstattribute", "This attribute is used to ...");
SECOND_ATTRIBUTE = new OptionalTagAttribute(
"secondattribute", "This optional attribute is used to ...",
AttributeType.STRING, "default value");
}
A description of the valid formats for attributes can be found in the AttributeType class.
Optionally, a Tag developer can also:
The ITagMetaData TAG member variable needs to be initialized first since it can be used in other tags (i.e. as a RequiredParentTag) that are referenced by member variables of this tag (i.e. as a RelatedChildTag). This is necessary for tags that have circular references such as a parent / child tag relationship.
The ATag methods are grouped into several different categories of methods.
E.G. <pt:tag pt:attribute="false"/>
E.G. <pt:tag attribute="false"/>
Each tag instance is guaranteed to be accessed by only a single thread at a time. However, there may be multiple threads accessing different instances of the same tag class at the same time, either from the same user or a different user. This means that any static fields will need to be accessed using synchronized methods. It is a best practice not to use static fields for data storage in tags.
Since there can be multiple instances of the same tag running at the same time, state variables set in shared Scopes (E.G. Scope.SESSION, Scope.PERSISTENT_SESSION, and Scope.APPLICATION) may change values during the execution of a single tag.
AttributeType
,
ITagMetaData
,
TagMetaData
,
RequiredTagAttribute
,
OptionalTagAttribute
,
RequiredParentTag
,
RequiredChildTag
,
RelatedChildTag
,
ITagState
Constructor Summary | |
---|---|
ATag()
|
Method Summary | |
---|---|
void |
AddJavascript(HTMLScriptCollection _script)
This method is used to add JavaScript for this tag. |
abstract ATag |
Create()
This method is used to create new instance of managed (i.e. |
HTMLScriptCollection |
DisplaySharedJavascript()
This method is used to display JavaScript that only needs to included on a page once, regardless of how many times a particular tag is used on that page (such as including JavaScript files). |
abstract HTMLElement |
DisplayTag()
This is the main display method of the Tag. |
static java.lang.String |
EncodeForTagDoc(java.lang.String tagdocString)
Helper function to format a string with HTML, tags to properly display in Tag Docs. |
java.lang.Object |
GetAnyStateVariable(java.lang.String _strKey)
Gets a variable from memory from all scopes. |
IEnvironment |
GetEnvironment()
Gets the environment for the current tag and request. |
ITagState |
GetState()
Gets the variable state helper object. |
java.lang.Object |
GetStateSharedVariable(java.lang.String _strKey,
Scope _scope)
Gets a shared variable from memory in the appropriate scope. |
java.lang.Object |
GetStateVariable(java.lang.String _strKey,
Scope _scope)
Gets a variable from memory in the appropriate scope. |
java.lang.String |
GetTagAttribute(java.lang.String _strAttribute)
This method gets the value of the requested pt attribute. |
boolean |
GetTagAttributeAsBoolean(ATagAttribute _attribute)
This method gets the requested attribute if it was present in the tag. |
char |
GetTagAttributeAsChar(ATagAttribute _attribute)
This method gets the requested attribute if it was present in the tag. |
double |
GetTagAttributeAsDouble(ATagAttribute _attribute)
This method gets the requested attribute if it was present in the tag. |
int |
GetTagAttributeAsInt(ATagAttribute _attribute)
This method gets the requested attribute if it was present in the tag. |
long |
GetTagAttributeAsLong(ATagAttribute _attribute)
This method gets the requested attribute if it was present in the tag. |
Scope |
GetTagAttributeAsScope(ATagAttribute _attribute)
This method gets the requested attribute if it was present in the tag. |
java.lang.String |
GetTagAttributeAsString(ATagAttribute _attribute)
This method gets the requested attribute if it was present in the tag. |
java.lang.Object |
GetTagAttributeAsTagVariable(ATagAttribute _attribute,
Scope scope)
This method gets the requested attribute if it was present in the tag. |
IXPEnumerator |
GetTagAttributeNames()
Gets an enumeration of the names of all the pt attributes in this tag. |
TagType |
GetTagType()
This method describes what kind of tag this is. |
java.lang.String |
GetUniqueID()
Gets a unique ID for this instance of this tag. |
java.lang.String |
GetXMLTagAttribute(java.lang.String _strAttribute)
This method gets the value of the requested non-pt attribute. |
IXPEnumerator |
GetXMLTagAttributeNames()
Gets an enumeration of the names of all the non-pt attributes in this tag. |
java.lang.String |
GetXMLTagAttributesAsString()
Calculates a string containing all of the non-pt attributes that can be inserted inside an XML tag to add all of the attributes to the tag. |
boolean |
HasChildTag(ITagMetaData _childTag)
Check whether or not a particular Transformer Tag is nested inside the current Tag. |
boolean |
HasParentTag(ITagMetaData _parentTag)
Check whether or not the current Tag is nested inside a given parent Tag. |
boolean |
HasTagAttribute(ATagAttribute _attribute)
Check to see whether or not a specified attribute is present in the HTML for this tag. |
boolean |
HasXMLTagAttribute(java.lang.String _strAttribute)
Check to see whether or not a specified non-pt attribute is present in the HTML for this tag. |
HTMLElement |
ProcessTagBody()
This method displays the HTML and Transformer Tags that are inside this tag. |
void |
ReleaseTag()
This method releases all data stored in this tag to prevent excess memory retention and to prepare the tag for reuse. |
void |
SetStateSharedVariable(java.lang.String _strKey,
java.lang.Object _oValue,
Scope _scope,
boolean bOwnerEditOnly)
Sets a variable in memory in the appropriate scope. |
void |
SetStateVariable(java.lang.String _strKey,
java.lang.Object _oValue,
Scope _scope)
Sets a variable in memory in the appropriate scope. |
boolean |
SupportsAccessStyle(AccessStyles _style)
This method is used to verify whether or not this tag supports the passed in access style. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public ATag()
Method Detail |
---|
public abstract HTMLElement DisplayTag()
E.G. <pt:thistag><span><pt:innertag/></span></pt:thistag> This method is responsible for displaying the thistag UI and displaying the inner HTML (<span><pt:innertag/></span>) by calling ProcessTagBody and including the results in the HTMLElement returned by this method.
This method is also responsible for displaying any instances of JavaScript need by this tag through the AddJavascript method. The DisplaySharedJavascript method will be called automatically by the framework and does not need to be called by this method.
If there are errors in the tag and it cannot be displayed properly, the tag should throw an XPException with the error message, and the tag framework will log the error and add the message and stack trace to the HTML as an HTML comment. The message contents will be HTML encoded before being added to the comment.
Abstract Tag Method
XPException
- if there are any errors in the tag.public abstract ATag Create()
Tag methods will not be functional during execution of this method (E.G. tag.SetStateVariable, etc... will not work).
public HTMLScriptCollection DisplaySharedJavascript()
Tags that need to include javascript once per page should override this method and include the javascript here.
This method is called automatically by the framework and does not need to be called in the DisplayTag() method.
This method will not be called in Section 508 compliance mode, as 508 screen readers do not allow JavaScript.
If there are errors in the tag and the JavaScript cannot be displayed properly, the tag should throw an XPException with the error message, and the tag framework will log the error and add the message and stack trace to the HTML as an HTML comment. The message contents will be HTML encoded before being added to the comment.
Default Tag Method
public TagType GetTagType()
The TagType data is used for performance optimizations.
Default Tag Method
public boolean SupportsAccessStyle(AccessStyles _style)
Default Tag Method
_style
- The access style to check.
public void ReleaseTag()
All tags that store custom data as member variables should override this method and release the data here. If a tag does not store custom data as member variables, then there is no need to override this method.
Tag methods will not be functional during execution of this method (E.G. tag.GetEnvironment, etc... will not work). Default Tag Method
public IEnvironment GetEnvironment()
Tag Utility Method
public ITagState GetState()
Tag Utility Method
public HTMLElement ProcessTagBody()
This method may be called zero times, once, or multiple times during the lifecycle of a tag. Tags that call this method multiple times should return TagType.LOOPING from the GetTagType method. Tags that never call this method should return TagType.NO_BODY from the GetTagType method.
Tag Utility Method
XPException
- if tags of type NO_BODY call this method.public void AddJavascript(HTMLScriptCollection _script)
This method should not be used for common JavaScript for a tag (such as JavaScript includes) that only needs to be displayed once per page, regardless of how many instances of this tag there are on the page. DisplaySharedJavaScript() should be used instead.
JavaScript added using this method will not be displayed in Section 508 compliance mode, as 508 screen readers do not allow JavaScript.
Tag Utility Method
HTMLScriptCollection
- _script The JavaScript to
be displayedpublic boolean HasParentTag(ITagMetaData _parentTag)
E.G. <pt:parenttag><pt:thistag/></pt:parenttag> would return true for "parenttag".
Tag Utility Method
ITagMetaData
- _parentTag The Tag Meta Data
of the requested parent tag
public boolean HasChildTag(ITagMetaData _childTag)
E.G. <pt:thistag><span><pt:firstchildtag><pt:subsubchildtag/></pt:firstchildtag> <pt:secondchildtag/><span></pt:thistag> would return true for "firstchildtag", "secondchildtag", and "subsubchildtag", but not "span", since it is an HTML Tag, not a Transformer Tag.
Tag Utility Method
ITagMetaData
- _childTag A Tag Meta
Data objects of the requested child tag
public java.lang.String GetUniqueID()
This ID is unique across all tags on all portlets on a given page.
This ID cannot be re-used across multiple pages and needs to be regenerated.
Tag Utility Method
public void SetStateVariable(java.lang.String _strKey, java.lang.Object _oValue, Scope _scope)
The scope determines who can see this variable and how long it stays in memory.
For instance, a variable stored in Tag Scope can only be seen by children of the current tag and will be removed from memory when the tag is finished.
A variable stored in Portlet Request Scope will be visible to all tags in the same portlet as the current tag, and will be removed from memory when the portlet is finished displaying. Tags in other portlets on the same page will not be able to see the variable.
Standard variables (as opposed to shared variables) can only be accessed by tags from the same tag library as the tag that originally stored the variable.
Note: Displaying an HTMLElement in a tag and then caching it so that another tag can add more HTML to the original tag later is not supported. HTMLElement trees can be generated and stored for later use, as long as they are self-contained trees and used in a read only way. It is safest to make clones of a cached HTMLElement tree before trying to display it again to make sure there are no threading problems.
Tag State Variable Method
String
- _strKey The key used to store the data.
The key cannot contain the reserved character '.'.Object
- _oValue The data to be stored. Note: setting
the value to null is the same as never having set the variable.Scope
- _scope The scope to store the data in
XPIllegalArgumentException
- if the key is null or
contains the reserved character '.', or if the scope
is null or unknown.public void SetStateSharedVariable(java.lang.String _strKey, java.lang.Object _oValue, Scope _scope, boolean bOwnerEditOnly)
The scope determines who can see this variable and how long it stays in memory.
For instance, a variable stored in Tag Scope can only be seen by children of the current tag and will be removed from memory when the tag is finished.
A variable stored in Portlet Request Scope will be visible to all tags in the same portlet as the current tag, and will be removed from memory when the portlet is finished displaying. Tags in other portlets on the same page will not be able to see the variable.
Shared variables (as opposed to standard variables) can be accessed by tags from any library. If bOwnerEditOnly is set to true when a shared variable is first stored, then any tag can read the variable, but only tags from the same library as the tag that originally stored the variable can edit it (and replace the value in memory).
Note: Displaying an HTMLElement in a tag and then caching it so that another tag can add more HTML to the original tag later is not supported. HTMLElement trees can be generated and stored for later use, as long as they are self-contained trees and used in a read only way. It is safest to make clones of a cached HTMLElement tree before trying to display it again to make sure there are no threading problems.
Tag State Variable Method
String
- _strKey The key used to store the data.
The key cannot contain the reserved character '.'.Object
- _oValue The data to be stored. Note: setting
the value to null is the same as never having set the variable.Scope
- _scope The scope to store the data in.bOwnerEditOnly
- True implies that only tags from
the same tag library should be able to store the value
for this tag. If this variable has already been saved,
then the original bOwnerEditOnly value will be retained
and this argument will be ignored.
XPIllegalArgumentException
- if the key is null or
contains the reserved character '.', or if the scope
is null or unknown.
XPIllegalAccessException
- if the variable is being
set by a tag from a different library than the original
tag that stored the variable with bOwnerEditOnly set to
true.public java.lang.Object GetStateVariable(java.lang.String _strKey, Scope _scope)
The scope determines who can see this variable and how long it stays in memory.
For instance, a variable can only be retrieved from Tag Scope if a tag that includes the current tag added the variable to Tag Scope.
A variable can only be retrieved from Portlet Request Scope if another tag in the portlet stored the variable in memory.
Standard variables (as opposed to shared variables) can only be accessed by tags from the same tag library as the tag that originally stored the variable.
Note: Retrieving an HTMLElement from memory that has already been displayed in another tag and then adding more HTML to the original tag is not supported. HTMLElement trees can be retrieved from memory and re-used, as long as they are not modified. The safest way to do this is to make a clone of the cached HTMLElement tree before trying to display it again to make sure there are no threading problems.
Tag State Variable Method
String
- _strKey The key used to store the data.
The key cannot contain the reserved character '.'.Scope
- _scope The scope used to store the data.
XPIllegalArgumentException
- if the key is null or
contains the reserved character '.', or if the scope
is null or unknown.public java.lang.Object GetAnyStateVariable(java.lang.String _strKey)
The scope determines who can see this variable and how long it stays in memory.
For instance, a variable can only be retrieved from Tag Scope if a tag that includes the current tag added the variable to Tag Scope.
A variable can only be retrieved from Portlet Request Scope if another tag in the portlet stored the variable in memory.
Standard variables (as opposed to shared variables) can only be accessed by tags from the same tag library as the tag that originally stored the variable.
This method will first look for standard variables, and if not found will then look for shared variables.
Note: Retrieving an HTMLElement from memory that has already been displayed in another tag and then adding more HTML to the original tag is not supported. HTMLElement trees can be retrieved from memory and re-used, as long as they are not modified. The safest way to do this is to make a clone of the cached HTMLElement tree before trying to display it again to make sure there are no threading problems.
Tag State Variable Method
String
- _strKey The key used to store the data.
XPIllegalArgumentException
- if the key is null.public java.lang.Object GetStateSharedVariable(java.lang.String _strKey, Scope _scope)
The scope determines who can see this variable and how long it stays in memory.
For instance, a variable can only be retrieved from Tag Scope if a tag that includes the current tag added the variable to Tag Scope.
A variable can only be retrieved from Portlet Request Scope if another tag in the portlet stored the variable in memory.
Shared variables can be accessed by tags from any tag library (as opposed to standard variables, which can only be accessed by tags from the same tag library).
Note: Retrieving an HTMLElement from memory that has already been displayed in another tag and then adding more HTML to the original tag is not supported. HTMLElement trees can be retrieved from memory and re-used, as long as they are not modified. The safest way to do this is to make a clone of the cached HTMLElement tree before trying to display it again to make sure there are no threading problems.
Tag State Variable Method
String
- _strKey The key used to store the data.
The key cannot contain the reserved character '.'.Scope
- _scope The scope used to store the data.
XPIllegalArgumentException
- if the key is null or
contains the reserved character '.', or if the scope
is null or unknown.public java.lang.Object GetTagAttributeAsTagVariable(ATagAttribute _attribute, Scope scope)
This is a helper method to get retrieve tag variable from tag variable id
PT Tag Attribute Method
ATagAttribute
- The requested attribute.Scope
- The scope to retrieve the tag variable from
public Scope GetTagAttributeAsScope(ATagAttribute _attribute)
This is a helper method to get retrieve the Scope object from a attribute that takes a scope name
PT Tag Attribute Method
ATagAttribute
- The requested attribute.
public java.lang.String GetTagAttributeAsString(ATagAttribute _attribute)
E.G. <pt:tag pt:ptattr="test" width="10"/> would get the ptattr attribute, but not the width attribute.
A description of the valid formats for attributes can be found in the AttributeType class.
PT Tag Attribute Method
ATagAttribute
- The requested attribute.
AttributeType.STRING
public int GetTagAttributeAsInt(ATagAttribute _attribute)
E.G. <pt:tag pt:ptattr="12" width="10"/> would get the ptattr attribute, but not the width attribute.
A description of the valid formats for attributes can be found in the AttributeType class.
PT Tag Attribute Method
ATagAttribute
- The requested attribute
XPFormatException
- if the attribute value
cannot be converted to an intAttributeType.INT
public boolean GetTagAttributeAsBoolean(ATagAttribute _attribute)
E.G. <pt:tag pt:ptattr="false" width="10"/> would get the ptattr attribute, but not the width attribute.
A description of the valid formats for attributes can be found in the AttributeType class.
PT Tag Attribute Method
ATagAttribute
- The requested attribute
XPFormatException
- if the attribute value
cannot be converted to a booleanAttributeType.BOOLEAN
public char GetTagAttributeAsChar(ATagAttribute _attribute)
E.G. <pt:tag pt:ptattr="t" width="10"/> would get the ptattr attribute, but not the width attribute.
A description of the valid formats for attributes can be found in the AttributeType class.
PT Tag Attribute Method
ATagAttribute
- The requested attribute
XPFormatException
- if the attribute value
cannot be converted to a charAttributeType.CHAR
public double GetTagAttributeAsDouble(ATagAttribute _attribute)
E.G. <pt:tag pt:ptattr="1.5" width="10"/> would get the ptattr attribute, but not the width attribute.
A description of the valid formats for attributes can be found in the AttributeType class.
PT Tag Attribute Method
ATagAttribute
- The requested attribute
XPFormatException
- if the attribute value
cannot be converted to a doubleAttributeType.DOUBLE
public long GetTagAttributeAsLong(ATagAttribute _attribute)
E.G. <pt:tag pt:ptattr="100" width="10"/> would get the ptattr attribute, but not the width attribute.
A description of the valid formats for attributes can be found in the AttributeType class.
PT Tag Attribute Method
ATagAttribute
- The requested attribute
XPFormatException
- if the attribute value
cannot be converted to a longAttributeType.LONG
public boolean HasTagAttribute(ATagAttribute _attribute)
E.G. <pt:tag pt:ptattr="test" width="10"/> would return true for ptattr, but not for width.
Note: Even though the tag may be present, it may produce an error when trying to process the tag.
PT Tag Attribute Method
_attribute
- ATagAttribute The attribute to check
public IXPEnumerator GetTagAttributeNames()
E.G. <pt:tag pt:ptattr="test" width="10"/> would return the ptattr attribute, but not the width attribute.
PT attributes are designed to specify the logic of the tag, while non-pt attributes specify the behavior of the resulting HTML tag.
In general, PT Attributes should have a corresponding ATagAttribute class and should be retrieved using the GetTagAttributeAs* methods. These methods handle default attribute values and attribute type conversion.
This method is present for backwards compatibility with the standard Transformer tags and should not be used if at all possible.
PT Tag Attribute Method
public java.lang.String GetTagAttribute(java.lang.String _strAttribute)
E.G. <pt:tag pt:ptattr="test" width="10"/> would get the ptattr attribute, but not the width attribute.
PT attributes are designed to specify the logic of the tag, while non-pt attributes specify the behavior of the resulting HTML tag.
In general, PT Attributes should have a corresponding ATagAttribute class and should be retrieved using the GetTagAttributeAs* methods. These methods handle default attribute values and attribute type conversion.
This method does not handle default attribute values if the attribute is not present, or if there is an error processing the attribute.
This method is present for backwards compatibility with the standard Transformer tags and should not be used if at all possible.
PT Tag Attribute Method
_strAttribute
- The requested attribute name
public java.lang.String GetXMLTagAttribute(java.lang.String _strAttribute)
E.G. <pt:tag pt:ptattr="test" width="10"/> would get the width attribute, but not the ptattr attribute.
XML attributes are designed to let a web designer specify standard HTML attributes for a tag without the tag author having to handle them individually. PT attributes specify the logic of the tag, while non-pt attributes specify the behavior of the resulting HTML tag.
This is only appropriate for tags that output a simple HTML tag.
This method does not handle default attribute values.
XML Tag Attribute Method
_strAttribute
- The requested attribute name
public boolean HasXMLTagAttribute(java.lang.String _strAttribute)
E.G. <pt:tag pt:ptattr="test" width="10"/> would return true for the width attribute, but not for the ptattr attribute.
XML attributes are designed to let a web designer specify standard HTML attributes for a tag without the tag author having to handle them individually. PT attributes specify the logic of the tag, while non-pt attributes specify the behavior of the resulting HTML tag.
This is only appropriate for tags that output a simple HTML tag.
Note: Even though the tag may be present, it may produce an error when trying to process the tag.
XML Tag Attribute Method
String
- _strAttribute The name of the non-pt attribute to check
public IXPEnumerator GetXMLTagAttributeNames()
E.G. <pt:tag pt:ptattr="test" width="10"/> would return the width attribute, but not the ptattr attribute.
XML attributes are designed to let a web designer specify standard HTML attributes for a tag without the tag author having to handle them individually. PT attributes specify the logic of the tag, while non-pt attributes specify the behavior of the resulting HTML tag.
XML Tag Attribute Method
This is only appropriate for tags that output a simple HTML tag.
public java.lang.String GetXMLTagAttributesAsString()
E.G. <pt:tag pt:ptattr="test" width="10" length="20"/> would return the following string: width="10" length="20"
XML attributes are designed to let a web designer specify standard HTML attributes for a tag without the tag author having to handle them individually. PT attributes specify the logic of the tag, while non-pt attributes specify the behavior of the resulting HTML tag.
XML Tag Attribute Method
This is only appropriate for tags that output a simple HTML tag.
public static java.lang.String EncodeForTagDoc(java.lang.String tagdocString)
tag in the string.
Example: String s = "Use the EncodeForTagDoc()
call to encode your documentation";
Lists of items can be shown in the tag docs using the ,
and - tags.
Example: String s = "The output contains 3 items:
- One
- Two, and
- 3
";
NOTE: This only encodes certain HTML elements (br, ul, li, and code), and only if
they are lower case.
- Parameters:
tagdocString
-
- Returns:
- The HTML string properly escaped for use in tag docs.
|
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |