Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
|- valign="top"
| {{Code|parameter-document}}
| Parses the value as XML document with additional serialization parameters (see the [https://www.w3.org/TR/xslt-xquery-serialization-31/#serparams-in-xdm-instance Serialization Specification] for more details).
| ''string''
|
Text replacement - "syntaxhighlight" to "pre"
The namespace for serialization parameters is statically bound to the {{Code|output}} prefix. This means that it need not (but may) be declared in the query prolog:
<syntaxhighlight pre lang="'xquery"'>
declare namespace output = 'http://www.w3.org/2010/xslt-xquery-serialization';
declare option output:method 'text';
<xml>Hi there</xml>
</syntaxhighlightpre>
Due to the wide range of ways how parameters can be supplied, we deliberately ignored one rule of the specification, which requires non-official features to be defined in a non-null namespace URI. In the following, we will indicate which features are specific to our implementation.
=Standard Parameters=
The following serialization parameters are supported by BaseX (further details can be looked up in the official specification):
|- valign="top"
| {{Code|indent}}
| Adjusts Adds leading whitespaces to make the output better more readable.
| {{Code|yes}}, {{Code|no}}
| {{Code|yesno}}
|- valign="top"
| {{Code|cdata-section-elements}}
| List of elements to be output as CDATA, separated by whitespaces.<br />Example: {{Code|<text><![CDATA[ <> ]]></text>}}
| ''string''
|
|- valign="top"
| {{Code|omit-xml-declaration}}
| Omits the XML declaration, which is serialized before the actual query result<br />Example: <code><?xml version="1.0" encoding="UTF-8"?></code>
| {{Code|yes}}, {{Code|no}}
| {{Code|yes}}
|- valign="top"
| {{Code|standalone}}
| Prints or omits the "{{Code|standalone" }} attribute in the XML declaration.
| {{Code|yes}}, {{Code|no}}, {{Code|omit}}
| {{Code|omit}}
|- valign="top"
| {{Code|doctype-system}}
| Introduces the output with a document type declaration and the given system identifier.<br />Example: {{Code|<!DOCTYPE x SYSTEM "entities.dtd">}}
| ''string''
|
|- valign="top"
| {{Code|doctype-public}}
| If {{Code|doctype-system}} is specified, adds a public identifier.<br />Example: {{Code|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>">}}
| ''string''
|
| ''string''
| {{Code|application/xml}}
|- valign="top"
| {{Code|use-character-maps}}
| Defines character mappings. If maps mappings are supplied as a single string, keys and values are separated by the equal sign (<code>=</code>), and multiple pairs are separated by commas (. Separators that are to be defined as keys or values can be encoded as entities.<br/>Example: <code>A=alpha,B=beta</code>).
| ''string''
|
|- valign="top"
| {{Code|escape-uri-attributes}}
| Escapes URI information in certain HTML attributes<br />Example: <code><a href="%C3%A4%C3%B6%C3%BC">äöü<a></code>
| {{Code|yes}}, {{Code|no}}
| {{Code|no}}
|- valign="top"
| {{Code|include-content-type}}
| Inserts a {{Code|meta}} content-type element into the head element if the result is output as HTML<br />Example: <code><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></head></code>. The head element must already exist or nothing will be added. Any existing {{Code|meta}} content-type elements will be removed.
| {{Code|yes}}, {{Code|no}}
| {{Code|yes}}
|}
=Query Prolog Parameters=
The following parameters can only be specified in the query prolog (see [https://www.w3.org/TR/xquery-31/#id-serialization XQuery: Specification] for more details and examples):
{| class="wikitable sortable" width="100%"
|- valign="top"
! width="140" | Parameter
! Description
! Allowed
! Default
|- valign="top"
| {{Code|parameter-document}}
| Parses the value as an XML document with additional serialization parameters.
| ''string''
|
|}
=Custom Parameters=
BaseX provides some additional serialization parameters:
| ''positive number''
| {{Code|2}}
|- valign="top"
| {{Code|indent-attributes}}
| {{Announce|Version 11:}} Indent attributes after the element name, one below the other.
| {{Code|yes}}, {{Code|no}}
| {{Code|false}}
|- valign="top"
| {{Code|newline}}
The {{Code|csv}} and {{Code|json}} parameters are supplied with a list of options. Option names and values are combined with <code>=</code>, several options are separated by <code>,</code>:
<syntaxhighlight pre lang="'xquery"'>
declare option output:method "csv";
declare option output:csv "header=yes, separator=semicolon";
</record>
</csv>
</syntaxhighlightpre>
If {{Code|fn:serialize}} is called, output-specific parameters can be supplied via nested options:
<syntaxhighlight pre lang="'xquery"'>
serialize(
<csv>
}
)
</syntaxhighlightpre>
'''Result''':
<syntaxhighlight pre lang="xml">
Name;City
John;Newton
Jack;Oldtown
</syntaxhighlightpre>
=Character mappings=
Character maps allow a specific character in the instance of the data model to be replaced with a specified string of characters during serialization. The string that is substituted is output "as “as is," ” and the serializer performs no checks that the resulting document is well-formed. This may only occur in documents parsed with {{Code|parameter-document}}. If a character is mapped, then it is not subjected to XML or HTML escaping. For details , refer to section [https://www.w3.org/TR/2015/CR-xslt-xquery-serialization-31-20151217/#character-maps 11 Character maps] in the [https://www.w3.org/TR/xslt-xquery-serialization-31 W3C XQuery Serialization 3.1] document.
This example maps the Unicode U+00A0 NO-BREAK SPACE as &#160; (without the serialization parameter, the Unicode character would be output):
'''Example query''':
<syntaxhighlight pre lang="'xquery"'>
declare option output:parameter-document "map.xml";
<x>&#xA0;</x>
</syntaxhighlightpre>
'''Example parameter-document''':
<syntaxhighlight pre lang="xml">
<serialization-parameters
xmlns="http://www.w3.org/2010/xslt-xquery-serialization">
</use-character-maps>
</serialization-parameters>
</syntaxhighlightpre>
=Changelog=
;Version 11.0
* Added: Serialization parameter {{Code|indent-attributes}}.
;Version 10.0
* Updated: {{Code|indent}}: Default changed from {{Code|yes}} to {{Code|no}}.
;Version 9.2
* Updated: New default value for {{Code|include-content-type}} is {{Code|yes}}.
;Version 8.4
* Added: Serialization parameter {{Code|binary}}.
* Updated: New serialization method <code>basex</code>. By default, items of binary type are now output in their native byte representation. The method <code>raw</code> was removed.
;Version 8.0
* Added: Support for {{Code|use-character-maps}} and {{Code|parameter-document}}.
* Added: Serialization method {{Code|adaptive}}.
;Version 7.8.2
* Added: {{Code|limit}}: Stops serialization after the specified number of bytes has been serialized.
;Version 7.8
* Added: {{Code|csv}} and {{Code|json}} serialization parameters.
* Removed: {{Code|separator}} option (use {{Code|item-separator}} instead).
;Version 7.7.2
* Added: {{Code|csv}} serialization method.
* Added: temporary serialization methods {{Code|csv-header}}, {{Code|csv-separator}}, {{Code|json-unescape}}, {{Code|json-spec}}, {{Code|json-format}}.
;Version 7.5
* Added: official {{Code|item-separator}} and {{Code|html-version}} parameter.
* Updated: <code>method=html5</code> removed; serializers updated with the [https://www.w3.org/TR/2013/WD-xslt-xquery-serialization-30-20130108/ latest version of the specification], using <code>method=html</code> and <code>version=5.0</code>.
;Version 7.2
* Added: {{Code|separator}} parameter.
;Version 7.1
* Added: {{Code|newline}} parameter.
;Version 7.0
* Added: Serialization parameters added to [[REST API]]; JSON/JsonML/raw methods.
