Yamato DaiwaFrontend (2.0.0-beta.4)
English
日本語
Русский

RegularWebPageTemplate

The main Pug template for generating of the valid HTML5 pages recommended for most cases.

If only inherit the Pug file from this template but without adding any other code, then the output code already will represent the valid HTML document:

Because the lang attribute is required for html tag and title tag is also necessary, they has been generated according the default settings. Most likely you want to change them, particularly if you page is non-English. These and many other things could be done by RegularWebPageTemplate__YDF, the JavaScript class for the configuring which could be accessed from JavaScript block of Pug preprocessor.

RegularWebPageTemplate__YDF Configuration Class

Allows to configure the generating of the typical HTML code. This class is available starting from the end of the Functionality Pug block, but it is recommended to access to this class in Metadata block, because majority of settings either related with meta tags, or is the metadata at its core:

The settings could be specified by calling the configure static method, the only parameter of which is a multi-level configuration object:

metadata.locale
Used to fill the attribute lang of the tag html. Since this attribute is required for the html tag, there is the default value "en", which must be replaced with another value for non-English pages. It is noteworthy, but the value of the attribute lang is officially called "language tag", what is confusing, that is why this property has been named the "locale".
metadata.title
Used to fill the tag title. Since this tag is required, there is a default value — "Untitled".
metadata.description
If defined, then the tag meta will be added with the attributes name="description" and content, the last of which will be filled with the specified value.
metadata.keywords
If defined, then the tag meta will be added with the attributes name="keywords" and content, the last of which will be filled with the specified value.
metadata.author
If defined, then the tag meta will be added with the attributes name="author" and content, the last of which will be filled with the specified value.
faviconURI
If defined, then 2 tags link will be added, herewith one of them will have the rel="icon" attribute, and another one will have rel="shortcut icon", attribute, and also both will have the href attribute filled with the specified value. This value must be a valid URI referencing the icon file to be displayed on the browser tab.
AMP_VersionURI
If defined, then the tag link will be added with the attributes rel="amphtml" and href, the last of which will be filled with the specified value. This value must be a valid URI referencing the AMP version of the same page.
stylesSheetsURIs
If defined with the array, then for each its element the tag link with rel="stylesheet" and href attributes will be added, herewith the href attribute will be filled by the array element. Each of these elements must be the string and represent the valid URI referencing the CSS file.
scripts.atEndOfHead

If defined with the array, then for each its element the tag script with src attribute will be added to end of the head tag, herewith the src attribute will be filled by the array element. Each of these elements must be the string and represent the valid URI referencing the JavaScript file.

  • Generally it is not recommended to add the scripts to the end of head tag because without specific measures the rendering of the HTML page will be suspended until the script will be loaded. The exceptions are the cases such as the third-party scripts for the analytics.
  • The script tags added by this way will not have any attributes except src. If you need any other attributes, add the script tag manually using the HeadScripts Pug block.
scripts.atEndOfBody

If defined with the array, then for each its element the tag script with src attribute will be added to end of the body tag, herewith the src attribute will be filled by the array element. Each of these elements must be the string and represent the valid URI referencing the JavaScript file.

  • This method of adding of the scripts is the recommended one because this way the loading of the scripts will not detain the page rendering.
  • The script tags added by this way will not have any attributes except src. If you need any other attributes, add the script tag manually using the EndBodyScripts Pug block.

The configure method could be called repeatedly, but because the repeated specifying of same properties will overwrite the previous values, the calling of this method repeatedly is meaningful only if specify the non-repetitive properties. For example, if your site or application has single natural language (assume that English), and there is the single author for all pages, it is meaningful to specify the respective settings in the separate file (e. g. CommonMetadata.pug):

Then, this file could be included to the files of pages an specify only specific for certain page metadata:

Pug Blocks

The modification of Pug templates is being executed via Pug blocks. In RegularWebPageTemplate template, the following Pug blocks has been declared.

Functionality

Use this block if you want to write some functionality on built-in JavaScript.

Because the functionality of "Yamato Daiwa ECMAScript Extensions" library is being included to this block, starting from this block you can use it if specified the append keyword during referring to this block:

Data

Use this block if you want to generate some data to use it for the generating of the markup.

Requirements

Use this block for including of the Pug files containing the Pug mixins or inner JavaScript code, for which the previous blocks are not suited for some reason.

Metadata

Use this block if you want to define the metadata of HTML page via JavaScript variables. In particular, this block is exactly where it is recommended to call the RegularWebPageTemplate__YDF.configure({}).

StatesSimulations

If it is planned to create the dynamic page, then on the stage of creating of the markup and styles using the Pug conditional rendering it is possible to check, does page displaying correctly with or without certain elements. Specifically, various states could be displayed. For example, if the dynamic data collections retrieved by AJAX must be displayed, the page will have the following states:

  • Data retrieving is process
  • Data retrieving error
  • No data
  • There is the data but no search results
  • The data has been successfully retrieved and displaying

All of this states could be defined via boolean variables (in below example it has been implemented by the class with the object-type statesSimulations static field which properties are referring to specific states) and organize the conditional displaying:

To switch between the states, it is required to re-run the Pug. However if you want to represent all of these states as separate pages to customer before the implementation of JavaScript dynamics and server part but also minimize the routines (particularly, avoid the manual creating of the separate page for each state), consider the static preview concept and the project building tool Yamato Daiwa Automation (abbreviation: YDA), which has the functionality designed exactly for such cases.

HeadBegin

Use this block if you want to add something to the start of the head tag (before other children elements).

The sequence of children in relation to head elements is rarely matters (mainly it ths the sequence of the styles and scripts), so usually there is no need to add something precisely to the start thus this block will come in handy only in the rare occasions.

Styles

Use this block if for some reason it is not enough to specify the styles via (RegularWebPageTemplate__YDF.configure({})) or if you want to declare the styles directly in the head tag. Particularly, because the link tags which will be generated according the configuration have no any attributes except href and rel="stylesheet", so if you need other attributes, add the link tags inside Styles block manually:

This way of styles specifying does not conflict with specifying of the styles via configuration, however for the correct cascading of styles it is required to respect the sequence in which CSS rules declared on the page. Because in the CSS, the priority depends on multiple factors it is impossible to say unequivocally that the CSS rules declaration sequence will change the displaying, however the sequence is the one of factors on which final displaying depends.

  • Use prepend keyword when modifying the Styles block to add the styles before the ones specified via configuration.
  • Use append keyword when modifying the Styles block to add the styles after the ones specified via configuration.

HeadScripts

Use this block if for some reason it is not enough to specify the scripts via (RegularWebPageTemplate__YDF.configure({})) or if you want to declare the scripts directly in the head tag. Particularly, because the script tags which will be generated according the configuration have no any attributes except src, so if you need other attributes, add the script tags inside HeadScripts block manually:

Basically it is recommended to add the scripts to the end of body tag, because the scripts defined previously could slow down the page rendering. However, in some cases the scripts must be added exactly to head tag, especially if the are the third-party scripts for the analytics such as the Google Analytics:

This way of scripts specifying does not conflict with specifying of the scripts via configuration, and if the scripts independent of each other (in modern times it is usually such as but not in legacy sites and web applications), these methods could be combined.

  • Use prepend keyword when modifying the HeadScripts block to add the scripts before the ones specified via configuration.
  • Use append keyword when modifying the HeadScripts block to add the scripts after the ones specified via configuration.

PageContent

Add the visible content of this page to this block. Herewith, the body will be the direct parent of the generated HTML code.

EndBodyContent

According to some methodologies, the elements with the fixed positioning such as the modal dialogs should be placed after all other elements, but of course, still inside the body tag. If you are following this methodology, use EndBodyContent block. The content of this block will be placed direct after the content of PageContent block.

EndBodyScripts

Use this block if for some reason it is not enough to specify the scripts via (RegularWebPageTemplate__YDF.configure({})) or if you want to declare the scripts directly in the body tag. Particularly, because the script tags which will be generated according the configuration have no any attributes except src, so if you need other attributes, add the script tag inside EndBodyScripts block manually:

This way of scripts specifying does not conflict with specifying of the scripts via configuration, and if the scripts independent of each other (in modern times it is usually such as but not in legacy sites and web applications), these methods could be combined.

  • Use prepend keyword when modifying the EndBodyScripts block to add the scripts before the ones specified via configuration.
  • Use append keyword when modifying the EndBodyScripts block to add the scripts after the ones specified via configuration.

Multi-level Inheritance

If your project has multiple pages, herewith most of them has the common part (for example, shared header, footer and sidebar), then it is meaningful to extend Pug files of the pages from the interim page templates containing the shared markup, not directly from the RegularWebPageTemplate. Usually there are the main template, admin panel template, authentication template etc.

Below, the page template including single-column page layout has been represented. To embed the page-specific content to this page layout, new SpecificContent pug block has been defined:

Now, it is possible to extend other pages from this page template:

© 2023 Yamato Daiwa Co., Ltd.