Permalink
Browse files

Added a little more about mt:Order limit and mt:OrderItem pin

Didn't add "You should probably just forget all about mt:OrderItem pin" regardless of how much I should
  • Loading branch information...
1 parent fde43eb commit b1ae8a35fb8a61a6540efb8d1817dfe843582735 Mark Paschal committed Feb 21, 2009
Showing with 18 additions and 10 deletions.
  1. +18 −10 README.txt
View
@@ -64,16 +64,17 @@ If set to `ascend`, reorders the content from first to last (that is, 1 to 9
and A to Z). Otherwise, the items are sorted in descending order (Z to A and 9
to 1).
-#### `limit` ####
-
-Specifies how many `mt:OrderItem`s to show. That is, after reordering all the
-`mt:OrderItem` tags, discard all but this many items.
-
#### `offset` ####
Specifies a number of `mt:OrderItem`s to skip. That is, after reordering all
the `mt:OrderItem` tags, discard this many items from the front of the list.
+#### `limit` ####
+
+Specifies how many `mt:OrderItem`s to show. That is, after reordering all the
+`mt:OrderItem` tags (and discarding items due to `offset`), keep only this
+many items from the front of the list.
+
#### `natural` ####
If set to `1`, sorting values that look like numbers will be sorted
@@ -87,9 +88,10 @@ if they're numbers, specify `natural="1"`.
#### `shuffle` ####
If set to `1`, reorder the items randomly instead of using the sorting values.
+
When using this attribute, you can safely omit the `natural`, `sort_order`,
and `by` attributes, and you need not set sorting values inside your
-`mt:OrderItem` tags.
+`mt:OrderItem` tags. `mt:OrderItem pin` attributes are still honored, however.
#### `by` ####
@@ -127,12 +129,18 @@ negative numbers: writing `mt:OrderItem pin="-1"` is almost like using the
If multiple `mt:OrderItem`s have the same `pin` value, those items will be
reordered based on their `order_by` values, then spliced into the full set of
-items at the specified `pin` point as a contiguous tranche.
+items at the specified `pin` point as a contiguous tranche. Pinned groups are
+inserted from left to right (`0` to `-1`), so groups with multiple items may
+overlap with groups pinned nearby. For example, if there are four items pinned
+at `0` and one item pinned at `1`, in the final reckoning three of the items
+pinned at `0` will appear *after* the item at `1`: by the time the item at `1`
+is finally pinned, the other items pinned at `0` have already become items #1,
+#2, and #3.
Pinned items are put in position *before* the `mt:Order` tag's `limit`
-attribute is considered. That is, if you are sorting 11 items, pin one to
-`-1` (last), and use `limit="10"` on the `mt:Order` tag, the pinned item will
-*not* be shown (it was the eleventh of ten items).
+attribute is considered. That is, if you order 11 items, pin one to `-1`
+(last), and use `limit="10"` on the `mt:Order` tag, the pinned item will *not*
+be shown (it was the eleventh of ten items).
### `mt:OrderHeader` ###

0 comments on commit b1ae8a3

Please sign in to comment.