npsobj list

Syntax

npsobj_list ::=

  <npsobj list = "name"
    [ sortkey1 = "sortKey1" 
      [ sortmodifier1 = sortModifier ]
      [ sortkey2 = "sortKey2"
        [ sortmodifier2 = sortModifier ]
        [ sortkey3 = "sortKey3"
          [ sortmodifier3 =  sortModifier ]]]]
    [ start = "startIndex" ]
    [ ( length = "length" ) | ( end = "end" ) ] 
    [ reverse = "" ] >
    content
  </npsobj>

sortModifier ::=
  "alpha" | 
  "numeric" | 
  "ascending" | 
  "descending" |
  "alpha ascending" | 
  "alpha descending" |
  "numeric ascending" | 
  "numeric descending"

Aufgabe

Die Anweisung wird häufig verwendet, um Inhaltsübersichten automatisch zu generieren. Sie erzeugt eine Liste von Datei- oder Linkkontexten, indem name ausgewertet wird. name steht hierbei für einen Bezeichner, der eine Kontextliste ergibt, beispielsweise toclist oder children. Als name kann auch der Name eines Linklistenfeldes oder einer Exportvariablen angegeben werden, der vorher eine Kontextliste zugewiesen wurde.

Für jedes Element in der Liste wird content genau einmal ausgewertet (siehe jedoch auch npsobj_break). Für die Auswertung von content wird der aktuelle Kontext temporär auf das jeweilige Listenelement gesetzt. Dadurch beziehen sich sämtliche Namen (beispielsweise Feldnamen) auf das aktuelle Listenelement, solange der Kontext innerhalb von content nicht gewechselt wird.

Sortierung der Liste

Die Kontextliste kann sortiert werden, indem die Werte sortKey1 der Kontexte verglichen werden. Sind zwei Werte gleich, so werden die Werte von sortKey2 herangezogen. Sind auch diese Werte gleich, wird die Reihenfolge der Kontexte anhand von sortKey3 bestimmt. Die Reihenfolge von Kontexten, bei denen alle drei Sortierschlüssel jeweils denselben Wert haben, ist nicht definiert. Ist sortkey1 nicht angegeben, so wird die Kontextliste nach den Sortierschlüsseln sortiert, die für den darüber liegenden Ordner angegeben wurden.

Mit dem Modifikator sortModifier kann man angeben, wie die Werte zweier Sortierschlüssel miteinander verglichen werden sollen. alpha sortiert nach Zeichenwert, numeric numerisch, d. h. die Zeichenfolge wird als Zahl interpretiert. ascending sortiert aufsteigend, descending absteigend. Jeweils ein Schlüsselwort der beiden Modifikatorpaare (alpha/numeric und ascending/descending) kann miteinander kombiniert werden (Beispiel: numeric descending). Der voreingestellte Sortiermodus ist alpha, die voreingestellte Sortierrichtung ascending. Die voreingestellte Modifikatorkombination ist also alpha ascending.

Auswahl von Listenelementen

Ist das Attribut start angegeben und hat startIndex einen Wert größer 0, so ist startIndex der Index des ersten zu berücksichtigenden Elements der Kontextliste. Das erste Element hat den Index 1. Hat startIndex einen Wert kleiner 0, so wird das erste zu berücksichtigende Element vom Ende der Kontextliste her ermittelt. Ist start gleich 0, so wird das Attribut ignoriert.

Mit dem Wert des Attributs length kann die Anzahl der Elemente in der Kontextliste festgelegt werden. Ist length gleich 0 (Voreinstellung), so werden die Elemente ab start bis zum Ende der Liste zurückgegeben. Dagegen bestimmt ein Wert größer 0 die maximale Anzahl der ab start zu liefernden Elemente. Ist length kleiner als 0, so bezeichnet start das letzte Element der Liste, die höchstens soviele Elemente hat, wie es der Absolutwert von length festlegt. Mit start="-1" und length="-2" erhält man also das vorletzte und das letzte Element der Liste.

Alternativ zu length kann das Attribut end angegeben werden. Ist end eine positive Zahl, so bezeichnet diese Zahl den Index des letzten zu berücksichtigenden Elements der ursprünglichen Liste. Das erste Element hat den Index 1. Ist end negativ, so werden vom Ende der Liste her so viele Elemente ausgespart wie der Absolutwert von end angibt.

Die Wirkung von start und length bzw. end zeigt die folgende Übersicht. Das durch start gewählte Element ist grün gefärbt.

Ausgewählte Elemente	start	length	end
	3	2
	5	-2
	-3	2
	-1	-3
	3		5
	2		-2
	-3		5
	-4		-1

Legende: Nicht ausgewähltes Element   Erstes ausgewähltes Element   Weiteres ausgewähltes Element

Ist das Attribut reverse angegeben, so wird die Reihenfolge der Elemente umgekehrt, nachdem sie gegebenenfalls sortiert wurden und bevor diese mit start und length bzw. end gekürzt werden.

Beispiel

<npsobj list="toclist" start="2" length="3" sortkey1="title" sortmodifier1="ascending">
  <!-- Dies wird für jedes Listenelement abgearbeitet -->
  <npsobj insertvalue="anchor" name="self">
    <npsobj insertvalue="var" name="title" /><br />
  </npsobj>
</npsobj>