Improve Core Widget and DCA field documentation

[bezin]

Hi there,

I really appreciate the (not so new anymore) documentation and it was a huge step forward 🎉

One thing that is still a little hard to understand is the DCA field documentation.

What we currently have is a list of all available options, structured in a way that does not help you if you are new to Contao, and – honestly – only even helps you a little if you are already a few years in. The key issue is IMO, that nowhere in the documentation we actually show which widget can be configured with which options. We know all the options, we know all available Core widgets, but there is no matching between them.

As a positive example I would like you to have a look at the field documentation of the Kirby CMS. There is a whole page dedicated to every single field (Kirbys widget) with all the properties that can be set to configure this particular field. You also find plenty examples of different configurations, but I think we all would love to see more examples everywhere in the documentation ;-)

There are some issues with this approach for sure: In Slack, @ausi already mentioned,that one would need to document general options that apply to many or all widgets in a way that does not turn into an unmaintainable mess.

Since I think it is easier to reason about this if there is something to reason about, I'll document a widget as I would like to see them and we can further discuss it from there :-) Comments and thoughts much appreciated.

Cheerio

[bezin]

Hello again,

I „quickly“ documented the checkbox widget as a very first, totally unfinished draft to show what I would like as a result in the end.

As you see, my main focus would be on how to use this specific widget. The general options table with options shared among all widgets is an issue editing-wise: Maybe there is a HUGO way to share content across multiple pages? It would be nice to edit it in a single place, but reference it on every page. The widget specific options are also shared between some widgets, but I feel like these should be explained in the context of a widget.

Source is here: https://github.com/bezin/contao-docs/tree/widget-reference

BTW: The Kirby documentation is self-documenting when it comes to the field config, as the Kirby panel (back-end) is implemetend in Vue and the documentation just reads the component definition 🤷

[fritzmg]

Looks very good 👍

Now if you could provide a PR containing all the widgets that would be super-duper 😁

In all seriousness: I would happily merge the PR for just one fully described widget, which will then act as a template for the other widgets :). I would then create issues for widgets that are not yet documented, so that I can assign those issues to either myself if I work on a widget - or anyone else in the community who says they want to work on it.

[bezin]

Well I can provide you an empty page for every core widget in a matter of minutes 😂

I totally agree with the procedure – I'll give it some more thought on this particular widget and will then provide a PR. Then we all can work on the other widgets one after another 👍

Any idea on this shared content thing? I also thought: Maybe these pages are not really there to explain every shared configuration, but only the specific ones? The DCA fields reference does not necessarily need to be removed. They could live alongside each other for a time.

[fritzmg]

Any idea on this shared content thing? I also thought: Maybe these pages are not really there to explain every shared configuration, but only the specific ones? The DCA fields reference does not necessarily need to be removed. They could live alongside each other for a time.

Yes, I would keep the DCA reference as it is (at least for now). We can then link there to the Widgets overview page so that one can look up the relevant fields for specific widgets. On the matter of the shared configuration: I am not sure. I think technically we should always list all the relevant configurations for each widget. It's more work and leads to duplication, but it would be far more convenient for whenever you want to lookup the possibilities of a specific widget.

[fkaminski]

Any idea on this shared content thing?

Maybe with the help of (front matter) tags with appropriate naming convention?
(a,o. with using shortcode https://github.com/contao/docs/blob/main/page/layouts/shortcodes/taxonomylist.html)

[bezin]

Hello there,

I worked a little more on my checkbox example (see https://github.com/bezin/contao-docs/tree/widget-reference if you wanna check it out yourself):

I gave the general vs. specific options discussion another thought. Including the general options on every widget page would be tedious to repeat, take up a lot of space and be incomplete and out of sync sooner or later anyways. I then thought about a separate section Widgets \ General Options, but this turned out to be a copy of the already existing DCA field reference. So I decided to only include the options that are essential to this one particular widget.

I think the key points to document is the options at hand, the necessary SQL definition and examples. The last is actually the most important as it shows the different options to work together.

I also took new screenshots from the online demo so that they show an English user interface.

This is how the widget index page could look like: All widgets listed alphabetically with a short description (that should be a little more explanatory than the one in the screenshot ;-))

[fritzmg]

Closing in favour of #732 and #743 🥳