about.page

---
title: Tag
description: Lists all pages in the current folder, filtered by tag.
icon: 'M5.5,9A1.5,1.5 0 0,0 7,7.5A1.5,1.5 0 0,0 5.5,6A1.5,1.5 0 0,0 4,7.5A1.5,1.5 0 0,0 5.5,9M17.41,11.58C17.77,11.94 18,12.44 18,13C18,13.55 17.78,14.05 17.41,14.41L12.41,19.41C12.05,19.77 11.55,20 11,20C10.45,20 9.95,19.78 9.58,19.41L2.59,12.42C2.22,12.05 2,11.55 2,11V6C2,4.89 2.89,4 4,4H9C9.55,4 10.05,4.22 10.41,4.58L17.41,11.58M13.54,5.71L14.54,4.71L21.41,11.58C21.78,11.94 22,12.45 22,13C22,13.55 21.78,14.05 21.42,14.41L16.04,19.79L15.04,18.79L20.75,13L13.54,5.71Z'
color: '#195fe7'
author: Taufik Nurrohman
type: Markdown
version: 3.0.1
...

This extension enables the tag filter feature by using the page’s `kind` property to add multiple routes, such as
`http://127.0.0.1/blog/tag/:tag/1`, to each page to allow users to list all pages in the current folder by tag.

[Panel](https://github.com/mecha-cms/x.panel) extension can help you to automate everything. But if you have to, you can
still make this extension work without the GUI feature. Before we start, you need to know how this extension works.

Writing a tag file is the same as writing a page file. The only difference is that you have to write the `id` property
separately from the page. Be sure to specify a unique number for each `id.data` file. These numbers will then be used to
associate the tag file with the `kind` property on each page:

~~~ .txt
.\
└── lot\
    ├── page\
    │   └── …
    └── tag\
        ├── bar\
        │   └── id.data ✔
        ├── baz\
        │   └── id.data ✔
        ├── foo\
        │   └── id.data ✔
        ├── bar.page
        ├── baz.page
        └── foo.page
~~~

Here’s an example of what a tag file might contain:

~~~ .yaml
---
title: Tag Name
description: Short description about this tag.
type: Markdown
...

Long description about this tag.
~~~

To associate tags with the current page, create a `kind.data` file in the relevant folder that contains a list of tag
IDs written in a valid JSON format:

~~~ .txt
.\
└── lot\
    ├── page\
    │   ├── lorem-ipsum\
    │   │   └── kind.data ✔
    │   └── lorem-ipsum.page
    └── tag\
        └── …
~~~

Example contents of a `kind.data` file:

~~~ .json
[ 1, 2, 3 ]
~~~

You can also include the `kind` property in the page header, but this method may not be performance efficient when
reading the data:

~~~ .yaml
---
title: Page Title
description: Page description.
author: Taufik Nurrohman
type: Markdown
kind: [ 1, 2, 3 ]
...

Page content goes here.
~~~

### Usage

These HTML classes will be added to the root element if it contains a `class` attribute when you are on the tags page.
You can use this feature to create a specific look or response on your site from the client side if the following
classes are found in the root element:

`is:tags`
: Will be added if the current items view is a tags view and is not empty.

Example usage in CSS code:

~~~ .css
.is\:tags body {
  border-top: 4px solid #f00;
}
~~~

Example usage in JS code:

~~~ .js
if (document.documentElement.classList.contains('is:tags')) {
    console.info('You are currently in the tags page.');
}
~~~

These additional conditional statements are available for use in layouts to show/hide elements on your site from the
server side:

`$site->is('tags')`
: Returns `true` if the current items view is a tags view and is not empty.

Example usage in HTML/PHP code:

~~~ .html.php
<?php if ($site->is('tags')): ?>
  <p role="alert">
    <?= i('You are currently in the tags page.'); ?>
  </p>
<?php endif; ?>
~~~

These additional variables are available for use in layouts that carry data related to the currently active tags page:

`$tag`
: This variable is an instance of the `Tag` class, which you can use to get the current tag information.

Example usage in HTML/PHP code:

~~~ .html.php
<?php if ($site->is('tags') && !empty($tag)): ?>
  <p role="alert">
    <?= i('Showing pages filtered by tag %s.', $tag->title); ?>
  </p>
<?php endif; ?>
~~~

This extension will also add `query` and `tags` properties to the page only if the page contains a `kind` property that
is not empty:

~~~ .php
// These numbers refer to the tag IDs.
$kind = $page->kind; // Returns `[1, 2, 3]`
// These queries are automatically generated based on the available tags.
// They may be generated less than the amount of `kind` data because non-existent tag IDs are ignored.
$query = $page->query; // Returns `['bar', 'baz', 'foo']`
// These tags data are also generated based on the available tags.
$tags = $page->tags; // Returns `Tags` class instance
~~~

Example usage in HTML/PHP code:

~~~ .html.php
<?php if ($tags = $page->tags): ?>
  <?php if ($tags->count): ?>
    <ul>
      <?php foreach ($tags as $tag): ?>
        <li>
          <a href="<?= eat($tag->link); ?>" rel="tag" title="<?= eat($tag->description); ?>">
            <?= $tag->title; ?>
          </a>
        </li>
      <?php endforeach; ?>
    </ul>
  <?php else: ?>
    <p role="status">
      <?= i('This page does not contain any %s.', 'tags'); ?>
    </p>
  <?php endif; ?>
<?php endif; ?>
~~~