Developer Guide to Document Authoring with Edge Delivery Services. Part 2

Creating variations of our block

Automating Author Name from Alt Text

Place text to the right of BIO

Use of fragments

Theming

This post continues my Developer’s guide to Document Authoring with Edge Delivery Services.

Previously

We created a Google Doc called ‘Hello World’. It has a hero and a bio block, with the line of text “Hello World From Edge Delivery Services.”

We added a metadata table at the bottom of the document, and the entries became metadata on the final web page.

We added JavaScript to the hero block to allow the hero to contain two distinct images: one for mobile and one for desktop. The picture element selected these depending on the viewport size. We created the bio block from scratch, with styling to create a circular overlay and to pick up the author's name from either the alt tag in the img element and, if not present, obtain the author’s name from the author meta element from the page. We added a class name ‘highlighted’ to our Bio block and the CSS to put an outline on the image.

Continuing the journey

Our manager has asked that we follow the image with some text with brief biographical details, including the author's name. Thus, we no longer need the author's name automatically provided underneath the picture. This is another variation.

The cell in the block name is currently Bio (highlighted). The word bio is the block name and also the class name used to create the element and its wrappers; looking at the rendered HTML in the browser after Edge Delivery Services has run, one of the first things to note is that the blocks we created have been rendered in a div with a section class.

The div also has classes for each block in the document, postfixed with -container. There is a data-section-status class that is adjusted by edge delivery and, finally, an empty style; we will return to section styles later. Further down, we see the bio-block

<div class="bio-wrapper">
  <div class="bio highlighted block" data-block-name="bio" data-block-status="loaded">
    <div>
	<div>
	  <picture>
	    <source type="image/webp" srcset="./media_145e13ea388af99109b4e34d2c57d40f5fc22d9c9.jpeg?width=2000&amp;format=webply&amp;optimise=medium" media="(min-width: 600px)">
	    <source type="image/webp" srcset="./media_145e13ea388af99109b4e34d2c57d40f5fc22d9c9.jpeg?width=750&amp;format=webply&amp;optimize=medium">
	    <source type="image/jpeg" srcset="./media_145e13ea388af99109b4e34d2c57d40f5fc22d9c9.jpeg?width=2000&amp;format=jpeg&amp;optimize=medium" media="(min-width: 600px)">
          <img loading="lazy" alt="Author: Tom Cranstoun" src="./media_145e13ea388af99109b4e34d2c57d40f5fc22d9c9.jpeg?width=750&amp;format=jpeg&amp;optimize=medium" width="198" height="198">
        </picture>
	</div>
  </div><strong>Author: Tom Cranstoun</strong> </div>
</div>

In the snippet of HTML, the block is decorated with a -wrapper <div class="bio-wrapper">, and the next div is decorated with the block name ‘bio’ and the variation ‘highlighted’ along with a ‘block’ class.

All blocks are decorated this way: block name, variations applied and then ‘block’. This makes it easy to target slices of the HTML using classes; Edge Delivery Services does not use IDs.

Hiding the auto-generated author-name

Our task is to hide the author, so adding a new class name, “hide author”, is done by adding a second phrase after a comma within the brackets. All spaces in the block/styling phrase are replaced with hyphens (-)

Investigating the rendered HTML.

We can adjust the CSS or JS to make this class work. I chose to adjust the javascript, adding a test for the non-existence of the class ‘hide-author.’

if (!bioElement.classList.contains("hide-author")) {

…. Original code

}

The final Javascript function

export default function decorate(block) {
  const bioElement = document.querySelector(".bio");
  if (!bioElement.classList.contains("hide-author")) {
    // Find the <img> element within the .bio.block
    const imgElement = document.querySelector(".bio.block img");
    let author = "";
    // Check if the <img> element has a non-empty alt attribute
    if (imgElement && imgElement.getAttribute("alt")) {
      author = imgElement.getAttribute("alt");
    }

    // If the alt attribute is empty or not present, fall back to the <meta> tag's author content
    if (!author) {
      const metaAuthor = document.querySelector('meta[name="author"]');
      if (metaAuthor) {
        author = metaAuthor.getAttribute("content");
      }
    }
    // Create a new <strong> element to hold the author name
    const authorElement = document.createElement("strong");
    authorElement.textContent = author;
    // Find the .bio.block element
    const bioBlock = document.querySelector(".bio.block");
    // Insert the author element as the last child of the .bio.block element
    bioBlock.appendChild(authorElement);
  }  
}

Place the text to the right.

The next task was to allow text to the right of our bio picture. Insert a new column, merge the title and add the text.

Previewing could be better; the text is underneath.

It looks OK, but we wanted something else. We want the text to be to the right. Adding CSS to bio.css to involve a flex layout does the trick.

.bio-wrapper .bio.block img {
border-radius: 50%;
object-fit: cover;
}
.bio-wrapper .bio.block.highlighted img {
border: 2px solid blue;
box-sizing: border-box;
}

.bio>div {
    display: flex;
    align-items: center;
    gap: 20px;
}

.bio>div>div:first-child {
    flex-shrink: 0;
}

.bio>div>div:last-child {
    flex-grow: 1;
}

We adjusted the first and last child of the DIVs to make it work.

Reusing content

Content Management Systems often reuse pieces of text and assets; Edge Delivery Services include this functionality; these are called fragments.

I create fragments in a folder called fragments in my Google Drive. We want boilerplate text at the foot of our pages, similar to the ‘Want to know more’ at the bottom of these articles.

We create the fragment.

And add the content

We need to include this fragment in our page by adding a fragment block with the path of the fragment.

When previewed, we can now see the fragment on our page.

The ‘want to know more’ fragment is displayed on the page; it is interesting to see how Edge Delivery Services provides this snippet; we inspect the network traffic.

This time, you can see the fetch/xhr content in my filter, and the fragment component asked for want-to-know-more-plain.html instead of Edge Delivery providing a page with styling, javascript, <body>, <main>, etc.; it just provided the raw HTML in a div ready for adding to the page; where it will inherit the styling and context of the page.

Looking more carefully, you wiil also see footer.plain.html and nav.plain.html

These are ‘auto fragments’ generated from the footer and nav documents placed in the root folder of Google Drive. This gives the website a consistent set of headers and footers.

I want my allabout.network to be focussed on telling people ‘all about’ something, such as this tutorial, without third-party distractions. Therefore, I have also chosen not to have footers or navigation; you can easily create your navigation and footers and have them auto-included as fragments.

Styling the pages

There are three ways to style your pages.

Use the default autoblock style.

Change nothing; get the style verbatim from styles.css. You can view and change the styles in styles.css for your project. Note that the style sheets in Edge Delivery use CSS 3 with variables; it does not require bundling, compiling, or transpilation.

Use a theme

After applying the theme's name to your metadata table, Edge Delivery Services will apply the theme class to the body. Then, you can change the styling for this page using the theme as a modifier; for instance, a newsletter page could have a theme of ‘newsletter’; as I am writing an article, I will give this page a theme of ‘article’.

Edge Delivery Services applies the theme class to the body element.

One can use different styles on this page, such as margin padding.

body {
  font-size: var(--body-font-size-m);
  margin: 0;
  font-family: var(--body-font-family);
  line-height: 1.6;
  color: var(--text-color);
  background-color: var(--background-color);
  display: none;
}

body.article {
  padding-left: 50px;
  padding-right: 50px;
}

Note that the body class has a display: none; when Edge Delivery finishes loading the page, it changes the display attribute by adding a class “appear” with a display “block”

Use sections

Sections are parts of the page; they are marked by ‘---’ 3 hyphens on a line by themselves and have a section metadata table.

Preview the page

The rendered HTML for a section looks like this:

<div class="section bg-dark" data-section-status="loaded" data-description="This is a dark background section" style="">
  <div class="default-content-wrapper">
    <p>This part of the page is in a section marked by three hyphens: ‘--—’ as a line at the start of the section and three hyphens as a line by themself at the end of the section. You can see them in this document section.</p>
    <p>If you want to modify the section, place a section metadata table with style or other attributes at the foot of the section.<br><br>The style key applies the style name to the section,</p>
    <p>The description and other metadata entries are placed inside the HTML.</p>
  </div>
</div>

The description metadata is used as a data-description attribute in the section div. You can use these data descriptions to decorate the HTML further, but this will be custom code.

/fragments/ddt/proposition

style

bg-dark

The Hello World page is here.

https://allabout.network/blogs/ddt/hello-world-2

Return to Top