Blueprint options: Indicate if prop accepts query syntax

[texnixe]

It would be great if blueprint options had indicators if a property supports query syntax or not. Some do, some don't, and currently we always have to go to the source code or find out by trial and error.

[distantnative]

I guess we would have to fix this partially in the core, e.g. for field props. Just adding something like (support query syntax). There are likely other parts that are manual docs that we would need to treat as well.

[texnixe]

I guess we would have to fix this partially in the core, e.g. for field props.

Yes, I thought so. Should I add another issue in the core repo?

[distantnative]

I think it's fine here. We can look at it for 3.6.1 or 3.6.2 - shouldn't be too difficult to do

[bastianallgeier]

How's the rule for custom docblock comments? Couldn't we just make up our own? Something like

/**
 * @queries true
 */

Our parser can parse all that stuff as far as I know.

[bastianallgeier]

This would also make our lives a lot easier for the blueprint editor.

[distantnative]

We should be able to implement this custom docblock tag in our reference models.

[bastianallgeier]

Maybe it would be cool to create a general concept for such custom tags. What would be useful for the docs and what would be useful for the editor?

[distantnative]

That would be great, to integrate all at once.

[lukasbestle]

The @queries tag should also be able to differentiate between props that are a query themselves and props that may use queries with the {{ }} syntax.

[distantnative]

@lukasbestle true, I'm just not sure how - I think this already causes some headache with users. We should find a way/words that convey the difference easily

[lukasbestle]

We could use a more generic tag like:

@string-type query
@string-type query-template
@string-type html
@string-type markdown
@string-type query-template html // combination of both
...

Open for a better name. :)

[distantnative]

@lukasbestle getting back to this. I still like your last suggestion.

Would we add it, e.g. here https://github.com/getkirby/kirby/blob/main/config/fields/toggle.php#L22, with the convention that if present @string-type describes how the string form of this prop should be?

Looking at this example, which also allows arrays for i18n, maybe we should also directly find another annotation to indicate i18n support.

[lukasbestle]

The toggle field is indeed a good example as it shows how complex the type system can and needs to get.

Maybe we should hook more into PHPDoc types to be able to more accurately control what can be combined. There are already some custom string types for different use cases. We could add our own:

query-string
template-string
html-string
markdown-string
translation-array

Those could then be used in normal @param definitions. So e.g. for the toggle field text prop:

@param template-string|translation-array<template-string>|array{0: template-string|translation-array<template-string>, 1: template-string|translation-array<template-string>} $value

It's quite verbose, but I think the toggle field is an extreme case here.

[distantnative]

You're probably right that this would be the most solid way forward, but it is a lot work then. Also having to add the support for all those types on getkirby.com, both in parsing and UI. This will need some more nights of sleep for a good idea.