Skip to content

Writing your own debate format XML file

Debatekeeper can time according to any format you like—not just the styles that come built in to the app.

Note: This page details the specification for schema version 2.0, which was released in app version 1.0 on 4 July 2013.

You can specify your own debate format for Debatekeeper to use.  Debate formats are written in XML, according to the specifications on this page.

You can’t edit or create debate formats from within the Debatekeeper app.  You need to write an XML file on your computer, and load it into your phone (e.g. via USB).  In future releases I intend to implement a mechanism to easily share custom formats between phones, but not a means of editing them yourself on your phone unless people ask for that feature.

The easiest approach is just to look at examples in the assets/formats folder on github here, and copy a style that is similar to the one you want to write. The files are quite self-explanatory, though a full specification is below on this page.

Note: In the user interface we call it a “debate style”, and in the source code we call it a “debate format”.  On this page I use the terms interchangeably.

Where to put the file

You should create a directory called debatekeeper on (the root directory of) your phone, and place the XML file in there. It must have the file extension .xml.  If you give your file the same name as one of the built-in styles, then your custom file will override the built-in style. Otherwise, Debatekeeper will just add it to the list.

The easiest way to do this is with a USB cable and your computer. But you could also e-mail it to yourself or load it in through cloud storage like Dropbox or Google Drive, so long as you can find a way to save it to the “debatekeeper” directory.

Want to contribute your debate format to the official release?

I don’t know about all the different debate styles in the world, so I (and many users, I’m sure) would be grateful to people who can help me include more.  Instructions for contributing debate formats are on the github repository for this app here.

Converting schema 1.0 files

If you have a file you wrote in the schema 1.0 format, I encourage you to convert it to the new schema 2.0 format. If you have Python installed on your computer, you can use this script to convert any 1.0 file to a 2.0 file.

Why you should convert your file to 2.0:

  1. Schema 2.0 supports global period types, so that standard period colours are now consistent across all formats.
  2. If and when I do an iOS version, it won’t support schema 1.0 files.
  3. While there’s backwards support for 1.0 files now, I will eventually drop this from the Android app.

What goes in the XML file

Note: Element names and attribute names are case-sensitive. All are in lower case. Mind the hyphens—they’re important too!

Root element

<debate-format schema-version="2.0">...</debate-format>

This is the root element of the XML file. Everything goes between these tags.

  • schema-version is the version number of the schema this file uses. The current version is 2.0.

When Debatekeeper sees a file that is newer than the app version supports, the user is prompted to upgrade the app. However, this unfortunately doesn’t work with the upgrade to 2.0 because I also changed the root element name, so app versions 0.10 and earlier will just ignore schema 2.0 files. You should advise users of your file to upgrade to the latest version.

Name of debate style

<name>...</name>

Write the name of the debate style here, e.g. “British Parliamentary”.

Information section

<info>
<region>...</region>
<level>...</level>
<used-at>...</used-at>
<description>...</description>
</info>

The information between these tags is displayed in the debate styles list. There are four sub-elements. The text in them can be anything, but obviously you should make the information useful.

  • <region>...</region>
    The geographic region(s) where this style is used, for example, “Australasia”, “United States”. You can have multiple <region> elements to describe a region each; the app will display all of them. But the regions should be mutually exclusive; for example, if your region is “Australasia”, users are probably smart enough to realise it’s also used in Australia, New Zealand, Korea and Singapore.
  • <level>...</level>
    The level(s) at which this style is used. I can only think of two: “University” and “School”. You can have multiple <level> elements to describe a level each; the app will display all of them.
  • <used-at>...</used-at>
    The major tournament(s) at which this style is used. You can have multiple <used-at> elements to describe a tournament each. It’s best to limit this to major tournaments, otherwise it’ll display a really long list.
  • <description>...</description>
    A very short description of the style, no more than about a dozen words. You should basically just include speech times and key features like whether POIs are allowed, similarly to the default styles. Don’t make it too long; you don’t want it to clutter the styles screen!

Custom period types

This is optional, and is needed only if the built-in period types aren’t enough for your format.

<period-types>...</period-types>
All custom <period-type> elements, if any, go between these tags.

<period-type ref="reference" pois-allowed="true">
<name>...</name>
<display>...</display>
<default-bgcolor>...</default-bgcolor>
</period-type>

Use one of these elements for each custom period type you need to define. The <period-type> element has two attributes and three sub-elements.

  • ref="reference"
    A unique reference that is used by <speech-type> elements to refer to this period. This name should be globally unique, as future releases may give users the ability to customise background colours. To ensure global uniqueness, I recommend prefixing references with the name of the file, e.g. easters.moot. If you use the same period in two or more files, then you can give them the same name. (This doesn’t really matter now, but in future Debatekeeper will treat them as the same type for user customisation purposes.) However, you must still define a custom period type in each file in which it is used.
  • pois-allowed="true"
    Set this to true if points of information are allowed in this period type. Omit or set to false if not.
  • <name>...</name>
    A human-readable name for your period type. This isn’t currently used, but it’s still mandatory. In the future it may be used to allow users to customise period type colours themselves.
  • <display>...</display>
    The phrase that gets displayed on the screen during periods of this type. If blank, nothing is displayed. If omitted, whatever was written there in the previous period stays there. (Note that blank and omitted are not the same thing.)
  • <default-bgcolor>...</default-bgcolor>
    The background colour used during periods of this type. Must be in HTML colour code format, i.e. #rrggbb where each two digits is a hexadecimal value for red, green and blue respectively.
    Note: Background colours in schema 2.0 are always opaque—the alpha value is not used.

Preparation time

Use these elements to specify how much preparation time is allowed in a style. You can use either of these two elements. For debates that don’t have limited preparation time (e.g. American Parliamentary, Canadian Parliamentary), you should omit both these elements.

<prep-time length="15:00" />
Use this element when preparation time is just a single amount of time. Most styles will use this element. The user’s prep time bells (as customised in Menu > Settings > Prep time bells) will apply.

<prep-time-controlled length="15:00" first-period="something">
<bell .../>
<bell .../>
</preptime-controlled>

Use this element when the preparation time is controlled by the chair. The only style I know of where this is the case is the Easters style in New Zealand. If you use this, you should populate the element with <bell> elements, just like a <speech-type> (see below).

Definitions of speech types

<speech-type ref="something" length="7:00" first-period="firstmin">;
<bell .../>
<bell .../>
</speech-type>

This element defines a type of speech.  You should create a speech type for each type of speech that has different bell times.  For example, the Australs format has two types of speeches: “substantive” and “reply”.  This element has three attributes and one or more <bell> elements.

Every speech type must have at least a <bell> element that is at the finish time of the speech.  You can either use time="finish", or just set the bell time to the same as the speech type length.  If you don’t, the app will show an annoying warning message and default to two bells.  This is by design: debate format XML file authors should be explicit.  If you don’t want to hear a bell, put number="0" in the <bell> element.

  • ref is a reference for the speech.  Its primary purpose is to give the <speech> element a means of referencing this type.  It is only shown in the “More” dialogue box in the debate styles list.  If the style only has one speech type (e.g. British Parliamentary), I recommend using “all”.
  • length is the length of this speech, either in m:ss format or as a single number of seconds.
  • first-period, optional but recommended, is the reference of period type that this speech type should use at the beginning of the speech.

<bell time="6:00" number="1" next-period="warning" />

This element defines a bell.  The time attribute is mandatory.  All others are optional.

  • time is the time of the bell, either in m:ss format or as a single number of seconds.  If this is in a speechtype, it can also be “finish“, which will put the bell at the finish time of the speech (i.e. the same time as the length attribute of the enclosing speech type).
  • number is how many bells to ring.  This is normally 1 for warning bells and 2 for finish bells.  It can be 0, in which case the bell doesn’t sound (you might want this to change periods without an audible bell).
  • next-period is the reference of the period that should apply straight after this bell. This can be either a built-in period type or a custom period type (specified by its reference).

Built-in period types

The built-in period types are:

  • normal, which is a black background.
  • pois-allowed, which is a green background with points of information allowed.
  • warning, which is an orange background and should be used after a warning bell is rung.
  • overtime, which is a red background and should be (explicitly) used after the finish bell is rung. Note that Debatekeeper does not use this period automatically for finish bells; it does, however, colour the time text light red when in overtime regardless of the active period type.

The built-in period types are specified in an XML file in the source, if you want to see what they look like. If these aren’t enough for you, you can always add your own custom period types.

Listing the speeches

<speeches>...</speeches>

All speeches go between these two tags.

<speech type="substantive" >
<name>...</name>
</speech>

There should be one of these elements for each speech.  Both the type attribute and the <name> element are mandatory.

  • <name>...</name> is the human-readable name of the speech, for example, “1st Affirmative”, “Leader of the Opposition’s Rebuttal”
  • type is the reference of the speech-type of this speech
Follow

Get every new post delivered to your Inbox.

Join 1,471 other followers

%d bloggers like this: