[RFC] Revamp of 'Extending Contao 4' + 'Contao 4 cookbook'

[m-vo]

Here is a draft for a 'english and Contao 4 only' section of the cookbook with some short articles mainly about bundle development to start with.

As mentioned in #457 I think it would make sense to start a new section that only contains Contao 4 related articles (or at least no content that is deprecated) in only one language so that new admins & developers can have an easier start with Contao 4. Besides, Contao 3's lifetime ends soon in terms of the rather slow progress of the documentation... 😄

If we decide this is something that would be helpful, we could copy / migrate / translate old articles that apply, too. (Please keep in mind that this is a early stage with unreviewed and possibly wrong or incomplete content.) Let me know if I should keep on working on this and if this fits in here - feedback's welcome.

[aschempp]

AWESOME!! 🎉 🎉 🎉

Looks like a very good first draft to me! There's some feedback I can provide, but it's gonna be hard to write down. Maybe we should have a (public) call on Mumble about the topic? The regular call is scheduled tomorrow from 3pm to 5pm, maybe you want to join and we discuss the topic after 5pm?

[m-vo]

Thanks, that sounds like a really good idea 👍! Unfortunately I don't have time tomorrow (past 3:30pm). I could only try to join the call maybe half an hour earlier before it starts - hope this works on Android :-). Or we could postpone it to another day?

[aschempp]

well we could discuss before 3pm as well. Or any other time, just send me an email to andreas.schempp@terminal42.ch 😊

[stefansl]

Great work, thanks! It already helped me! 👍

[m-vo]

This will still take some time... ;-)

As discussed on mumble I started by (partly) integrating the articles into the Extending Contao 4 manual. And with this I started rewriting the bits and pieces there as well... the last commit really is WIP. Unfortunately I can keep on working on it end Aug / Sept soonest.

[aschempp]

Good work! I really like your wording, winks and "how to" approaches. Makes the manual fun to read 👍

[Toflar]

Super cool stuff! Thank you very much!! I'll just add a note here and there to maybe improve it a little. But the quality is already seriously high! 👍

[m-vo]

Thanks a lot! I really appreaciate your comments.

I'm on holidays tommorow and will be freshly motivated to finish this project afterwards :-).

[m-vo]

Ok let's get this done. I included Toflar's feedback and tried to get this part somewhat finished. Still some open questions and decisions to make. And feedback is still welcome of course!

Extending Contao 4

I reworked the Extending Contao 4 section (not much change in that part since last push) - here are the open points I'm stuck with or unsure:

• [ ] How do references across books work? Same relative paths? (linking to cookbook)
• [ ] What's the ParserInterface in getBundles(...) (BundlePluginInterface) for?
• [ ] What's the current best practice with config parameters that a user needs to to be able to change (like an API key)? In Contao 3 this probaly would have landed in tl_config / system settings. (How is the Manager going to deal with this in the future? 😃)

Contao 4 Cookbook

I think I don't want to put too much content into the Cookbook right now to get this finished and rather extend and improve it with other pull requests later on (This one's gotten quite big anyway). Here are the things that we should probably decide on:

• [ ] Do we want to link to 3rd-party articles/tutorials or should the authors rather be invited to do pull requests and add their bits and pieces here? Having it here would be the better option in terms of accessibility and quality (reviewed) I guess but it's also the possibility that noting ever happens. ;-)
• [ ] How should the Contao 4 Cookbook be integrated in the Cookbook's structure?*

) Of the 20 english articles, 7 are about the old extension repository, 3 on custom modules, and many of the remaining ones do as well not or not fully apply to Contao 4 and/or are imo not best practice anymore. (Same goes for to the 6 german articles that aren't translations). That's a very short list and I don't really think any more Contao <4 articles will appear. (I know: At some places there already exist warnings that things work differently in Contao 4 but I find it kind of confusing...) So what about putting all of this old stuff in a separate list (pre Contao 4* or something) and extracting and modernizing the useful bits out of the two languages into the new Cookbook? Shouldn't take that much effort.