Adaptive Tag API Documentation
|| 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:
The ITagMetaData, RequiredTagAttribute, and OptionalTagAttribute objects are used for programmatic access to tag meta data, as well as to pre-process tag attributes (presence, correct type, and default values). If the required attributes are not correct, an error will be logged and the tag and its children will be skipped and not displayed. An HTML Comment describing the tag and error will be displayed instead. A description of the valid formats for attributes can be found in the AttributeType class. Optionally, a Tag developer can also:
- Implement the DisplayTag() abstract method. If you want this tag to display the HTML and tags inside the tag, you must call ProcessTagBody() and return the resulting HTML.
- Implement the Create() abstract method to return a new instance of this Tag.
- Create exactly one public static final ITagMetaData member variable that provides the name and description of the Tag and initialize it in the static initializer. 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.
- Create one public static final RequiredTagAttribute or OptionalTagAttribute member variable for every attribute that this tag supports and initialize them in the static initializer. 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");
All public static final metadata objects should be initialized together in a single static initializer so that the order of initialization can be properly controlled. 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.
- Override the GetTagType() method to show that this tag is a different type of tag; e.g. LOOPING or NO_BODY.
- Override the ReleaseTag() method to release data stored on the tag. All tags that store custom data as member variables should override this method.
- Create a public static final RequiredParentTag member variable to require that this tag be used inside a particular tag and initialize it in the static initializer. If there are multiple RequiredParentTag members, then at least one parent tag must be present in order for the tag to function (but not all parent tags are required to be present).
- Create one public static final RequiredChildTag member variable for every tag that is required to be used inside this tag and initialize it in the static initializer.
- Create one public static final RelatedChildTag member variable for every tag that is designed to be used inside this tag, but is not required to be used inside this tag. Initialize the member variable in the static initializer.
Thread Safety 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.
- Abstract Tag Methods: These methods need to implemented by the Tag developer.
- Default Tag Methods: These methods can be overridden by the Tag developer.
- Tag Utility Methods: These methods are used by the Tag developer in their\u0009Tag and should not be overridden. This includes the IEnvironment class, which contains information about the current request and user, including locale information.
- Tag State Variable methods: These methods are used by the Tag developer to get and set Tag State Variables in their Tags and should not be overridden. Tag State Variables are used for inter-tag communication and are similar to storing data on the HTTP Session.
- PT Tag Attribute Methods: These methods are used by the Tag developer to access PT Tag attributes in their Tags and should not be overridden. E.G. <pt:tag pt:attribute="false"/>
- XML Tag Attribute Methods: These methods are used by the Tag developer to access XML Tag attributes in their Tags and should not be overridden. E.G. <pt:tag attribute="false"/>
- Framework Helper Methods: These methods are used by the framework and should\u0009not be called or overridden by the Tag developer.
|| This enumeration specifies the various scopes that can be used to store data in memory. The Duration comments specify how long the data stored in that scope will be maintained, and when the data will be removed. The Visibility comments specify which tags can access the data stored in that scope. 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.
|| This enumeration specifies the type of the tag. SIMPLE tags call ProcessTagBody at most once, whereas LOOPING tags can call it multiple times. NO_BODY tags do not display any tags or HTML nested inside them.
|| This class manages variable storage and retrieval for tags. It allows you to get and set variables for various contexts (session, request, tag, etc...).