ns_adp_tagset - Managing ADP Tag Sets
The ns_adp_tagset command manages named ADP tag sets. A tag set is a server-wide collection of registered ADP tags used by the ADP parser when recognizing markup-like ADP tags such as registered script, procedure, or ADP-backed tags.
The built-in tag set named default is the ordinary server-wide ADP tag table used by NaviServer when no named tag set is selected. This is the traditional behavior of registered ADP tags.
Named tag sets are useful when different parts of an application should parse ADP pages with different registered-tag definitions. This is especially useful for migrations where legacy pages and newly compiled or transformed ADP pages have to coexist in the same NaviServer server.
Creates a named ADP tag set.
The name must not be default, since default is reserved for the built-in server-wide ADP tag table.
Without -fallback, the new tag set is isolated: only tags registered explicitly in this tag set are recognized when parsing with this tag set.
With -fallback default, the parser first looks for a tag in the named tag set and, if it is not found there, falls back to the built-in default tag table. Currently, default is the only permitted value for the fallback tagset.
ns_adp_tagset create app-tags ns_adp_tagset create -fallback default app-tags-with-defaults
Returns a boolean indicating whether the specified tag set exists.
The reserved tag set default always exists.
ns_adp_tagset exists default ## output: 1 ns_adp_tagset exists app-tags ## output: 1 or 0
Returns a list of available ADP tag-set names.
The result always includes default, followed by the names of explicitly created tag sets.
ns_adp_tagset names ## output: default app-tags app-tags-with-defaults
Returns information about the specified tag set as a dictionary.
The dictionary contains at least the following keys:
The number of tags registered directly in this tag set.
The configured fallback tag set. Currently this is either default or the empty string.
ns_adp_tagset info default
## output: size 12 fallback {}
ns_adp_tagset info app-tags-with-defaults
## output: size 2 fallback default
The ns_adp_registeradp, ns_adp_registerproc, and ns_adp_registerscript commands accept an optional -tagset argument.
Without -tagset, tags are registered in the built-in default tag table. With -tagset, tags are registered in the specified named tag set. The reserved name default is equivalent to omitting -tagset.
ns_adp_tagset create -fallback default compiled-tags ns_adp_registerscript -tagset compiled-tags foreach /foreach ::my::foreach_tag ns_adp_registerscript -tagset compiled-tags multiple /multiple ::my::multiple_tag
Named tag sets are selected when parsing ADP, for example with ns_adp_parse or ns_adp_include.
If no -tagset is specified, the current effective tag set is inherited. This means includes normally use the same tag set as the caller.
If -tagset default is specified, the parse or include operation uses the built-in default tag table for that operation only.
If -tagset name is specified, the parse or include operation uses the named tag set for that operation only. After the operation returns, the previous effective tag set is restored.
# Parse with a named tag set. ns_adp_parse -tagset compiled-tags -string $adp # Include a legacy/default fragment from a page parsed with another tag set. ns_adp_include -tagset default legacy-fragment.adp # Include a fragment with a named tag set. ns_adp_include -tagset compiled-tags fragment.adp
A named tag set created without -fallback is isolated.
ns_adp_tagset create strict-tags
When parsing with strict-tags, only tags registered in strict-tags are recognized.
A named tag set created with -fallback default first checks the named tag set and then the built-in default tag table.
ns_adp_tagset create -fallback default migration-tags
This is useful during migrations, where only a few tags have to be overridden while all other registered tags should continue to use the traditional default definitions.
The effective ADP tag set is part of the identity of parsed ADP code. When a file is parsed under a named tag set, NaviServer keeps the parsed ADP cache separate from the same file parsed under the default tag set or under another named tag set.
This avoids reusing ADP code that was parsed with a different set of registered tags.
Create a tag set for transformed ADP pages, falling back to the existing server-wide tags:
ns_adp_tagset create -fallback default transformed-adp
Register a tag only in this tag set:
proc ::demo::hello_tag {body attributes} {
return "Hello from transformed ADP"
}
ns_adp_registerscript -tagset transformed-adp hello /hello ::demo::hello_tag
Parse a string using the named tag set:
ns_adp_parse -tagset transformed-adp -string {
Before <hello>ignored body</hello> after
}
Include a fragment using the named tag set:
ns_adp_include -tagset transformed-adp fragment.adp
Force the default tag table for an include:
ns_adp_include -tagset default legacy-fragment.adp
Tag sets are server-wide. Selecting a tag set with -tagset affects only the current parse or include operation and is scoped: the previous effective tag set is restored afterwards.
There is currently no command to delete a tag set or to deregister a single registered ADP tag.