TU BRAUNSCHWEIG
| Carl-Friedrich-Gauß-Faculty | Computer Science
Informatikzentrum

XXHTML Documentation

Author Frank Steinberg
Keywords XXHTML XSL Tags Elements Magic

General Information

[[ TODO: galleries and iphoto, lists and registrations, information on user login, how to validate XML files, rooms, calendars/schedules in course files, show and edit by schema, gpx/kml, inventory/hardware/software, issues, news, matches/bets, rss/atom feeds, svn and trac, ... ]]

The IBR web server is different from ordinary web servers or content management systems. If you intend to write or edit any content on the web server, it is helpful to understand a few concepts:

  • Most content is stored in XML files. You should be familiar with XML to some degree. Most important: "XML files" that contain syntactical errors (e.g. non-nesting tags, missing preamble, non-matching "<" and ">" characters, illegally quoted attribute values, umlauts encoded differently from the encoding given the preamble, etc.) are not XML files, and thus they are completely ignored. Furthermore, almost all XML files are based on XML Schema definitions ("xsd"), which means their content and structure has to be based on a given formal grammar. If it is not, the document is "not valid". The expected rendering of data can only be guaranteed for valid documents. You can check a documents validity with a validating parser, e.g. "xmlvalidate".
  • Web browsers should always request HTML files by URLs ending in ".html". The server first tries to serve a corresponding file. Only if this file does not exist, the server looks up an according file with the extension ".xml" and processes it by applying the given XSL transformations.
  • There are basically two types of XML files:
    • Documents. Their top-level element is "html" from the XXHTML namespace. XXHTML is a superset of XHTML. So their content is more or less identical to XHTML but is also allows a few extensions which make life easier.
    • Data. Data XML files contain a structured "record". Usually there is one record per file, but it can be structured so that a sub-element may appear multiple times. Data XML files are based on a given XML Schema definition. Examples are: courses, users, theses, projects, bibitems, news articles, knowledge base articles, etc.
    Data files can be referenced in document files (or in other data files), so that their content or parts of their content is re-used. The basic idea is to avoid redundancy. E.g., a specific lecture is described in only one place: an XML data file which conforms to the "course" schema. Parts of it can then be referenced at other places, e.g. in tables which list all courses of a given semester or in a link within a course announcement article. If things change over time or errors have to be fixed, they have to be changed only at one place.
  • All documents and data is stored in usual files on a usual filesystem. There is no magic database. An XML indexing and search daemon runs the background and cares about all changes to XML files. This means you can use any ordinary editor, file manager or UNIX commands to edit and manage the documents and data. Access control is based on UNIX filesystem access control.

The content of XML documents is structured more or less as follows:


      <?xml version="1.0"?>
      <?xml-stylesheet type="text/xsl" href="/xsl/show.xsl"?>

      <html
        xmlns="http://www.ibr.cs.tu-bs.de/xsd/xxhtml"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.ibr.cs.tu-bs.de/xsd/xxhtml
                            http://www.ibr.cs.tu-bs.de/xsd/xxhtml.xsd">

	<head>
	  <title lang="de">Beispiel</title>
	  <title lang="en">Example</title>
	</head>
  
	<body>
	  <p>
	    ...
	  </p>
	</body>
      </html>
    

In combination with some default CSS definitions, the resulting web pages appear in a consistent design based on less redundant and thus more consistent XML files than with usual handcrafted HTML documents. Some abilities built into the supplied stylesheets take also care of consistent web page menus, bi-language support, time or user based filtering, etc.

Multi-Language Support

In some cases it might be useful to put additional effort in your documents to supply it in multiple languages, mainly in german and in english. This can be done within one file, so that it easy for the author to keep a consistent structure for both languages. You just have to add "lang" attributes to those elements, which should appear only in a given language. Elements without a "lang" attribute appear in any language. See the example above, which contains a title in two languages, while the rest of the document is not multi-langual. If you use multi-language support, you should always supply an english variant (lang="en"), since this is the fallback language for any client language which is not supported by your document.

Time-based Filtering

Most (but not all) elements may contain the attributes "start" and/or "end", which allow to supply a starting or ending point in time, when this element (and its content) shall be rendered. This might be useful for course registration forms, special announcements, etc. The timestamps have to be given ISO format (yyyy-mm-ddThh:mm:ss).


      <p start="2005-07-20T00:00:00" end="2005-07-20T23:59:00">
      Dieser Absatz soll nur am 20.07.2005 sichtbar sein!
      </p>
    

User-based Filtering

Most (but not all) elements may contain the attributes "user" or "group", so that their content is only rendered if the client user has logged in and matches the given username or is a member of the given group. The special case user="*" means that any authenticated user can see the content, but not an anonymous client.

Symbol Pictures

With the "new" web layout as of 2011 each page has a wide symbolic picture on its top. By default it is a zoomed photo of our building. Alternatively, you may choose another picture from the TU "Medien-DB" by adding something like this to the head of the document:

      <meta name="symbolpic" content="buecher-01.jpg"/>
    

More Help

As long as more information is missing at this place, please contact Frank in case of any questions.

Special anchors (<a ...>, not Schema-specific)

<a class="mail"/>

Generates an anchor (<a ...>) to an email address given by the href attribute (either with or without the mailto: prefix). If the text content of the element is empty, the plain email address will be used as the visible content of the anchor.

<a class="man" sect="x"/>

Generates an anchor (<a ...>) to a man page named by the text content of the <a> element and optionally detailed to the section given by the sect attribute.

<a class="kb"/>

Generates an anchor (<a ...>) to a knowledge base article given by the idref attribute.

<a class="room" idref="xxx"/>

Generates an anchor (<a ...>) to a given room. As of September 2007 only rooms on the first and second floor of the computer science building which belong the IBR are available this way. They have to be identified by a three-digit number through the idref attribute. If the element is empty, a default label will be generated, e.g. "Room 131". Alternatively, an explicit label can be given as a contained text node. The generated link points to a page which shows a floor map where the given room is marked.

Special <div> and <span> sections (not Schema-specific)

<span class="title"/>

Generates a <span> section containing the document's title in the currently chosen language. On pages that shall contain a headline, it is suggested to specify a title in <head> and reference it by this element within a <h1> element at the beginning of the <body>:


        ...
        <head>
          <title lang="de">Beispiel</title>
          <title lang="en">Example</title>
        </head>
        <body>
          <h1><span class="title"/></h1>
          ...
    

<div class="qrcode"/>

Generates a <div> section containing a QR code image of the current page URL or of the div's content.

<div class="now"/>

Generates a <div> section containing the current date and time in ISO format.

<div class="material" href="xxx" />

Generates a <div> section containing a table of (course) material, which is specified in the material document given by the href attribute. Such a table may list course slides, recorded audio and movie files of lectures, exercises and solutions. It may also contain links to automatically generated podcasts of different media types. The material document has a complex structure based on a schema. It controls the way in which the table is rendered, including access control, so that the material might be accessible to anonymous users or not. See the material.xsd schema and other already existing usages of this mechanism for more details.

The user has to supply the media in a source subdirectory, and maintain the material.xml file. Subsequent calls to xcmmaterial will create or update the material subdirectory and its content which is referenced by the generated HTML table and the optional podcasts.

<div class="result" href="result.xml"/>

Generates a form allowing a user to query results of an exam. The results have to be stored in a result.xml file and the href attribute has to refer to that file. Note that the file MUST be readable to the web server and SHOULD NOT be readable to anyone.

<div class="resultstats" href="result.xml"/>

Generates a <div> section containing the result statistics of an exam.

<div class="rooms" [idref="xxx"]/> (Query String Parameters: room, floor, building)

Generates a <div> section containing a floor map of a given builing and floor and optionally with a marked room. As of September 2007, only the building 4103 (Informatikzentrum) and the first and second floor with the rooms that belong to IBR are implemented. If a room number is identified either through an XSLT template parameter named room (passed from the web server via a query string parameter) or through the idref attribute, that room is marked on the map.

Special lists (<ul>, <ol>) and tables (<table>, <tr>)

The following forms of lists and tables can be used to render a dynamic set of items which conform to a given class (i.e., XML Schema). In any case, the items are specified either through the XPath expression given in a select attribute (it should usually be of the form CLASS:CLASS[...]), or by a search form with the same class, if the searchresult="true" attribute is present. In the latter case, the document must also contain this search form:


	<div>
	  <form class="search"/>
	</div>
    

Note that this functionality depends on the XML index daemon (xmlidxd) to be running and to be configured so that the contents of directories you expect can be found. Note also that the CLASS has to be known by xmlidxd in its configuration file.

As of September 2007, supported classes are: bibitem, transponder, hardware, event, project, thesis, course, user, issue, news. This might change over time.

<ul class="CLASS" [directory="dir"] [select="xxx"] [searchresult="true"] [sort="xxx" [order="ascending|descending"]]/>

Generates an unnumbered list (<ul>...) of items of a given CLASS. The following example lists all bibitems, that were authored or co-authored by the IBR user "strauss", sorted by the bibitems' sub-elements which specify the publication date. Note the two types of quoting characters (' and ").


      <ul class="bibitem" 
          select='//bibitem:bibitem[contains(bibitem:ibrauthors,"strauss")]'
	  sort='concat(document(@href)/bibitem:bibitem/bibitem:year,
	               document(@href)/bibitem:bibitem/bibitem:month)'
          order="descending">
      </ul>
    

<ol class="CLASS" [directory="dir"] [select="xxx"] [searchresult="true"] [sort="xxx" [order="ascending|descending"]]/>

Generates an ordered list (<ul>...) of items of a given CLASS. The following example shows an input form for a search pattern followed by an ordered list of search results. As long as no search string is given, the result list is filled with the search result given by the select attribute. The search is restricted to documents in the /bib subdirectory. Note the two types of quoting characters (' and ").


      <div>
        <form class="search"/>
      </div>
      <ol class="bibitem"
          directory="/bib"
	  searchresult="true"
	  select='//bibitem:bibitem[bibitem:loaned = "$HTTP_REMOTE_USER"]'
	  sort="concat(document(@href)/*/bibitem:year,
	               document(@href)/*/bibitem:month)"
          order="descending"/>
    

<div class="CLASS" [directory="dir"] [select="xxx"] [searchresult="true"] [sort="xxx" [order="ascending|descending"]]/>

Generates an list of div's of items of a given CLASS.

<table class="CLASS" [directory="dir"] [select="xxx"] [searchresult="true"] [sort="xxx" [order="ascending|descending"]]/>

Generates a table of items of a given CLASS. The following example lists all theses in a table, that were supervised by the IBR user "strauss". Note the two types of quoting characters (' and ").


      <table class="thesis" 
             directory="/theses/strauss" 
             select='//thesis:thesis[thesis:supervisor = "strauss"]'/>
    

<table class="generic"> ...

Generates a table that contains data from a given XML document. Rendered columns and the sorting order can be configured. The configuration is achieved through a containing <colgroup> element that specifies the XML document and the attribute used for sorting the rows, and through a number of containing <col> elements that specify the columns to be rendered, either subelement or attributes.

(This functionality might be changed soon.)


      <table class="generic">
	<colgroup href="list.xml" sort="name">
	  <col select="@date"/>
	  <col select="gender"/>
	  <col select="name"/>
	  <col select="firstname"/>
	  <col select="matrikel"/>
	  <col select="course"/>
	  <col select="comment"/>
	  <col select="semester"/>
	  <col select="email"/>
	</colgroup>
      </table>
    

The XML document has to have an arbitrary root element representing a list. On the second level an arbitrary number of elements represent the records that are rendered as table rows. Their attributes and their containing third-level elements can be rendered as the records' columnar cells which are selected and ordered by the cols.

<form class="search" href="xxx"/>

Generates a <form> for entering search patterns. Search results are rendered through other <table> elements on the same page, see above.

Currently, only one search form and result is supported on the same page.

<commment>...</commment>

If you want to include comments in the result XHTML document, you can use this element in the source XML document.

Users

<a class="user" idref="xxx"/>

Generates an anchor (<a ...>) to a user's home page or email address. The user has to be identified through the idref attribute giving a username. Depending on whether a <user> document in /users/xxx/index.xml exists and contains an <url>, a link to the web page or the email address of the form xxx@ibr.cs.tu-bs.de is created. Depending on whether the user document exists and contains a <name> the label contains the user's real name or the email address.

<a class="mail" idref="xxx"/>

Generates an anchor (<a ...>) to a user's email address. The user has to be identified through the idref attribute giving a username. Depending on whether a <user> document in /users/xxx/index.xml exists and contains an <url>, a link to the web page or the email address of the form xxx@ibr.cs.tu-bs.de is created. Depending on whether the user document exists and contains a <name> the label contains the user's real name or the email address.

<div class="user" idref="xxx"/>

Generates a <div> section containing personal information on the user identified through the idref attribute. Such a section should be included on top of each personal homepage. The information is taken from a user record managed my the IBR system administrators. If changes are required, please contact them.

<table class="user"> <tr idref="xxx"/> ...

Generates a table of users with a common set of columns (name, email, phone). The users are explicitly specified through tr elements with idref attributes containing the users' usernames.

<div class="users" ldapfilter="(ldapfilter)" />

Generates a formatted overview of users.

Courses

<a class="course" idref="xxx"/>

Generates an anchor (<a ...>) to a course page, labeled with the course title. The course has to be identified through the idref attribute. A concrete semester/term can be identified by an idref like "ss05/bsn". If you want to refer dynamically to the most recent instance of a course, it should be identified like "bsn". You can also use "./bsn" (note, this is different from "bsn"!). The according course document must exist at /courses/semester/course/index.xml.

<table class="course"> <tr idref="xxx"/> ...

Generates a table of courses with a common set of columns (course title, credit points, etc.). The courses are explicitly specified through tr elements with idref attributes containing the courses' identifiers.

Theses

<a class="thesis" idref="xxx"/>

Generates an anchor (<a ...>) to a thesis description. The thesis has to be identified through the idref attribute giving a thesis id in the form username/filename which reflects the path under docroot/theses without the .xml extension.

<table class="thesis"> <tr idref="xxx"/> ...

Generates a table of theses with a common set of columns. The theses are explicitly specified through tr elements with idref attributes containing the theses' identifiers as described above.

Projects

<a class="project" idref="xxx"/>

Generates an anchor (<a ...>) to a project page, labeled with the project's title. The project has to be identified through the idref attribute and have a <project> document in /projects/xxx.xml.

<table class="project"> <tr idref="xxx"/> ...

Generates a table of projects with a common set of columns (project name, short description). The projects are explicitly specified through tr elements with idref attributes containing the projects' identifiers.

Bibitems

The /bib directory contains several BibTeX files which are automatically converted to XML bibitems so that they can be referenced from any web page. Users only have to take care that the files are syntactically correct (BibTeX is a little delicate) and that BibTeX keys are unique over all files.

More detailed information on how bibitems are managed can be found in another article.

<li class="bibitem" idref="xxx"/> or <ul class="bibitem"> <li idref="xxx"/> ...

Generates a list item (in an unnumbered or ordered list) representing a bibitem which has to be identified through the idref attribute containing the bibitem's BibTeX key.

<span class="bibitemcosts" [select="xxx" | searchresult="true"] />

Generates a real number representing the sum of the costs of all bibitems from the given select expression or the current search result. This functionally is very specific and probably only useful for the webmaster.

Issues (Knowledge Base Articles)

Articles in the knowledge base are stored as XML files from the "issue" namespace. There are no specific XXHTML elements related to such issues.


last changed 2009-08-24, 23:01 by Frank Steinberg
printemailtop