Overriding Header and Footer

Technical Questions
1

Where is the best insertion point for a custom header and footer?
In reviewing code and documentation (Quick Tutorial → Mount a Subscreen) the chain appears to be as follows:
webroot.xml - default root screen, can be overridden in Moqui conf file.
references header and footer ftl files:

        <render-mode>
            <text type="html" location="component://webroot/screen/includes/Header.html.ftl" no-boundary-comment="true"/>
            <text type="xsl-fo" location="component://webroot/screen/includes/Header.xsl-fo.ftl" no-boundary-comment="true"/>
        </render-mode>

The tutorial recommends configuring a custom component as a subscreen of apps.xml

<?xml version="1.0" encoding="UTF-8" ?>
<moqui-conf xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/moqui-conf-2.1.xsd">
    <screen-facade>
        <screen location="component://webroot/screen/webroot/apps.xml">
            <subscreens-item name="tutorial" menu-title="Tutorial" menu-index="99"
                    location="component://tutorial/screen/tutorial.xml"/>
        </screen>
    </screen-facade>
</moqui-conf>

apps.xml references navbar ftl

        <section name="TopNavSection" condition="hideNav != 'true'"><widgets>
            <container id="top">
                <render-mode><text type="html" location="component://webroot/screen/includes/navbar.html.ftl"/></render-mode>
                <subscreens-menu type="popup" id="header-menu" title="Application"/>
            </container>
        </widgets></section>

Questions:

  1. How is apps.xml bootstrapped? Is it a subscreen of webroot.xml? If so where is the defined, I cannot find it.
  2. Is a custom apps.xml file within a custom component the best place to override header and footer? This assumes using the existing foundation provided by header and footer ftl files referenced in webroot.xml.
  3. If the functionality provided in the ftl files needs to be customized how would this be done? Override webroot.xml in config?
2

Point of clarification… when I say “header” I am specifically referring to the navigation at the top of the screen. Applications menu, user notifications, logout, etc.
On further investigation much of this appears to be controlled by WebrootVue.qvt.ftl, which is referenced in qapps.xml here:

    <widgets>
        <render-mode>
            <!-- for html just render the navbar (Vue page wrapper and nav component) -->
            <text type="html" location="component://webroot/screen/includes/WebrootVue.qvt.ftl"/>
            <!-- not meant to be used for anything else, for all other render modes go directly through /apps -->
        </render-mode>
    </widgets>

So the chain appears to be as follows:

  • webroot.xml - default setting that can be overridden in Moqui conf
    • header.html.ftl - gets css, js, icon, etc. from theme
  • qapps.xml - default subscreen in webroot.xml
    • WebrootVue.qvt.ftl - gets logo, title from theme and creates some of the navigation at top of screen.
  • apps.xml - unclear how this is included
    • navbar.html.ftl - also seems to get logo and title from theme and builds the navigation in the top right (dark/light toggle, notifications, etc.)
3

Perhaps as you’re finding out, there is no single header (or top nav bar is probably a better term to distinguish from other things that are called header). Even if you are referring to the OOTB ‘apps’ container in webroot, that needs to be clarified because not everything lives under that, especially custom things.

For screens and sub-screens there are 4 ways to define them:

https://moqui.org/m/docs/framework/User+Interface/XML+Screen#subscreens

Actually, as of last week there is a 5th using the new screen-extend functionality, but that is brand new and has no documentation yet aside from the built-in docs in the XSD and such.

The OOTB applications shell in apps.xml (in the webroot component) is primarily for server-rendering of HTML that does not use Vue JS or any other JS lib for client rendering (ie React, Angular, etc).

To support a Single Page Application (SPA) shell and at least partial client rendering while still supporting the Moqui XML Screens which has Groovy expressions and allows other server-specific logic, the vapps.xml screen plus the files it uses were added as a shell around the screens under the apps.xml screen. The vapps.xml screen uses Vue JS with Bootstrap for layout and styling. More recently the qapps.xml screen was added which is another shell that uses the screens under apps.xml but uses a Vue JS plus the Quasar widget and UI library which uses Google Material Design styling… and technically is more strictly componentized with Vue JS than vapps was.

For more info about how this works, and how to create variations on this, the moqui-quasar-custom example component and its README might be helpful:

Depending on what you want to do, ie why you want to modify the top nav bar, it may make sense to use something like this to create a custom shell that leaves the OOTB apps infrastructure as-is.

To modify the top nav bar in the OOTB apps/vapps/qapps infrastructure there is one file for each: navbar.html.ftl, WebrootVue.vuet.ftl, and WebrootVuew.qvt.ftl.