Add Available Blocks Section

[notebk]

Add documentation on available blocks that can be overwritten

First off, happy to write this up, just need some guidance to make sure I cover all blocks. I think it will be good to have a section with the list of available blocks that can be overwritten (i.e. apostropheMenu is a block that can be overwritten but it's never mentioned).

I know digging through modules can reveal these things, but perhaps it's better to write it up. If you agree, I'm happy to contribute.

[abea]

Thank you, @notebk. I think this could be a new page in the "Working with Templates" section. I have a few thoughts to get you started:

• The page should be slightly more general, covering how to insert template code into parent templates (that's not a very good title). Besides blocks, ideally we would cover the prepend and append methods of apostrophe-templates on the page as well.
• It should briefly review what blocks are. This is already addressed in the pages section (which should eventually link to the new page) and in the Glossary page. It's probably a good idea to include some version the full definition in the glossary since this page would be all about the concept.
• Blocks should be listed in sections:
  • List all of the core content area and public blocks in the layout templates (e.g., afterHead, main, afterMain)
  • List the "helper" blocks (e.g., title, bodyClass)
  • I don't know if we should emphasize the Apostrophe user interface blocks (e.g., apostropheContextMenu). There are some places where they can be safely used, but it's more likely that editing would break the UI. I would be open to opinions on that. Maybe that would be better in a separate "advanced" section on the UI templates.
• The super() pattern should be highlighted as a way to add to a block without overriding it completely. You could link to the Nunjucks docs "for more information". A ::: tip block would be nice to highlight this.

Those are my initial thoughts. This is a good idea and we'd appreciate the contribution.

[notebk]

@abea Sorry for the lag, this is very helpful to start with. I will try and get this out in the next two weeks.

I think linking to an advanced section highlighting the Apostrophe user interface blocks makes sense and keeps in line with the overall documentation structure. I have to get more familiar with super() and popular uses for it, as well as the prepend and append methods. Other than that, should be straightforward.

[abea]

I encourage you to take it piece by piece. The prepend and append stuff is valuable, but if it stops you from getting to a publishable PR then don't worry about it.

The super() template helper really just adds a template block with it to the existing uses of the same block in other files instead of replacing them. The simplest and most common use in my experience in Apostrophe is the bodyClass block. If you are adding a class to body to, for example, change the color scheme, you don't want to either have to find all the existing body classes and rewrite them or totally replace them with only the color theme class. Instead, you would use:

{% block bodyClass %}{{ super() }} color-class{% endblock %}

That would add your class to the others already in that block. There are other uses for it, but that's the cleanest I know of.