<dsp:page> [dsp:servlet and basic tags] </dsp:page>
The tag may contain any dsp:servlet, basic tags, custom tags and text content.
The page tag is completely optional and is used to help DSP achieve XML compliance should the need arise. It is completely transparent and only serves to group multiple servlets together as a top- level element. It is not allowed inside of any other tags nor is it allowed to contain any DSP tags other than servlets.
<dsp:servlet [attributes] > [basic tags] </dsp:servlet>
The tag may contain any basic tags, custom tags and text content.
Use of the servlet tag is completely optional. Should the servlet tag not be used, a default servlet will be constructed, and all DSP tags will be processed into the default servlet’s response handler. This mode of operation allows DSP pages to take on a more traditional look similar to JSP code. See default servlet for more information about how this works.
The servlet tag defines information about the servlet. Multiple servlets are allowed per file, but only one default (anonymous) servlet is allowed. Only text inside the tag will be parsed as part of the servlet, leaving the rest of the file before and after the tag to evaluate as the enclosing servlet, or the default servlet if none is specified.
Named servlets can only be invoked via a custom tag binding, which is accomplished by use of the dsp:tag tag.
<dsp:import [attributes] />
The Import tag specifies a D library to import for servlet compilation. This is akin to the D ‘import’ statement, and follows the same semantics. The DSP Runtime will depend on the server’s configuration to determine what libraries are available for import.
<dsp:include [attributes] />
The Include tag allows the DSP developer to build a servlet out of multiple files, but incorporating the content of an external file, specified by 'file'. The content is inserted into the current servlet as though it replaces the include tag.
The 'as' attribute specifies the mode for inclusion. The default mode, 'output' simply passes the file's content to the servlet output without any additional processing. The 'code' mode, adds the file's content to the servlet as though it were contained in a dsp:code tag. Likewise, the 'in' and 'out' modes correspond to the dsp:in and dsp:out tags. Lastly, the 'dsp' mode treats the contents as DSP code, and will treat these as though the file's contents were placed at the include tag's location in the file.
The dependency attribute specifies if the file referenced in the include tag generates a dependency upon that file. Setting this to false will prevent changes to the included file from triggering a regeneration of the servlet.
<dsp:capture [attributes] > [content] </dsp:capture>
The tag may contain any basic tags, custom tags and text content.
The dsp:capture tag takes advantage of DSP's output stack behavior, and saves the content inside the tag to a specified variable, instead of passing it on to the output. All basic tags and custom tags behave as normal inside the dsp:capture tag.
<dsp:attribute [attributes] />
<dsp:attribute [attributes] > [r-value expression] </dsp:attribute>
The tag may contain any text or CDATA tags which will be treated as an expression, or nothing at all. The coded expression itself must be a proper r-value in the D language for output purposes. Whitespace will be evaluated and treated as a literal text expression.
The dsp:attribute tag is used when the servlet is invoked as a custom tag in another servlet. It defines a variable to hold the value of the passed attribute, when the servlet is invoked in this manner.
Attributes that are not explicitly defined by an dsp:attribute tag can still be accessed via the 'attributes' property of the request object. The syntax provided by the dsp:attribute tag is reccomended as it's less error prone, and far more convenient.
Using the ‘value’ attribute specifies a default for the attribute. The enclosing syntax is used when the 'value' attribute is not sufficient. The evaluated r-value expression will override anything used for the value attribute.
Type is used to cast the argument value to a type more immediately useful when invoking the servlet. This must be a valid D type that will satisfy a cast() statement.
<dsp:output> [r-value expression] </dsp:output>
The tag may contain any text or CDATA tags which will be treated as an expression. The coded expression itself must be a proper r-value in the D language for output purposes.
The Output tag appends data to the servlet output. The enclosed data must evaluate to a valid D r-value, such as a quoted string (e.g. "hello world") or a D statement or anything else that will satisfy an explicit conversion to char[].
<dsp:code> [code] </dsp:code>
The tag may contain any text or CDATA tags which will be treated as D code.
The Code tag allows the DSP developer to inject D code directly into the response handler of the servlet. Code elements are added to the handler in the order they are processed in the servlet source. Additionally, the DSP parser trusts the programmer to ensure that all text in the code block evaluates as valid D code, and that any open brackets or incomplete statements are completed in subsequent code elements.
Code sections will be treated as XML-encoded text, that may contain XML-entities like < and > (this is required as DSP is based on XML parsing technology). Alternately, you may wrap your code in a CDATA block, and use literal D code instead.
<dsp:in> [code] </dsp:in>
The tag may contain any text or CDATA tags which will be treated as D code.
The In tag allows the DSP developer to specify code that is run before the response handler, that is intended to test preconditions. Should any precondition fail, an assert should be generated that will prevent the handler from executing.
All dsp:in code blocks are coalesced into a single contract for the response handler. They are combined in the order they are processed in the DSP page. It is important to note that since an In block runs before the rest of the handler, it only has access to the ‘response’ and ‘request’ parameters for the response handler. It is essentially within its own scope and will not have access to anything declared outside of another dsp:in tag.
<dsp:out> [code] </dsp:out>
The tag may contain any text or CDATA tags which will be treated as D code.
The Out tag allows the DSP developer to specify code that is run after the response handler, that is intended to test post conditions. Should any post condition fail, an assert should be generated that will trigger an exception. Such an exception will result in the servlet’s response being destroyed.
All dsp:out code blocks are coalesced into a single contract for the response handler. They are combined in the order they are processed in the DSP page. It is important to note that since an out block runs after the rest of the handler, it only has access to the ‘response’ and ‘request’ parameters for the response handler. It is essentially within its own scope and will not have access to anything declared outside of another dsp:out tag.
<dsp:tag [attributes] > [dsp:default] </dsp:tag>
<dsp:tag [attributes] />
The tag may contain any number of dsp:default tags, including none.
This tag embeds another servlet into the current servlet in the form of a custom DSP tag. The tag also creates a dependency for the embedded servlet, so changes to that servlet will trigger a regeneration of this servlet as well.
The dependency attribute specifies if the file referenced in the include tag generates a dependency upon that file. Setting this to true will cause changes in the included file to trigger a regeneration of the servlet.
The name attribute specifies the tag name to use when calling the embedded servlet. In the case of 'file' indicating a DSP servlet, the name attribute maps to the default servlet of the target. Should the target contain any named servlets, those named servlets are also mapped to custom tags that use the value of the 'name' attribute as a namespace, followed by the separator and the names of the named servlets. This allows the developer to map to an entire 'tag library' by specifying a name like "x" so that the named servlets in the 'tag library' are mapped similar to "x:foo" and "x:bar".
Once defined, an embedded servlet may be invoked simply by using its tag name elsewhere in the page. See custom tags for more information.
Data is sent to the custom tag via a process called ‘forwarding’. Any attributes that match the attribute tag expressions for the servlet will be forwarded and set before the response handler is run. The tag may also have any number of enclosed dsp:argument tags that also define attribute values for forwarding. Default attribute values may be defined in the calling servlet by use of the dsp:default tag.
The target file, as specified by the 'file' attribute, is passed the attribute values resolved at the point the custom servlet is invoked in the calling DSP page. The attribute set is passed to the page as is appropriate given its type. Should the target be a DSP script, the attribute set will be matched, and converted through whatever dsp:attribute it has declared.
If the target is anything other than a DSP script, the attribute set is converted to a set of HTTP post params and passed to the file as though a separate HTTP post request was made. The generated output from the request is then incorporated into the output of the calling servlet, where the custom tag was invoked.
Custom tag content can also be passed to an embedded servlet when it is invoked, via the "__content" attribute. This content is the sum of all of the dynamic output, of all the data and DSP tags enclosed in the expression, including other embedded servlets. This is accomplished through the response object’s stack-like semantics for output handling. It is because of this stack-like behavior that the evaluation order of embedded servlets moves from innermost to outermost, rather than from top to bottom.
<dsp:default [attributes] />
<dsp:default [attributes] > [r-value expression] </dsp:default>
The tag may contain any text or CDATA tags which will be treated as an expression, or nothing at all. The coded expression itself must be a proper r-value in the D language for output purposes. Whitespace will be evaluated and treated as a literal text expression.
The dsp:default tag is used when defining an embedded servlet via the 'tag' tag.
The enclosing syntax is used when the 'value' attribute is not sufficient. The evaluated r-value expression will override anything used for the value attribute.
Type is used to cast the default argument to a type more immediately useful when invoking the servlet. This must be a valid D type that will satisfy a cast() statement.
<dsp:argument [attributes] />
<dsp:argument [attributes] > [r-value expression] </dsp:argument>
The tag may contain any text or CDATA tags which will be treated as an expression, or nothing at all. The coded expression itself must be a proper r-value in the D language for output purposes. Whitespace will be evaluated and treated as a literal text expression.
The dsp:argument tag is used when calling an embedded servlet via a custom tag.
The Argument tag is used when invoking an embedded servlet, and appears inside the servlet’s custom tag when it is invoked. It is used as an alternative to using actual attributes when invoking an embedded servlet.
The enclosing syntax is used when the 'value' attribute is not sufficient. The evaluated r-value expression will override anything used for the value attribute.
Type is used to cast the default argument to a type more immediately useful when invoking the servlet. This must be a valid D type that will satisfy a cast() statement.
<!-- [hidden content] -->
<!--# [client content] -->
Both versions of the comment tag may contain any characters except '-', due to the XML specification parsing rules.
It is undesireable to send all code comments to the client machine. In such a case, the secondary synax (with the leading embedded '#') is used to specify that a comment's content (following the '#') is to be sent to the client. Should the developer need to hide comments from the client, the first form will provided the needed functionality.
# [r-value expression] #
##
The tag may contain any text which will be treated as an expression. The coded expression itself must be a proper r-value in the D language for output purposes.
This is, for the most part, an alias for the dsp:output tag. While it serves the same purpose, it can be used in more contexts than the tag version without disrupting XML compatiblity. Unlike the dsp:output tag, it can be used inside tag attributes, where it is dynamically meshed with text data to create a coherent attribute output value. It can also be used in tag content areas.
The secondary syntax is used when a single '#' is needed to be generated in the output. It has a lower precedence than the single '#' symbol, so back-to-back alias expressions will function correctly.
The enclosed data must evaluate to a valid D r-value, such as a quoted string (e.g. "hello world") or a D statement or anything else that will satisfy an explicit conversion to char[].
<?dsp:xml [pi content] ?>
<?dsp:pi:[pi name] [pi content] ?>
The tag may contain any text except for the '?' symbol.
The behavior of the DSP parser will 'eat' any processing instruction it encounters in the text of a given DSP script. However, it may be desireable to emit a processing instruction to the script output. To allow this behavior, these specialized processing instructions are included.
The first form, 'dsp:xml' emits the processing instruction content, unparsed, into a processing instruction beginning with 'xml'. The second form, allows a processing instruction of any name to be emitted as a processing instruction. Simply prefix the desired instruction with 'dsp:pi:' and the DSP parser does the rest.
<?dsp [code] ?>
<?dsp:in [in code] ?>
<?dsp:out [out code] ?>
<?dsp:output [output r-value code] ?>
The tag may contain any text except for the '?' symbol.
In order to allow some familiarity with other web languages, such as PHP, these aliases are provided to accomplish the same feel. The content of any of these custom processing instructions will be interpreted as code and inserted into the appropriate portion of the servlet.
These behave as aliases to some of the more formal dsp code tags. The first form, 'dsp' corresponds directly to the dsp:code tag. The second and third forms, 'dsp:in' and 'dsp:out', correspond to the dsp:in and dsp:out tags respectively. The forth form, 'dsp:output' corresponds to the dsp:output tag, and adopts is requirements for the code to be a D language r-value.
<[tag name] [attributes] />
<[tag name] [attributes] > [content] </[tag name]>
Any top level tag, text content or the dsp:argument tag.
Invokes an embedded servlet via the tag declared via the dsp:tag tag. Attributes are passed to the servlet via the attributes declared in the custom tag itself. The target servlet is then responsible for generating any output that may be passed back to the calling servlet.
The dsp:argument tag is used to pass arguments to the servlet that may be more complicated than the inline attribute syntax allows. They are also used to provide a means for conditionally passed arguments.