Intro to using services via craft.app in templates

[carlcs]

It’s currently hard to find info about very common API methods, things like

{% set segments = craft.app.request.getSegments() %}

I know it’s not practicable to duplicate all docs from the Class Reference into documentation articles, but I think there should be something in the Craft 3 Documentation to guide new Craft users. Maybe it would already help to have an intro article in the “Templating” section, with links pointing to the Class Reference pages for common service APIs? Maybe enrich it with some Twig example code?

[brandonkelly]

Just added a quick note about it on the Global Variables page.

As far as craft.app examples go, the plan is that we will start adding Twig examples to the service methods, and style the class reference more like API documentation (like https://docs.api.craftcms.com/), where code examples are displayed off to the right, and you can choose whether you want to view code examples in PHP or Twig.

[narration-sd]

that sounds a really good idea, especially as it will mean more useful documentation, as notes from both coding methods will be merged...also less work...

[carlcs]

Copy from a discussion on Slack:

Craft 2 only made a few of its service functions available in Twig, and all of them were nicely documented in the templating part of the docs where most of them came with nice examples to get you started quickly.

In 3 you now have access to all of Craft’s service functions via craft.app, and all of them are documented in the Class Reference already. I understand that it’s not really practical to have all functions documented in a second place, and it probably wouldn’t even help much because what I think is the most significant difference to Craft 2 docs of craft.request etc is compactness. Only the most usefull templating functions were documented, because more weren’t even available for use. This gave a nice overview of what you can do in Twig which is now lost and a real issue especially for beginners.

[brandonkelly]

Fair point.

[paul-frost]

I've just been pointed to this after getting help on Slack with segments.
I'd just like to re-iterate how the lack of real world examples in the documentation is making Craft 3 a really negative experience. I'm not a beginner but I'm also not a programmer. I keep hitting issues that I can't work out myself. I hate having to ask on SE or Slack how to do what seem such simple things. I search through SE threads trying all combinations of search questions and then usually find they refer to Craft 2.

[brandonkelly]

@paul-frost Thanks, we’re working on it.