Proposal: Add `header_block` Twig Block (#1896)

* Adding ``header_block`` Twig Block

In attempting to remove the default green header from the API docs (I am integrating the docs into a site that already has a header), I have found that the only possible way to do so is to overwrite the entire ``index.html.twig`` file.  This is because the existing ``{% header %}`` twig tags are placed *inside* the ``<header>`` HTML tags.  So, if one overrides the ``{% header %}`` block, it only adjusts the header content, as opposed to allowing control over the entire header object.

To resolve this problem I considered two methods:

- Move the existing ``{% header %}`` tags _*outside*_ of the ``<header>`` tags.  This would resolve the problem in the simplest fashion, but would be a breaking change for those currently overriding the block.

- Add a new twig block, placing its tags *_outside_* the existing ``<header>`` tags.  This would leave the existing functionality as-is, and would not break any current implementations.

I chose the latter for the reasons specified above, and suggested the name ``{% header_block %}``.  Thanks for considering this proposal.

* Add Location of Original Twig Template

This doc page advises that one can `have a look at the original template to see which blocks can be overridden`, but does not say where the original template can be found.  This edit adds that information so that users don't have to resort to searching for keywords (like I just had to).

Note that I haven't run any tests as this is a docs-only change.
This commit is contained in:
jeremy 2021-12-11 08:41:46 -05:00 committed by GitHub
parent 14383f4ee5
commit babf788636
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -51,6 +51,8 @@ file that was distributed with this source code. #}
</defs>
</svg>
{% endblock svg_icons %}
{% block header_block %}
<header>
{% block header %}
<a id="logo" href="https://github.com/nelmio/NelmioApiDocBundle">
@ -58,6 +60,7 @@ file that was distributed with this source code. #}
</a>
{% endblock header %}
</header>
{% endblock header_block %}
{% block swagger_ui %}
<div id="swagger-ui" class="api-platform"></div>