Tablix uses a XML formatted file to store timetable information. XML consists of tags, nested in each other. Each tag can have one or more properties and some tags can have text content in them. The top level tag, which should include all other tags, is called the root tag.
Note: The XML Document Type Definition document for the Tablix configuration format can be found on-line.
Tip: The most common mistake new users make is to put
<restriction>tags in wrong places in the XML file. Tablix will in most cases silently ignore unknown extra tags in the XML file and will therefore also ignore any<restriction>tags that are not in the right places.If you are not sure if your XML syntax is correct or if Tablix seems to be ignoring some of your
<restriction>tags, you can use the xmllint utility that comes with libxml2 to check your XML file against the Document Type Definition. Type xmllint --valid --noout your-config-file.xml at the command line. If it returns no error messages then the XML is most likely syntactically correct.
Tablix configuration consists of several parts. They are delimited by top
level tags. The root tag should be named <ttm>. The top level tag must also contain the version property that contains version number of the format. This version number should be "0.2.0"
for use with Tablix kernels versions 0.2.1 and later.
Note: All strings (resource names, restriction types, etc.) that appear in the XML file are case sensitive. You can have for example three different resources in the configuration file with names "ALPHA", "Alpha" and "alpha".
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE ttm PUBLIC "-//Tablix//DTD TTM 0.2.0//EN" "http://www.tablix.org/releases/dtd/tablix2r1.dtd">
<ttm version="0.2.0">
.
.
.
</ttm>
First part of the configuration is optional. You can include the information about the author of the timetable, the address of the institution and the title of the timetable under the <info> tag.
<info>
<title>Example high school</title>
<address>Somewhere</address>
<author>Someone</author>
</info>
This information will be printed on the top of the timetable when exported into the HTML format.
Next part of the configuration defines the modules that will be used by Tablix. This part and all subsequent parts of the configuration are mandatory.
Modules are listed with <module> tags inside the <modules> tag.
<modules>
<module name="sametime.so" weight="200" mandatory="yes"/>
.
.
.
<modules>
Some modules may accept module options. They can be specified with <option> tags. Each module option has a name (specified with the name property) and a value.
<modules>
<module name="holes.so" weight="6" mandatory="no">
<option name="resourcetype">class</option>
</module>
.
.
.
</modules>
Note: With the selection of modules you choose the group of errors for which Tablix will try to optimize your timetable. With weight values you can tell Tablix which errors are more important than others.
Note: Each module can define one or more restriction types. See the Modules reference manual for more information on which module defines which restrictions. Tablix will ignore any unknown restriction types in the configuration file. A warning is printed for each unknown restriction encountered if the verbosity level is set to 3 or higher (default is 2).
Tip: You can find working examples for all modules in the ttf/tests/ subdirectory. Each module included in the distribution has one or more test cases stored there. These test cases are used by the Tablix Testing Framework to automatically check if modules are working correctly. For now, you can treat these files as normal problem descriptions and ignore the extra Scheme code at the beginning.
All resources types that will be used in your timetable should be defined under the <resources> tag.
<resources>
<constant>
.
.
.
</constant>
<variable>
.
.
.
</variable>
</resources>
Constant resource types should be defined under the <constant> tag and variable resource types under the <variable> tag.
A resource type is defined with a <resourcetype> tag. Name of the type is specified inside a type property.
<constant>
<resourcetype type="teacher">
.
.
.
</resourcetype>
.
.
.
</constant>
Each resource type can contain one or more resources. A single resource is defined with a <resource> tag inside <resourcetype>. Each resource must have its name defined with a name property.
Note: Two resources of the same resource type can not have identical names.
<resourcetype type="teacher">
<resource name="Prof. SJK 1"/>
.
.
.
</resourcetype>
If some modules have defined resource restrictions for the defined resource types, then you can apply a resource restriction to a resource with a <restriction> tag.
<resourcetype type="class">
<resource name="3 B">
<restriction type="conflicts-with">3 MA-FIZ</restriction>
</resource>
.
.
.
</resourcetype>
Each restriction has a type (specified with the type property) and a value.
A row of resources can be defined with a <linear> tag. This is a simple way to defined a larger number of identical resources.
<resourcetype type="room">
<linear name="K#" from="1" to="5">
<restriction type="capability">Kemija</restriction>
</linear>
.
.
.
</resourcetype>
You must assign a name to the row of resources with the name property. The character "#" in the name will be replaced by an integer ranging from the number in the from property to the number in the to property.
Resource restrictions can be applied in the same way as with the <resource> tag.
The example above will define 5 resources with names from K1 to K5. All resources will have restriction "capability" applied.
A matrix of resources is defined in a similar way with the <matrix> tag.
<resourcetype type="time">
<matrix width="5" height="8"/>
</resourcetype>
The width and height properties define the dimensions of the matrix. You can not define a name for the resources in the matrix. All resources will be named "X Y", where X is the X coordinate of the resource in the matrix and Y is the Y coordinate.
Resource restrictions can be applied to a resource matrix in the same way as with the <resource> tag.
Events must be defined with <event> tags under the <events> tag.
<events>
<event name="SJK" repeats="4">
.
.
.
</event>
.
.
.
</events>
Each event has a name defined with the name. Two different events can share the same name, however this practice is not recommended since it may confuse some modules.
The repeats property defines how many times this event is repeated. For example if an event has repeats equal to 4, this has the same effect as if the the <event> tag defining this event would be copied four times in the configuration file.
Note: The
repeatshas no other hidden effects. It exists only for convenience when writing XML files by hand. This means that the following two examples are identical as far as Tablix is concerned. In fact if you look at the XML file with the problem solution you will see that all<event>tags are expanded so that none haverepeatsgreater than 1.This example...
<event name="SJK" repeats="3"> . . . </event>...is identical to this one:
<event name="SJK" repeats="1"> . . . </event> <event name="SJK" repeats="1"> . . . </event> <event name="SJK" repeats="1"> . . . </event>
Resources that are used by an event are defined with the <resource> tags inside the <event> tag.
<event name="SJK" repeats="4">
<resource type="teacher" name="Prof. SJK 1"/>
<resource type="class" name="1 A"/>
</event>
<resource> tags must have type and name properties, defining resource type and name of the resource. It is mandatory to assign one resource of each constant resource type to each event. Optionally, you can also assign one resource of some or all variable resource types to some or all events. Such assignments will be used as hints by Tablix kernel. They may be used in the final solution if they will help to reduce the fitness value of the timetables.
Note: Please note that these hints are not equal to the "fixed tuples" in 0.1 branch. If you would like to permanently assign some variable resources to an event, you have to use a module that defines a restriction that implements this.
For example, to schedule an event at a fixed time, you can use the module fixedtime.so.
If some modules have defined event restrictions, then you can apply an event restriction to an event with a <restriction> tag inside the <event> tag.
<event name="KEM" repeats="2">
<resource type="teacher" name="Prof. KEM 2"/>
<resource type="class" name="1 B"/>
<restriction type="capability">Kemija</restriction>
</event>
As with resource restrictions each event restriction has a type (specified with the type property) and a value.