Find file
Fetching contributors…
Cannot retrieve contributors at this time
341 lines (286 sloc) 7.48 KB
__NAME__ purpose
(obsolete) export selected Interchange session information as XML data
__END__
__NAME__ notes
<emphasis role='bold'>
Pay special attention to whitespace! The &tag-__FILENAME__; tag is very
particular about white space.
</emphasis>
</para><para>
It appears that the <literal>type=delimited</literal> and
<literal>field_names=</literal> do not function properly. This is,
however, not a problem because &tag-xml-generator; is obsolete. If you
use it, you can you can still achieve the same functionality by using
<literal>type=<replaceable>field_name</replaceable></literal>.
</para><para>
In any case, if you verify the problem and supply a patch, we'd be
glad to accept it.
<!-- TODO ^^^ if anyone wants to play with this -->
__END__
__NAME__ synopsis
<row>
<entry>type</entry>
<entry>Yes</entry>
<entry></entry>
<entry><literal>delimited</literal></entry>
<entry>
If set to <literal>delimited</literal>, then
<arg choice='plain'>field_names</arg> specifies the list of values to extract
from the session.
If <emphasis role='bold'>not</emphasis>
<literal>delimited</literal>, acts as a hash reference key into the
user's session.
Examples are good known session elements, such as &glos-value;s or
&glos-scratch; variables, <literal>errors</literal>, or any other session
key, such as <literal>source</literal>
</entry>
</row>
<row>
<entry>field_names</entry>
<entry></entry>
<entry></entry>
<entry>none</entry>
<entry>
Field names from the users' session to extract and display as XML
</entry>
</row>
<row>
<entry>
toplevel_tag
</entry>
<entry></entry>
<entry></entry>
<entry>
<literal>table</literal> for the type <literal>delimited</literal>,
<literal>session</literal> otherwise
</entry>
<entry>
The toplevel tag name to create
</entry>
</row>
<row>
<entry>table_name</entry>
<entry></entry>
<entry></entry>
<entry>none</entry>
<entry>
A <literal>name=</literal> attribute (if any) to append to the generated
&glos-HTML; &lt;table&gt; element. This is only used with type
<literal>delimited</literal>. Example output is
<literal>&lt;table name="<replaceable>name</replaceable>"&gt;</literal>
</entry>
</row>
<row>
<entry>attributes</entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry>
Attributes, if any, to pass on to the top level XML tag. See
<xref linkend="xml-generator_examples"/> for clarification
</entry>
</row>
<row>
<entry>no_second</entry>
<entry></entry>
<entry></entry>
<entry>false</entry>
<entry>
Prevents the second-level of XML tags from being generated
</entry>
</row>
<row>
<entry>separator</entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>
<row>
<entry>delimiter</entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>
<row>
<entry>joiner</entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>
<row>
<entry>spacer</entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>
<row>
<entry>dbdump</entry>
<entry></entry>
<entry></entry>
<entry>false</entry>
<entry>
</entry>
</row>
<row>
<entry>field_tag</entry>
<entry></entry>
<entry></entry>
<entry><literal>field</literal></entry>
<entry>
</entry>
</row>
<row>
<entry>record_tag</entry>
<entry></entry>
<entry></entry>
<entry><literal>record</literal></entry>
<entry>
</entry>
</row>
<row>
<entry>skip_empty</entry>
<entry></entry>
<entry></entry>
<entry>false</entry>
<entry>
</entry>
</row>
<row>
<entry>key_name</entry>
<entry></entry>
<entry></entry>
<entry></entry>
<entry>
</entry>
</row>
&TAG_CONTAINER_1_1;
__END__
__NAME__ description
This tag converts &IC; session information (stored inside &PERL; structures)
to XML output.
</para><para>
It accepts a list of records (delimited by TAB, separated by newline, by
default), for example those generated by &tag-item-list;, &tag-sql; or
&tag-loop; tags.
</para><para>
If the value passed to the <arg choice='plain'>session</arg> argument
is a hash reference, it will be XML-ified having <literal>session</literal>
as top element, and the actual value just beneath it at second level.
</para><para>
It is possible to show only subsets of complete hashes. To dump only
first and last name from the &glos-value;s space, use the following
snippet in the actual call to &tag-xml-generator;:
<code>type=values values="fname lname"</code>.
__END__
__NAME__ example: Dump first and last name to XML
<programlisting>
[comment]
The following two fields are set manually only to complete the example,
users are expected to define those values themselves.
[/comment]
[value name=fname set=Ivan hide=1]
[value name=lname set=Novak hide=1]
[xml-generator type=values values="fname lname" /]
</programlisting>
would generate:
<programlisting><![CDATA[
<session>
<values>
<fname>Ivan</fname>
<lname>Novak</lname>
</values>
</session>
]]></programlisting>
__END__
__NAME__ example: Dump a single value to XML
<programlisting>
[comment]
The following field is set manually only to complete the example,
users are expected to define those values themselves.
[/comment]
[value name=cybercash_id set=12345 hide=1]
[xml-generator type=cybercash_id /]
</programlisting>
would generate:
<programlisting><![CDATA[
<session>
<cybercash_id>[data session cybercash_id]</cybercash_id>
</session>
]]></programlisting>
__END__
__NAME__ example: Change the toplevel element name, and suppress creation of the second-level one
In this example, the top level element <literal>session</literal> is
replaced with <literal>dataset</literal>, and the 3rd level appears
as second level, because the 2nd level tags will be suppressed.
<programlisting>
[xml-generator
toplevel_tag=dataset
no_second=1
type="values scratch"
values="fname lname"
scratch=downloads /]
</programlisting>
would, depending on the exact values in the users' session, generate:
<programlisting><![CDATA[
<dataset>
<fname>Ivan</fname>
<lname>Novak</lname>
<downloads>0</downloads>
</dataset>
]]></programlisting>
__END__
__NAME__ example: A complete example, combination of all features
<programlisting>
[xml-generator
attributes="date_orig date_update"
date_orig="05-Mar-2000"
date_update="[tag time]%d-%b-%Y[/tag]"
type="values scratch source"
values="fname lname"
scratch=downloads /]
</programlisting>
would, depending on the exact values in the users' session, generate:
<programlisting><![CDATA[
<session date_orig="05-Mar-2000" date_update="05-Feb-2005">
<values>
<fname>Ivan</fname>
<lname>Novak</lname>
</values>
<scratch>
<downloads>0</downloads>
</scratch>
<source>Partner1</source>
</session>
]]></programlisting>
__END__
__NAME__ example: Exporting products SKU, title and price to XML
<programlisting>
[xml-generator type="delimited" toplevel_tag="products" field_names="sku title price"][query list=1 sql="select sku, title, price from products" prefix=xml][xml-param sku] [xml-param title] [xml-param price]
[/query][/xml-generator]
</programlisting>
__END__
**** Notice the missing _ at the beginning, this is effectively a comment.
_NAME__ example: Display an individual field
We rely on the default setting of <literal>type=delimited</literal> here:
<programlisting>
[comment]
The following field is set manually only to complete the example,
users are expected to define those values themselves.
[/comment]
[value name=source set=Partner1 hide=1]
[xml-generator
toplevel_tag=dataset
no_second=1
field_names=source /]
</programlisting>
would, depending on the exact values in the users' session, generate:
<programlisting><![CDATA[
<dataset>
<source>Partner1</source>
</dataset>
]]></programlisting>
_END__