Skip navigation

Integration with Frontend

Detail steps of how to integrate between frontend and backend.

Overview

When Frontend team release new FE package, BE team will have following items:

  • /PreciseAlloy.Patterns - folder
    This folder contains HTML snapshots of the rendered frontend pages using the code from the time of package creation. Its purpose is to facilitate change tracking, enabling the Backend team to easily identify the areas that require reintegration.
    Note that these files are not necessary for running your website, so there is no need to deploy them.

  • /PreciseAlloy.Web/wwwroot/assets - folder
    This folder contains compiled frontend assets, including CSS, JavaScript, and images required for integration and website functionality.

  • /PreciseAlloy.Web/wwwroot/assets/hashes.json - file
    This file provides a comprehensive list of all assets in the frontend bundle, along with their content hashing. It is essential to include this file during site deployment to ensure the cache buster asset path generation, thereby preventing any issues with CDN caching. Failure to include this file will render the cache buster mechanism ineffective.

The Frontend team will handle the preparation of these items, so the Backend team doesn't need to take any action to obtain them. However, if there is a need to manually build them, please refer to the Integration - Frontend guide for detailed instructions.

Integration

Copy the markup file

Begin the integration process by copying the markup provided by the Frontend team into the corresponding Backend view (.cshtml files).

For example, if you need to integrate the Hero block and the Frontend team indicates that it can be found on the static site's Home page, navigate to the matching pattern's Home page within the Pattern folder. Locate the markup for the Hero block, such as the example below:

<section class="zzz-o-hero">
  <h1>WELCOME</h1>
  <img src="/samples/image-1.svg" alt="hero">
  <a href="https://www.office.com/">
    <span>Explore</span>
    <svg viewBox="0 0 19 19" width="19" height="19">
      <use xlink:href="/assets/images/icons.svg#zzz-view"></use>
    </svg>
  </a>  
  <!-- <link rel="stylesheet" href="/assets/css/b-hero.css"> -->
  <!-- <script type="module" src="/assets/js/b-hero.js"></script> -->
</section>

Copy this markup and paste it into the Backend view (.cshtml) file corresponding to the Hero block.

Handling hashes.json

Suppose that you have a file named hashes.json located at /PreciseAlloy.Web/wwwroot/assets/hashes.json with the following content:

{
  "/assets/css/style-base.css": "Y3_rQ26JDf",
  "/assets/css/b-hero.css": "t8cxlFd_dF",
  "/assets/js/react-loader.0x4d7d0ab2.js": "",
  "/assets/js/main.js": "iX_2YqQ2z7",
  "/assets/js/hero.js": "A_CKPf-kTa",
  "/assets/images/icons.svg": "SeT74kfn_L",
}

To simplify handling this information, we will create HTML extension methods. These methods will generate appropriate tags for CSS and JavaScript files, taking care of cache busting through the hash value appended to the file URLs. For the list of availabe methods, please check /PreciseAlloy.Utils/Extensions/HtmlExtensions.cs.

Including CSS files

If you want to include b-hero.css into the <head> element of your page, use the following method:

@{
    Html.RequireStyle("/assets/css/b-hero.css").AtHeader();
}

The output will be:

<link href="/assets/css/b-hero.css?v=t8cxlFd_dF" rel="stylesheet">

The ?v=t8cxlFd_dF part represents the hash of the file's content, generated at the frontend's compile time. This approach ensures proper caching. If the file remains unchanged, the hash value remains the same, allowing browsers and/or CDN to cache it for extended periods. When the file content changes, the hash value changes as well, prompting browsers to retrieve the updated file to avoid any caching issues.

You can call the above method multiple times, but the rendered HTML will contain exactly one instance of the link to that CSS file.

Including JavaScript files

To include hero.js at the footer of your page, use the following method:

@{
  // Caution: see the note below
  Html.RequireScript("/assets/js/hero.js").AtFooter();
}

The output will be:

<script src="/assets/js/hero.js?v=A_CKPf-kTa" type="module"></script>

Similar to the CSS method, the JavaScript method also appends the hash value to the file URL, ensuring cache busting.

Obtaining the path directly

If you only need the path of an asset without the HTML tag, you can use the method @Html.GetCacheBusterPath() directly. For example, to include an image:

<img src='@Html.GetCacheBusterPath("/assets/images/icons.svg")'>

The output will be:

<img src='/assets/images/icons.svg?v=SeT74kfn_L'>

Sample integration

The sample HTML markup for the Hero above can be integrated into the Backend view as shown below.

@model HeroViewModel;

@{
  // Styles
  Html.RequireStyle("/assets/css/b-hero.css").AtHeader();

  // Scripts
  Html.RequireScript("/assets/js/hero.js").AtHeader();

  // Icons
  var iconPath = Html.GetCacheBusterPath("/assets/images/icons.svg");
}

<section class="zzz-o-hero">
  <h1>@Model.Heading</h1>
  <img src="@Model.ImageSrc" alt="@Model.AlternativeText">
  <a href="@Model.CtaUrl">
    <span>@Model.CtaText</span>
    <svg viewBox="0 0 19 19" width="19" height="19">
      <use xlink:href="@iconPath#zzz-view"></use>
    </svg>
  </a>
</section>

Special Case for React Components

There is a special case where the file react-loader.0x....js serves as the entry point for all React components using client-side rendering. You only need to include it once in the layout. For the <head> element, use the following method:

<script type="module" src='@Html.GetWidgetAssetPath("react-loader")'></script>

The method will search for any file with a name containing /react-loader.0x and return that file.

The output will be:

<script type="module" src='/assets/js/react-loader.0x4d7d0ab2.js'></script>

Conclusion

By following these guidelines, you can effectively handle hashed assets, manage cache busting, and ensure efficient loading of resources in your web application.