Verwenden von ORDER-Hinweisen in PlannerUsing order hints in Planner

Objekte in Planner identifizieren ihre Sortierreihenfolge anhand von ORDER-Hinweisen.Objects in Planner identify their sort order by order hints. Die Werte von ORDER-Hinweisen sind Zeichenfolgen.The order hint values are strings. Die Clients können die Zeichenfolgen basierend auf dem Ordnungswert von darin enthaltenen Zeichen sortieren, um die Reihenfolge von Elementen zu identifizieren.The clients can sort the strings based on ordinal value of characters in them to identify the order of items. Die Zeichen werden ab dem Anfang der Zeichenfolge verglichen, bis ein Unterschied in den Ordnungswerten der Zeichen gefunden wird oder bis eine Zeichenfolge endet. In diesem Fall wird die kürzere Zeichenfolge vor der längeren sortiert.The characters are compared from the beginning of the string, until a difference is encountered in the ordinal values of characters, or one string ends, in which case the shorter string would be sorted before the longer. Die Werte können beliebige Zeichen zwischen den Ordnungszahlen 32 (Leerzeichen) und 126 enthalten (~).The values can contain any character between ordinals 32 (space) and 126 (~)

Als Beispiel würde ein Element mit dem ORDER-Hinweis a (Ordnungswert 97) vor einem anderen Element mit dem ORDER-Hinweis z (Ordnungswert 122) platziert werden.As an example, an item with order hint a (ordinal value 97) would be placed before another item with order hint z (ordinal value 122). Ein Element mit dem ORDER-Hinweis abc (Ordnungswerte 97, 98, 99) würde vor einem anderen Element mit dem ORDER-Hinweis abd (Ordnungswerte 97, 98, 100) platziert werden.An item with order hint abc (ordinal values 97, 98, 99), would be placed before another item with order hint abd (ordinal values 97, 98, 100). Ein Element mit dem ORDER-Hinweis a würde vor einem anderen Element mit dem ORDER-Hinweis ab platziert, da alle vorhandenen Zeichen identisch sind und a kürzer ist.An item with order hint a would be placed before another item with order hint ab since all existing characters are the same, and a is shorter.

Die Werte für alle ORDER-Hinweise werden vom Dienst berechnet.The values for all order hints are calculated by the service. Der Client kann die Reihenfolge von Elementen ändern, indem der ORDER-Hinweis für das Element angegeben wird, das zwischen zwei Elementen verschoben wurde, indem der ORDER-Hinweis auf den folgenden Wert festgelegt wird: <previous order hint> <next order hint>!, wobei <previous order hint> durch den ORDER-Hinweis des Elements ersetzt werden muss, das sich vor der neuen gewünschten Position befindet, und <next order hint> durch den ORDER-Hinweis des Elements ersetzt werden muss, das sich nach der neuen gewünschten Position befindet.The client can reorder items by specifying the order hint for the item that got moved between two items with by setting the order hint to the following value: <previous order hint> <next order hint>!, where <previous order hint> is to be replaced by the order hint of the item that comes before the new desired location, and <next order hint> is to be replaced by the order hint of the item that comes after the new desired location. Es gibt ein Leerzeichen zwischen den Werten dieser ORDER-Hinweise, und ! wird an den gesamten Wert angehängt.There is a space character between these order hint values, and the entire value is suffixed with !. Wenn eines der Elemente nicht vorhanden ist, sollte stattdessen eine leere Zeichenfolge verwendet werden.If either item isn't present, empty string should be used instead. Dieser Wert kann auch aus vorherigen Berechnungen zusammengestellt werden, und kann im Client verwendet werden, um Elemente genau wie vom Dienst zurückgegebene ORDER-Hinweise zu sortieren.This value can also be composed of previous calculations, and can be used in the client to sort items exactly like service returned order hints. Nachdem der Client diese Werte an eine Aktualisierung gesendet hat, berechnet der Dienst einen kurzen Wert, der an der gewünschten Position sortiert wird.Once the client sends these values in an update, the service will calculate a short value that sorts in the desired location.

Bitte beachten Sie, dass in den folgenden Beispielen die tatsächlichen Werte der ORDER- Hinweise aus Gründen der Übersichtlichkeit in einfache Anführungszeichen (') eingeschlossen sind, diese sind jedoch nicht Bestandteil der Daten und dürfen nicht an den Dienst gesendet werden.Please note that in the following examples the actual order hint values are surrounded in single quote characters (') for clarity, however these are not part of the data, and must not be sent to the service.

Sehen Sie sich als Beispiel die folgende Liste sortierter ORDER-Hinweise an:As an example, consider the following list of sorted order hints:

  1. Element 1 (ORDER-Hinweis: '5637')Item 1 (Order Hint: '5637')
  2. Element 2 (ORDER-Hinweis: 'adhg')Item 2 (Order Hint: 'adhg')

Durch Platzieren eines Elements 3 vor Element 1, anschließendes Platzieren von Element 4 zwischen Element 1 und Element 2 und anschließendes Platzieren von Element 5 nach Element 2 würden die folgenden ORDER-Hinweise auf dem Client erstellt.Placing an Item 3 before Item 1, then placing item 4 between Item 1 and Item 2, and then placing item 5 after Item 2, would create the following order hints on the client.

  1. Element 3 (ORDER-Hinweis: ' 5637!')Item 3 (Order Hint: ' 5637!')
  2. Element 1 (ORDER-Hinweis: '5637')Item 1 (Order Hint: '5637')
  3. Element 4 (ORDER-Hinweis: '5637 adhg!')Item 4 (Order Hint: '5637 adhg!')
  4. Element 2 (ORDER-Hinweis: 'adhg')Item 2 (Order Hint: 'adhg')
  5. Element 5 (ORDER-Hinweis: 'adhg !')Item 5 (Order Hint: 'adhg !')

Durch Verschieben von Element 1 an das Ende der Liste würde Folgendes generiert:Then, moving item 1 to the end of the list would generate:

  1. Element 3 (ORDER-Hinweis: ' 5637!')Item 3 (Order Hint: ' 5637!')
  2. Element 4 (ORDER-Hinweis: '5637 adhg!')Item 4 (Order Hint: '5637 adhg!')
  3. Element 2 (ORDER-Hinweis: 'adhg')Item 2 (Order Hint: 'adhg')
  4. Element 5 (ORDER-Hinweis: 'adhg !')Item 5 (Order Hint: 'adhg !')
  5. Element 1 (ORDER-Hinweis: 'adhg ! !')Item 1 (Order Hint: 'adhg ! !')

Durch Verschieben von Element 5 zwischen Element 3 und Element 4 würde schließlich Folgendes generiert:Finally moving Item 5 between Item 3 and Item 4 would generate:

  1. Element 3 (ORDER-Hinweis: ' 5637!')Item 3 (Order Hint: ' 5637!')
  2. Element 5 (ORDER-Hinweis: ' 5637! 5637 adhg!!')Item 5 (Order Hint: ' 5637! 5637 adhg!!')
  3. Element 4 (ORDER-Hinweis: '5637 adhg!')Item 4 (Order Hint: '5637 adhg!')
  4. Element 2 (ORDER-Hinweis: 'adhg')Item 2 (Order Hint: 'adhg')
  5. Element 1 (ORDER-Hinweis: 'adhg ! !')Item 1 (Order Hint: 'adhg ! !')

Nachdem diese Änderungen an ORDER-Hinweisen an den Dienst in Patch-Anforderungen gesendet wurden, berechnet der Dienst die echten Werte, die die vom Client beabsichtigte Reihenfolge beibehalten.Once these changes to order hint values are sent to the service in patch requests, the service will calculate proper values that keep the order intended by the client. Der Client kann die Werte direkt abrufen, wenn die Einstellung return=representation in den PATCH-Anforderungen angegeben wird.The client can obtain the values immediate if return=representation preference is specified in the PATCH requests. Die Werte für die oben genannten Fall sehen in etwa wie folgt aus (die tatsächlichen Werte können anders lauten).The values for the case above may look like the following (the actual values may differ).

  1. Element 3 (ORDER-Hinweis: '432b')Item 3 (Order Hint: '432b')
  2. Element 5 (ORDER-Hinweis: '6F"#')Item 5 (Order Hint: '6F"#')
  3. Element 4 (ORDER-Hinweis: '7A$6')Item 4 (Order Hint: '7A$6')
  4. Element 2 (ORDER-Hinweis: 'adhg')Item 2 (Order Hint: 'adhg')
  5. Element 1 (ORDER-Hinweis: 'de5%')Item 1 (Order Hint: 'de5%')

ORDER-Hinweise können für das Erstellen des ersten Elements in der Liste als ! angegeben werden, da in diesem Fall weder ein vorheriges noch ein nächstes Element vorhanden ist, dies ist jedoch nicht erforderlich, da der Dienst Werte für alle ORDER-Hinweise für Elemente automatisch generiert, wenn diese während der Erstellung des Elements nicht angegeben werden.Order Hints can be specified for creating the first item in the list as !, since neither a previous or a next item exists in that case, however this is unnecessary, as the service will auto-generate values for all order hint values on items if they are not specified during creation of the item. Im folgenden Beispiel werden die ORDER-Hinweise veranschaulicht, die verwendet werden sollten, wenn Element in einer zuvor leeren Liste platziert werden.Following example illustrates the order hints should be used when placing items in a previously empty list. Fügen Sie das erste Element hinzu:Add the first item:

  1. Element 1 (ORDER-Hinweis: ' !')Item 1 (Order Hint: ' !')

Fügen Sie das zweite Elemente am Anfang hinzu:Add the second item to top:

  1. Element 2 (ORDER-Hinweis: ' !!')Item 2 (Order Hint: ' !!')
  2. Element 1 (ORDER-Hinweis: ' !')Item 1 (Order Hint: ' !')

Fügen Sie das dritte Element am Ende hinzu:Add the third item to bottom:

  1. Element 2 (ORDER-Hinweis: ' !!')Item 2 (Order Hint: ' !!')
  2. Element 1 (ORDER-Hinweis: ' !')Item 1 (Order Hint: ' !')
  3. Element 3 (ORDER-Hinweis: ' ! !')Item 3 (Order Hint: ' ! !')