How to use the Tags field with manual and autocomplete input?

Kirby 3 Solved ✅
1

Hello,

I try to set up a Tags field with autocompletion from previous input. I defined a field like this:

  tags:
    type: tags
    required: true
    min: 1
    max: 5
    options: query
    query: site.tags.toStructure

I would like to have autocompletion with options from other pages and to allow manual input at the same time. For example if I have 3 pages and each of them used different tags like test, whatever, hello, I would like to see these 3 tags as an autocompletion in a draft of a new 4th page. If I type in some tag which wasn’t used in the past, it should be a valid value.

According to my understand I have to use a query with site because page only provides information from the current page which doesn’t fit here. The tags in the query refers to the field with the same name and toStrucutre is used to convert the fields content to a by the autocompletion supported format.

So what am I missing here? I tried several queries and it seems I do not the query concept in detail. The only autocompletion I was able to perform was to get the Home and Error page titles as autocomplete so the feature works in general.

Best Regards

2

toStructure() definitely doesn’t make sense here, unless you have defined a tags field in your site.yml and that field is a structure field.

Also, do you want to get the tags from sibling pages only or from the complete site?

You can find query examples in the documentation: https://getkirby.com/docs/reference/panel/fields/tags#dynamic-options__option-queries

A usual use case is to query the tags from all sibling pages

query: page.siblings.pluck("tags", ",", true)

Or if you want to get them from the complete index:

query: site.index.pluck("tags", ",", true)
1 Like
3

Hi @texnixe!

the first query provides the expected output, although the second query is empty. I think the reason for why I found no solution was that I didn’t know that page is the proper source here and how siblings are defined, like what they are. I’m surprised that this is the proper solution. Maybe the Kirby 3 documentation examples should always have a proper description, even if it’s suspected to be self-explaining. Not every example given in the query solution is obvious in my point of view.

Thank you!

4

I can add a short comment to each example, yes, but the thing is that you need to be familiar with Kirby’s API (the query language is built on that) to use it effectively because we can’t really add every possible query.

5

I agree that the examples are fine - there is no reason to add every possible query. Let’s break it down to be more precise:

  1. How do I find out what a sibling is in Kirby 3? I found no definition at all in the documentation nor in the forum. If it’s a sibling in terms of a tree data structure, I come to question 2:
  2. Why is page object, which represents a single page according to https://getkirby.com/docs/guide/templates/php-api, able to provide information about siblings and how comes that there are siblings from point of view of the page object? I would expect that I have to use site or pages because I didn’t create subpages - every page is a standalone page and thus I thought there are no siblings for a single page.

Most likely question 2 is based on a false understanding about how siblings are defined.

6

Each page has siblings. If you do a dump($page) in any template, you will see them in the object.

For example in a Starterkit, the siblings of the photography page are:

Kirby\Cms\Pages Object
(
    [0] => photography
    [1] => notes
    [2] => about
    [3] => error
    [4] => home
    [5] => sandbox
)

The siblings by default contain the page itself, unless you set the $self parameter to false (https://getkirby.com/docs/reference/objects/page/siblings).

Why? Because children, siblings, files, parents etc. are all properties of the Page class.

1 Like
7

This seems to be a major reason for why this actually works how it works. I have to check those things via typical debugging ways (for example outputting general variables to see what they really contain). I’m glad I’ve asked this question because your posts often provide valuable information I wouldn’t find out by chance or by reading the documentation. Now I’m better able to understand other scenarios too!

8

Each object has an overview page with all the available methods in the reference, for example the $page class: https://getkirby.com/docs/reference/objects/page?advanced=no

If makes sense to go through these once in a while to get an idea what sort of information you can get from each object.

Apart from the list of all available methods at the top of each object, if you scroll down a bit you can find how to create such an object and some examples of important method calls (ok, the siblings are not mentioned…).

Edit: That is not to say it can’t be improved, but I sometimes have the feeling that although the information is there, people probably just don’t see it–for whatever reason.

1 Like
9

… I didn’t know about the examples at the bottom of the lists of available methods for each object … I checked some methods by hand but I didn’t look too close at the overview page.

Yep, I agree about people not finding the relevant information but I’m sure it’s often not related to being lazy to look it up. I worked on the Tags field for 2 days and read all the pages about it and the basic stuff information multiple times, just to verify I didn’t miss something. I think it’s sometimes not too easy to understand each example and to find all the relevant pages for your question - like you have to look at the references, the cookbook, the guide and the quick start tutorial. The reference is nice if you are aware of what you need and how to implement it but it’s quite hard if you don’t know what you are looking for exactly. In my case I’m not sure how it could be improved. I was just unaware about how everything has siblings and that I have to check closely what an object provides regarding properties/attributes.

Is there a way to get more information when a query is invalid? Like more information than the error message Invalid query result data. Debugging is already enabled. Maybe some kind of information like what field is unknown or that the called method X is not supported on this object type?

10

You can often find more information in the browser console. Whether or not that helps to debug the error, is another question.

For example, if you create a query like this for a files field

    fields:
      cover:
        type: files
        query: site.find('photography/animals')

that doesn’t make sense, because here we expect a files collection, not a page.

The error message in the console will be:

54
Bildschirmfoto 2019-05-30 um 17.52.54.png2712×714 134 KB

So it won’t tell you exactly what the error is. But you will at least now that you have to provide something to loop through like an array/collection.

And if you look into the /kirby/config/fields/file.php file on line 176, you will find this:

foreach ($files as $index => $file) {
  $data[] = $field->fileResponse($file);
}

so, ok, we need files.

Since the queries are the same as the PHP API, only with a different syntax (and currently less options), you can “translate” them and test and debug them in a template.

So if you

dump($site->find('photography/animals'));

that will obviously give you a page, not a files collection.

If a query works in your template but not in a blueprint, you are either running into a limitation (you currently can’t use variables as parameters, will change in 3.2) or you are not providing the required information even if the query as such is ok (see above).

2 Likes
11

Wow, this is a wonderful post. Thanks @texnixe! So much to keep in mind and to find out but this is so valuable!!! I bet this will help me with problems in future.

12

If not, there’s always the forum to come to and ask questions.

1 Like
13

And the guide on the query language has some more syntax comparison examples as well:

https://getkirby.com/docs/guide/blueprints/query-language#introduction__syntax

2 Likes