Writing a virtual field to a structure field and then use kirbytext() on it

Hi there,

In my controller, I am trying to pre-sort some structure fields. During this process, I need to add some virtual fields into my structure fields (result of some date calculations etc.).

I can achieve this like this:


return function ($page) {

  $testStructures = $page->myStructureField()->toStructure()->map(function($s) {
    $s->testfield = 'testString1234';
    return $s;

  return compact('testStructures');

Now, I can use this in my template like this and it will correctly insert the field’s string:

 <p><?= $testStructures->first()->testfield() ?> </p>

However when I try to use a kirbytextinline() function on this, it gives me the error:
Call to a member function kirbytextinline() on string

Is there a way I can avoid this and somehow insert this new field as a proper field into the structure, so I can still use the kirbytext functions when I use it in the template?

Strangely, I got it working with this old code I had flying around, but it seems to unneccessarily use a groupBy() and a filter() command and I need to write the fields into an array. If I don’t exactly set it up in this combination, it does not work. Since this is really confusing and complicated, I am looking for an easier alternative.

Here is the version that strangely works:

return function ($page) {

  $testStructures = $page->myStructureField()->toStructure()->filter(function(){return true;});

  $testGroups = null;

  if($testStructures->isNotEmpty()) {
    $testGroups = $testStructures->groupBy('_uid')->map(function($g) {

      $g->myData = [
        'testString' => 'testString1234'

      return $g;

  return compact('testGroups');

In my template I can then use the field like this:

<p> <?= $testGroups->first()->myData->testString()->kirbytextinline() ?> </p>

I have no idea why this works and I would be really happy, if someone could show me a simpler way.


$testStructures = $page->myStructureField()->toStructure()->map(function($s) {
  $s->testfield = new Field(null, 'testfield', '**testString1234**');
  return $s;

foreach ($testStructures as $s) {
  echo $s->testfield()->kti();

Thank you so much (once again!), works perfectly.

Two things though:
Neither the new Field() constructor, nor the kti() shortcut are documented anywhere (I realize now the kti() shortcut is listed on the kirbytextinline() page under alias, but that is really hidden and you would not easily discover it).

There are a few methods which seem not to be documented at all, like isPortrait() and isLandscape() and others.

What is the preferred handling if I come across methods like this? Should I open an issue on GitHub, should I post it here? Should I ignore it, as you are aware of it?

My issue with this is, I have no idea which methods are missing in the Reference and what I might be missing out on …

true :see_no_evil:

Ideally create an issue, because if I can’t fix it directly, I’ll probably forget it again.

The aliases are usually missing, because Reflections don’t know about them. I’m not sure if listing them in the main list really makes that much sense or if it clutters more than helps.

And then there’s also aliases that only exist for backward compatibility, like bool() for toBool(), etc., we definitely don’t want to list those.

Ah, ok, I was looking under the category Templates -> Field methods.
However, I feel this whole field section is really hidden. I need to go to Advanced → All Classes → Kirby/Form and there I find it. Not very intuitive at all. Over the search field I seem to be unable to find it at all.

As an end user, I can tell you, it would help tremendously. When I don’t know how to do something, I usually go to the method section of a certain object and check out what methods are available and that usually gives me a good idea what I can do. This way I discovered some other short forms in the past (h and r and others) that I wouldn’t want to miss out on.

Well yes, if you want to leave out those that makes sense. Maybe they can be specially flagged somehow so they are not included?

But I wonder, why are methods like isPortrait() and isLandscape() not listed? If it were not for the Kirby 2 docs, I would not know about them at all. If the references is genereated automatically, those should also be included, I think? It makes me really wonder if lots of other stuff is missing as well.

Yes, there is quite a bit of the image stuff missing from the docs, there is already an issue for that, and we have to find a good way to include that in the docs.

We are trying to constantly improve the docs, and we are well aware that there are still are a lot of things that are hard to find, that a better search is needed etc. It’s always a compromise between not overwhelming newcomers with too much stuff and still allowing advanced users to find the stuff they need. As a technical writer, I know how important good documentation is, because you can have as many great features as you like, if they are hidden or people don’t understand how to use them, they might as well not exist at all. That’s also why your feedback is so valuable, it makes us understand better where we need to improve.

That might be true for the cookbook recipes and for the short articles within the reference. But for the methods section of the reference I would (of course!) expect to have each and every existing method listed, as minor as this method might seem. I mean, where else am I supposed to find them?

So thanks for actually taking notice of my feedback and for hopefully considering it when improving the documentation. Much appreciated.