Skip to content

Commit

Permalink
Document dictionary tag
Browse files Browse the repository at this point in the history
Closes #1474.
  • Loading branch information
duncanmcclean committed Oct 14, 2024
1 parent d33aebb commit cf02bbc
Showing 1 changed file with 164 additions and 0 deletions.
164 changes: 164 additions & 0 deletions content/collections/tags/dictionary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
---
title: Dictionary
intro: Allows you to loop through options from a Dictionary.
description: Allows you to loop through options from a Dictionary.
id: 603bb573-5ebf-4851-935e-713f1caaa431
parameters:
-
name: handle
type: string
description: 'The handle of the dictionary you wish to get options from.'
required: true
-
name: sort
type: string
description: 'Sort options by field name (or `random`). You may pipe-separate multiple fields for sub-sorting and specify sort direction of each field using a colon. For example, `sort="name"` or `sort="date:asc|name:desc"` to sort by date then by name.'
required: false
-
name: limit
type: integer
description: 'Limit the total results returned.'
required: false
-
name: filter|query_scope
type: string
description: "Apply a custom [query scope](https://statamic.dev/extending/query-scopes-and-filters) You should specify the query scope's handle, which is usually the name of the class in snake case. For example: `MyAwesomeScope` would be `my_awesome_scope`."
required: false
-
name: offset
type: integer
description: 'Skip a specified number of results.'
required: false
-
name: paginate
type: 'boolean|int *false*'
description: 'Specify whether your options should be paginated. You can pass `true` and also use the `limit` param, or just pass the limit directly in here.'
required: false
-
name: page_name
type: 'string *page*'
description: 'The query string variable used to store the page number (ie. `?page=`).'
required: false
-
name: on_each_side
type: 'int *3*'
description: When using pagination, this specifies the max number of links each side of the current page. The minimum value is `1`.
-
name: as
type: string
description: 'Alias your options into a new variable loop.'
required: false
-
name: scope
type: string
description: 'Scope your options with a variable prefix.'
required: false
-
name: '*'
type: string
description: 'Any additional parameters will be set as config options on the Dictionary.'
---

This tag allows you to loop through options from a [Dictionary](/fieldtypes/dictionary).

```
{{ dictionary handle="countries" }}
{{ label }} {{ value }}
{{ /dictionary }}
```

You can also use the shorthand syntax for this:

```
{{ dictionary:countries }}
{{ label }} {{ value }}
{{ /dictionary:countries }}
```

You can also output any additional data provided by the Dictionary, like `emoji` or `region` in the case of the Countries dictionary:

```
{{ dictionary:countries }}
{{ emoji }} {{ name }} in {{ region }}
{{ /dictionary:countries }}
```

## Searching

```antlers
{{ dictionary:countries search="Aus" }}
{{ label }} {{ value }}
{{ /dictionary:countries }}
```

```html
🇦🇺 Australia AUS
🇦🇹 Austria AUT
```

## Conditions

```
{{ dictionary:countries region:is="Europe" }}
{{ label }} {{ value }}
{{ /dictionary:countries }}
```

There are a bunch of conditions available to you, like `:is`, `:isnt`, `:contains`, `:starts_with`, and `:is_before`. There are many more than that. In fact, there's a whole page dedicated to [conditions - check them out](/conditions).

## Paginating

To enable pagination mode, add the `paginate` parameter with the number of options in each page.

```
{{ dictionary:countries paginate="10" as="countries" }}
{{ countries }}
{{ label }}<br>
{{ /countries }}
{{ paginate }}
<a href="{{ prev_page }}">⬅ Previous</a>
{{ current_page }} of {{ total_pages }} pages
(There are {{ total_items }} posts)
<a href="{{ next_page }}">Next ➡</a>
{{ /paginate }}
{{ /dictionary:countries }}
```

In pagination mode, your options will be scoped (in the example, we're scoping them into the `countries` tag pair). Use that tag pair to loop over the options in that page.

The `paginate` variable will become available to you. This is an array containing data about the paginated set.

| Variable | Description |
|----------|-------------|
| `next_page` | The URL to the next paginated page.
| `prev_page` | The URL to the previous paginated page.
| `total_items` | The total number of options.
| `total_pages` | The number of paginated pages.
| `current_page` | The current paginated page. (ie. the x in the ?page=x param)
| `auto_links` | Outputs an HTML list of paginated links.
| `links` | Contains data for you to construct a custom list of links.
| `links:all` | An array of all the pages. You can loop over this and output {{ url }} and {{ page }}.
| `links:segments` | An array of data for you to create a segmented list of links.

<br>

## Query Scopes

Doing something custom or complicated? You can create [query scopes](/extending/query-scopes-and-filters) to narrow down those results with the `query_scope` or `filter` parameter:

```
{{ dictionary:countries query_scope="your_query_scope" }}
```

You should reference the query scope by its handle, which is usually the name of the class in snake case. For example: `YourQueryScope` would be `your_query_scope`.

## Files

One of the powerful things you can do with the Files dictionary is pull in options from a JSON, YAML or CSV file.

```
{{ dictionary:file filename="products.json" label="Name" value="Code" paginate="5" }}
```

0 comments on commit cf02bbc

Please sign in to comment.