Layouts

First of all, layouts are actually Vue components that allow for the basic skeleton of the body - so not the entire HTML document, but just the area that is covered by Vue. Layouts are stored in the subfolder layouts/ within the PWA theme. And they are set by using the meta.layout option in a route (as you can find in the routes/index.js file):

{ path:'/example.html', component:Example, meta: { layout:'empty' }}

The Default Theme ships with 3 layouts: Default, Minimal and Empty. The Default layout is (obviously) used most. The Empty layout is actually not used anywhere by default. In the codebase, the import is not for the actual filename layouts/Empty.vue but for a Webpack alias vsf-layout-empty.

Why edit layouts?

It is quite common to modify the layout components. For instance, the Default layout contains a rough structure of main components like main-footer, sign-up and loader, where their position also relates to their place in the HTML document, which again correlates to the CSS positioning. If you are going to turn the CSS structure inside and out, it is quite normal that you are also going to change the structure of the Default layout.

There are also the Minimal layout, which is used for the error page. And as mentioned, the Empty layout is not used anywhere.

However, by modifying the routes, you can implement more layouts or put the Minimal layout or Empty layout to better use. The Minimal layout could be used for instance in the checkout, so that there is no distraction that leads away from the checkout process. The Empty layout could be used to output an XML file or a PDF document or something else, that should not be represented in HTML. When sending different content to the browser, do make sure to set the Content-Type properly. For instance, the following line set the Content-Type header to text-xml.

contextserver.response.setHeader('Content-Type', 'text/xml')

Templates

Layouts are used for the output of the Vue app, living inside the body. Templates (located in src/*.html or within the theme templates/*.html) define the entire HTML document, but only for the purpose of SSR (Server Side Rendering). The tags within these HTML document templates (like {{{ renderResourceHints() }}}) are parsed by a package called vue-server-renderer which is run on the server-side, so that the HTML document - that is being outputted to the browser (or search engines) - contains a full HTML document with all of its SEO value present.

Templates are defined via the configuration option config.ssr.templates. To understand more about the syntax in templates, see https://ssr.vuejs.org/guide/

While the theme really needs to define layouts, adding templates to your theme (src/themes/default/templates/) is optional. If they do not exist, the files are taken from the root of your PWA (src/).

Why edit templates?

Editing HTML templates is not something you will do from the start. It is best to first focus on the Vue part of Vue Storefront and worry about the advanced bits of SSR later. However, there are still a couple of scenarios that come into mind:

AMP can be seen as a subset of HTML, where specific AMP elements are rendered in a minimal webpage with almost no JavaScript. Because the AMP page is so minimal, the performance is also excellent, which is one of the reasons why Google still pushes AMP quite a bit. By default, Vue Storefront tries to turn most of the output into AMP content. Just like with Server-Side Rendering, not all calls are supported, so therefore it could be needed to tune things. It is quite complex and not for the weak of heart. But this could be another reason why you would need to edit the templates.

Another reason might be to simply optimize the Server Side Rendering (SSR) part: This could be a small tuning like adding additional meta tags to the HTML header (like done in the Default Theme) but it could also involve additional output in the HTML.

Summary

In general, editing the layouts is quite common as they are part of the Vue app and you only need general Vue skills to modify things. Modifying templates is less common and only needed if you want to optimize SSR. SSR is discussed in upcoming lessons in more detail.