Skip to content

Templating Documentation

Jump to bottom
Loris Sauter edited this page Jul 30, 2020 · 3 revisions

Templating Documentation

Terminology

CS108-PET's core are the six entities:

  • requirement
  • milestone
  • catalogue
  • progress
  • progress-summary
  • group

Those entites are represented as objects with respective properties on their own (e.g. requirement has a property name). Those properties are called fields. There are several types of fields:

  • Simple fields return text (or a number)
  • Entity fields return an entity (which thus has its own fields)
  • Subentity field's return type is equal to the one of the field of the sub entity
  • Parametrized fields do have a parameter
  • Conditional fields do have two parameters, the first one being rendered, when the field's value is true, the second one if the field's value is false
  • List fields render the complete list of what they stand for.

CS108-PET's templating language (PMTL) is built upon **expression*s, which address a certain field of an entity.

Syntax

The syntax of such expressions is as follow:

${<entity>.<simple-field>}
${<entity>.<entity-field>}
${<entity>.<subentity-field>.<field>}
${<entity>.<parametrized-field>[<param>]}
${<entity>.<conditional-field>[<condition-met>][<condition-missed>]}

Where <entity> stands for an entity, <X-field> for a field of type X, <param> for the accepted parameter and <condition-met> is what gets rendered if the conditional field meets its condition, while ` is the what gets rendered if the conditional field does ont meet its condition.

WARNING

As of version 0.4 PMTL does not support expressions as parameter (parametrized field parameter as well as conditional field parameters). Thus ${<entity>.<field>[${<entity>.<field>]} is not allowed.

As of version 0.4 PMTL does not support expressions with parametrized or conditional sub entity fields. Thus ${<entity>.<subentity-field>.<parametrized-field>[<param>]} is not allowed.

Templating

Templates for cs108pet are written in any language or format desired. The only requirement for templating files is the one, that they must be plain text. Probably the most common use case would be to either have a html or tex export. To achieve this, one must simple use that specified format within the template itself and combine it with RMTL expressions.

Scope

Within the scope of a template file, only certain entities are visible.

(The headers below refer to the template with that name, not to the entity!)

Requirement

Within the requirement template, the following entities are visible:

  • requirement

Milestone

Within the milestone template, the following entities are visible:

  • milestone

Catalogue

Within the catalogue template, the following entities are visible:

  • catalogue

Progress

Within the progress template, the following entities are visible:

  • progress
  • requirement

Progress-Summary / Group-Milestone

Within the progress-summary template, the following entities are visible:

  • groupMilestone
  • milestone

Group

Within the group template, the following entities are visible:

  • group
  • catalogue

Entities

The field names mostly are self-explanatory or match the documentation of ReqMan core. Fields have case sensitive names.

(The headers below refer to the entity with that name, not the template)

Requirement

The entity requirement has the following fields:

  • name (Type: Simple)
  • excerpt (Type: Simple)
  • description (Type: Simple)
  • maxPoints (Type: Simple)
  • minMS (Type: Subentity: milestone)
  • predecessorNames (Type: List, Simple)
  • binary (Type: Conditional)
  • mandatory (Type: Conditional)
  • malus (Type: Conditional)
  • meta (Type: Parametrized) Parameter: key of meta data property.
  • type (Type: Simple)
  • category (type: Simple)

Milestone

The entity milestone has the folliwng fields:

  • name (Type: Simple)
  • date (Type: Simple) Pre-formatted with java.text.SimpleDateFormat("dd.MM.YYYY")
  • ordinal (Type: Simple)
  • sumMax (Type: Simple)
  • dateFormatted (Type: Parametrized) Parameter: Format string for java.text.SimpleDateFormat

Catalogue

The entity catalogue has the following fields:

  • name (Type: Simple)
  • description (Type: Simple)
  • lecture (Type: Simple)
  • semester (type: Simple)
  • requirements (Type: List, Entity: requirement)
  • milestones (Type: List, Entity: milestone)
  • sumTotal (Type: Simple)
  • sumMS (Type: Parametrized) Parameter: The ordinal of the milestone
  • milestoneName (type: Parametrized) Parameter: The ordinal of the milestone

Progress

The entity progress has the following fields:

  • points (Type: Simple)
  • hasPoints (Type: Conditional)

Group-Milestone

The entity groupMilestone has the following fields:

  • name (Type: Simple) same as ${milestone.name}
  • progressList (Type: List, Entity: progress)
  • sum (Type: Simple)
  • percentage (Type: Simple)
  • comment (Type: Simple)

Group

The entity group has the following fields:

  • name (Type: Simple)
  • project (Type: Simple)
  • milestones (Type: List, Entity: groupMilestone)
  • sumMS (Type: Parametrized) Parameter: The ordinal of the milestone
  • sumTotal (Type: Simple)
Clone this wiki locally