Function: Generates relevant HTTP headers for the admin interfaces.

Synopsis: This handler is invoked automatically by the Keystone system.

Result: This handler is special in the sense that it is invoked automatically by the shell.php in case the admin interface is about to be loaded. If not overwritten, this handler generates the relevant HTTP headers for authentication.

Warning: In general, this handler should not be overwritten except when you know exactly what you're doing!

See also tkl-header.

Function: Query HTTP GET'd/POST'd variables.

Synopsis: tkl-args:

Result: XML encoding representation of a list of key => value pairs, for instance,

  <args>
    <var1>value1</var1>
    <var2>value2</var2>
  </args>
      

If an array variable, i.e.

  Array
  (
      [key1] => value1
      [key2] => value2
  )
      

is present, it will be encoded this way:

  <args>
    <list i="key1">value1</list>
    <list i="key2">value2</list>
  </args>
      

Function: Looks for the presence of a file in portal area and Keystone core area.

Synopsis: tkl-default:?path=my_dir/my_file

Result: Path is the name of the file relative to the portal root. The handler looks for this file in the portal area. If it exists, the absolute path is returned. Otherwise, the file is looked for in the Keystone core area. If it exists here, the absolute path is returned, otherwise an error flag is raised. Example:

  <tkl-default>
    <abs_path>/var/www/bibliotheca/my_dir/my_file</abs_path>
  </tkl-default>
      

on success. On error, the returned XML looks like this:

  <tkl-default>
    <error>Error message</error>
  </tkl-default>
      

Function: Opens a Keystone file and filters language dependent elements.

Synopsis: tkl-file://subdir/my_file.tkl

Result: This handler returns an XML document tree ready to process in XSLT. It is important not to confuse the "tkl-file" handler with the generic XSLT handler "file". The differences can be summarized this way:

The tkl-file handler is well-suited for importing general XML into your stylesheet, Keystone files as well as XSLT stylesheets, or any other type of XML. The tkl-file handler works excellent in combination with the XSLT import and include instructions, i.e.

  <xsl:import href="tkl-file://my_stylesheet.xsl"/>
  <xsl:include href="tkl-file://subdir/some_other_stylesheet.xsl"/>
      

which are the preferred XSL stylesheet inclusion idioms.

Function: Checks if a specified file exists.

Synopsis: tkl-file-exists:?file=path/to/file.tkl

Result: Returns the following XML structure:

  <tkl-file-exists>
    <exists>1</exists>
  </tkl-file-exists>
      

if the file exists, and of course otherwise,

  <tkl-file-exists>
    <exists>0</exists>
  </tkl-file-exists>
      

Function: Finds files which match a given pattern or mask.

Synopsis: tkl-find://?path=pathmask&mask=filemask&select=fieldmask&level=number

Result: A list oif <file> elements, one for each matching file, containing the elements of each file given by fieldmask.

Example: tkl-find:/?path=*/index.tkl&select=title

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <tkl-find>
  <file path="./news/index.tkl">
  <title>Nu med links!</title>
  </file>
  <file path="./oldcheese/index.tkl">
  <title>Gammel ost på nye flasker</title>
  </file>
  .....
  </tkl-find>
      

The tkl-find function can be used in two different ways. IN the simple version, it searches for files which match path-parameters (comparable to a simple listing of files matching a filename (glob) pattern in a Unix shell. It returns a number of file elements, containing the elements selected by the fieldmask parameter.

The fieldmask parameter has the form element|element|... - in other words, an arbitrary number of element names separated by vertical bars.

The function can also be used like the find-command of Unix, to recursively traverse one or more subtrees.This example from the base test portal finds all index.tkl files in subdirectories of links/* two levels down.

tkl-find:/?path=links/*&mask=index.tkl&select=title&level=2

Returns:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <tkl-find>
     <dir path="./links/27/" level="1" att="2">
     <file path="./links/27/index.tkl">
     <title xml:lang="en">General Subjects</title>
     </file>
     <dir path="./links/27/01/" level="2" att="2">
     <file path="./links/27/01/index.tkl">
     <title xml:lang="en">Cross-disciplinary subjects</title>
     </file>
     </dir>
     <dir path="./links/27/03/" level="2" att="2">
     <file path="./links/27/03/index.tkl">
     <title xml:lang="en">Library collections</title>
     </file>
     </dir>
     </dir>
     ................
    </tkl-find>
      

(please note that the structure above represents a hierarchy, where directory elements can contain both files and onther directories).

If the path expression only matches files, there is no needs to provide a mask. If the path expression matches directories, the function will search these subdirectories, looking for files matching the mask parameter, until level levels (steps)

The <dir> and <file> elements both have a path-attribute, which provides a relative path to the file or directory (with respect to the location of the current document).Usually, this means that these paths can be used without modification in, say, a HTML <A> element, as a relative URL.

However, please note that if the original path expression is absolute (ie. starts with a '/'), it is processed relative to the root of the portal , and the path-attribute in the <dir> and <file> elements can be used directly as a server-absolute URL. For example:

    tkl-find://?path=/news/news*.tkl&select=date|title
    <tkl-find>
     <file path="/tkl/news/news1.tkl">
     <date>2002-07-08</date>
     <title xml:lang="en">The test has begun</title>
     </file>
     <file path="/tkl/news/news429.tkl">
     <date>2002-07-10</date>
     <title xml:lang="en">The news entries have been cleaned out</title>
     </file>
    </tkl-find>
      

Please note that tkl-find, like the other functions, pre-process their results so that any elements marked with xml:lang attributes not matching the current language are filtered out. Under normal circumstances, the programmer should not have to worry about resource languages in his stylesheets.

Function: Checks for user read/write/create authorization. This handler only makes sense in an administration interface, i.e. where ?admin=1.

Synopsis: tkl-grant://?type=create&file=tkl_cwd/new_file.tkl

Result: In case, the user is authorized to perform the given action, the following XML structure is returned:

  <tkl-grant>
    <granted>1</granted>
  </tkl-grant>
      

Otherwise, false is returned, i.e.

  <tkl-grant>
    <granted>0</granted>
  </tkl-grant>
      

The parameters file and type are both mandatory. The file argument specifies at which object the authorization request is targeted, while type specifies the type of action. The type argument must be one of the following:

All paths are relative to the Keystone portal root.

Function: Send HTTP headers to the user interface.

Synopsis: This handler is called automatically by the Keystone system. Don't attempt to call it from your XSL stylesheets.

Result: This Keystone handler is intentionally born empty. When developing a Keystone portal, the programmer is encouraged to overwrite the tkl-header by something meaningful. Typically, one wants to exploit the fact that this handler is called before any output has been generated by the XSLT processor. Thus, for instance HTTP headers can be created here.

See also tkl-admin-header.

Function: Find the closest occurence of help.tkl.

Synopsis: tkl-help:

Result: This support function is in a state of development and in the future it may be out-phased in favour of a more generalized implementation. But for the time being, it looks in the current working directory for the presence of a help.tkl file. If there is no such file there, it goes one directory level back and looks there. It keeps doing this process, until it finds a help.tkl file or reaches the Keystone portal root.

If a help.tkl file was found, the following XML document is returned:

  <tkl-help>
    <file>../../help.tkl</file>
  </tkl-help>
      

where the content of the <file> tag is the relative path from the current working directory to the location of the help.tkl file.

Otherwise, the <file> tag is replaced by some error message.

Function: Support function for sending e-mails.

Synopsis: tkl-mail:?to=recipient@domain.org&subject=Subject text&message=Message body.

Result: The following mail is sent with the native system's mail transmission agent:

  To: recipient@domain.org
  Subject: Subject text

  Message body.
      

If the mail was sent successfully, the following XML is returned:

  <tkl-mail>
    <status>OK</status>
  </tkl-mail>
      

Otherwise, an error flag is raised:

  <tkl-mail>
    <error>error message</error>
  </tkl-mail>
      

Function: Returns a path of "breadcrumbs" to the root of the portal.

Synopsis: tkl-path:/?select=title

Example:

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <tkl-path>
  <step path='./../../../'>
  <title xml:lang="en">Bibliotheca</title>
  </step>
  <step path='./../'>
  <title xml:lang="en">Social Sciences</title>
  </step>
  <step path='./'>
  <title xml:lang="en">Law</title>
  </step>
  </tkl-path>
      

Tkl-path returns an XML representation of the path from a given document to the root of the portal. In the base portal Bibliotheca, in the file interface.xsl, in the template insert-path, is an example of the usage of this function. In the base portal, the function is used to create a clickable path on each side, as a navigational aid.

The function operate by examining all directories from the current directory up to the root. For all directories which contain an index.tkl file, it returns a <step> element with a path-attribute providing a relative path. The path is generally suitable for use as a relative URL in an HTML <A> tag.

Function: Searches a Z39.50 database

Synopsis: tkl-search://unix:/home/indexdata/html/tkl/db/socket?query=@attrset idxpath computer&start=1&syntax=xml&number=6

Example:

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <search>
  <start>1</start>
  <number>6</number>
  <server url="unix:/home/indexdata/html/tkl/db/socket" status="1">
  <hits>6</hits>
  <end>6</end>
  <record offset="1">
  <subject xmlns:idzebra="http://www.indexdata.dk/zebra/">
  <title xml:lang="en">Computer science</title>
  <idzebra:size>153</idzebra:size>
  <idzebra:localnumber>332</idzebra:localnumber>
  <idzebra:filename>links/30/05/index.tkl</idzebra:filename>
  </subject>
  </record>
  ...............
  <record offset="6">
  .......
  </record>
  </server>
  </search>
      

Tkl-search executes a search against the given Z39.50 server. The address of the server generally follows the Z39.50 URL format, even though the example aboce is not standard, but an INdex Data specific extension which allows the use of Unix filesystem sockets (Unix fomain sockets) instead of internet host addresses/port numbers. In the local search function of the base portal Bibliotheca, Unix domain sockets are used to avoid having to allocate a new TCP/IP port to every portal running on the same machine.

The parameters start, number, and syntax work as you would expect, and queries are given in the PQF format (described at http://www.indexdata.dk/yaz/doc/tools.php#AEN2265) or ISO CCL (XX add documentation for the configuration of CCL field mapping setup).

The results come back as shown above. In particular, the users start and number-parameters are repeated in the XML structure. In the <server> element (which may become repeatable if multi-target searching is introduced) is the number of hits, along with the highest record number returned. After this follows a number of tecord elements, each of which contains one retrieval record from the server.

In portals like the base portal Bibliotheca, the tkl-search function is used to search the portal's index, which are hosted by a Zebra server. Note that Zebra for each record returns the path of the record in the element <idzebra:filename>.

Function: Name a custom handler to be executed after XSLT processing and output has completed.

Synopsis: tkl-set-footer:handler-name:?parameters

Result: Returns an empty XML document. Has the side effect of executing the named custom handler AFTER the current stylesheet has completed. The most obvious use for this is to execute a PHP or Perl script after the main page HTML has been output. This script in turn may perform a time-consuming process, i.e. a search, and provide a dynamic update of the user's screen by emitting a series of Javascript commands which alter the document HTML contents.

Function: Provides access to procedure calls on remote systems via the SOAP protocol.

Synopsis: tkl-soap:/MyTestService.wsdl?tkl:fun=weirdFunction&Hello World

Example:

  <?xml version='1.0' ?>
  <env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
  <env:Header>
  <t:transaction
  xmlns:t="http://thirdparty.example.org/transaction"
  env:encodingStyle="http://example.com/encoding"
  env:mustUnderstand="true" >
  5
  </t:transaction>
  </env:Header>
  <env:Body>
  <m:reserveAndChargeResponse
  env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
  xmlns:rpc="http://www.w3.org/2001/12/soap-rpc"
  xmlns:m="http://travelcompany.example.org/">
  <rpc:result>m:status</rpc:result>
  <m:status>confirmed</m:status>
  <m:reference>FT35ZBQ</m:reference>
  <m:viewAt>
  http://travelcompany.example.org/reservations?code=FT35ZBQ
  </m:viewAt>
  </m:reserveAndChargeResponse>
  </env:Body>
  </env:Envelope>
      

Tkl-soap provides access to any SOAP-based, so-called web-service (or remote API) anywhere on the Internet. The parameters to the the function consist of a reference to a service definition file (WSDL), a function name, and a list of parameters. The parameters can be structured in a variety of ways, to enable the use of different types of remote function.

The WSDL file can be identified using a relative or portal-absolute path, or as an HTTP URL.

Different SOAP functions pose different requirements to the structure of their parameters. In the example here, concat() is used to construct an argument list soleley in order to increase readability. You can imagine that "$query" in the example is a parameter which has been supplied by the user (see above about accessing user-supplied parameters in XSLT stylesheets).

INSERT EXAMPLE FROM bibliotheca/soap/google/google.xsl

Parameters for the SOAP functions can also be named explicitly, for example:

tkl-soap:MyTestService.wsdl?tkl:fun=myFunction&alpha=1&beta=2

Some functions require structured data, for instance, the arguments

primitive=test&alpha.a=bob&alpha.b=bub

yields the structure:

primitive=>test, alpha=>{a=>bob, b=>bub}

Substructures can be anonymous, as in

.a=bob&.b=bub

which yields

{a=bob, b=>bub}

As a concrete example, Amazon.com can be searched like this:

     <xsl:variable name="result" select="document(concat(
     'tkl-soap:AmazonWebServices.wsdl?',
     'tkl:fun=KeywordSearchRequest',
     '&amp;.keyword=', $squery,
     '&amp;.page=2',
     '&amp;.mode=books',
     '&amp;.tag=webservices-20',
     '&amp;.type=lite',
     '&amp;.devtag=', token,
     '&amp;.format=xml',
     '&amp;.version=1.0'
     ))"/>
      

If debugging has been enabled (adding the parameter debug=1 to the URL line), both the SOAP request and response packages will be displayed so it is easy to determine if you have constructed the right parameters for a given web service.

Function: Connect to a MySQL database server and execute SQL instructions.

Synopsis I: tkl-sql:?type=connect&host=mysqlhost.mydomain.org&db=sqlbase

Synopsis II: tkl-sql:?type=exec&sql=SELECT * FROM xxxx WHERE yyyy=zzzz

Result: This Keystone handler sends an SQL query to the database specified and encode the returned records as XML.

Before any SQL instruction can be carried out, a database connection must be established. This is performed by calling

  tkl-sql:?type=connect&host=mysqlhost.mydomain.org&db=sqlbase
      

If you need to login as a specific user with password, simply add a &db_user=mysql_user&db_pwd=secret to the URI. A database connection has a global scope in the sense that you can only have one open connection at a time. If you attempt to open 2 connections, the last connection will overwrite the first. A connection request with type=connect does not return any meaningful XML. In the future, some kind of reporting should be returned, i.e. success/failure/diagnostics.

Assuming one have an open MySQL connection, any number of manipulations can be made during one HTTP session. You execute SQL instructions the following way:

  tkl-sql:?type=exec&sql=SELECT this FROM that WHERE xxxx
      

When type=exec, the returned XML should be interpreted as the matching records. The XML structure is the following:

  <sql hits="xx" affected="yy">
    <record>
      <field1>value1</field1>
      <field2>value2</field2>
        ...
	...
    </record>
    <record>
      <field1>value1</field1>
      <field2>value2</field2>
        ...
	...
    </record>
      ...
      ...
  </sql>
      

The attribute hits represents the number of matching records, which is only meaningful for SELECT SQL instructions. For INSERT and UPDATE instructions, the affected attribute will be set to the number of rows affected by the operation.

The XML encoding is crucial when non-XML data from an external database is converted into well-formed XML. Therefore, one needs to decide how to handle two aspects of this situation:

Function: Return the current time.

Synopsis: tkl-time:?format=xxx

Result: Returns the time as a raw string. The optional setting format specifies how the time should be formatted. Use the conversion specifiers given at the PHP manual pages.

Function: Filenaming support function for the admin interface.

Synopsis: tkl-unique:?format=xxxx&type=yyyy

Result: This support function is designed mostly for the admin interface. It returns information about how to name new files respecting the local schemes specified in directory.tkl. The type argument can be one of the settings allowed in the naming scheme field in directory.tkl: globallyUnique, fixedName and userProvided. The format setting is the format used when naming files according to the globallyUnique scheme. Use the reserved character % to mark where to put the unique file identifier, e.g. format=link-%.tkl.

The returned XML document has this form:

  <tkl-unique>
    <unique>link-12345678.tkl</unique>
    <exists>0</exists>
    <file_spec>0</file_spec>
  </tkl-unique>
      

When type=globallyUnique, the <unique> tag contains the unique filename based on the specified format and on some dynamically constructed unique ID. For type=fixed, the <exists> tag will be set to 1, if the fixed file already exists, otherwise it will be set to 0. Finally, if type=userProvided, the <file_spec> tag will be set to 1.

Warning: Don't overwrite this function unless you know exactly what you are doing!

Function: Get information about user currently logged into the admin interface.

Synopsis: tkl-user:

Result: Returns an XML document with information about the user currently logged into the admin interface. The structure of the XML is the following:

  <tkl-user>
    <login>user_login</login>
    <password>ff402ace53f370435</password>
    <name>Human Readable Name Of This User;/name>
    <email>user_login@domain.org</email>
    <usertype>administrator</usertype>
    <area>/</area>
    <area>/news</area>
    <pass_type>md5</pass_type>
  </tkl-user>
      

The <login> tag contains the user's unique ID used when logging in. The <password> is a representation of the password used when logging in. Since Keystone version 1.4.1 new passwords will automatically be stored as MD-5 checksums. To ensure backwards compatibility, the tag <pass_type> is introduced to provide information about the password type used. Currently, this can only be one of the types md5 or clear or empty/non-existent, the two latter having the same meaning. The <name> and <email> are self-explaining. The <usertype> can be one of the following:

Finally, we have the repeatable <area> tag. This is a list of home directories, where the user has write permissions in addition to the granted read permissions given by default.

Since this is an admin interface handler, please don't attempt to overwrite it, unless you know what you are doing!