Resources

AMP Publisher Blocks User Manual

by CreatorFeb 19, 2021

The Blocks

• Side-by-Side : Blocks with a main object and content object that display side-by-side with responsivity options for mobile mode. These blocks are designed for root level usage. They support the WordPress suggested “full” and “wide” alignments (and more) when accompanied by the Accelerate theme.
  • Call to Action Box : CTA box object with text fields and button beside a content object with Title and a Nested content area.
  • Image Inset : Inset image with overlapping content object with a Title and Nested content area.
  • Media Split : Video or social media embed object beside a content object with Title, Subtitle and a Nested content area.
  • Table of Contents : Automated table of links to heading blocks found in page content beside a content object witha Nested content area.
  • Testimonial : Image object beside a content object with Title, Subtitle and Testimonial object using a nested content area.
• DOM Blocks : DOM Blocks can be be combined to make truly dynamic blocks within a block editor designed for single-purpose. Basically they make you the architect for the block’s DOM (document object model). All DOM blocks are designed to be used as children of other blocks, but they work equally well at the root level.
  • DOM Object : This is the backbone of the DOM block system. It includes advanced options for layout and child object handling using CSS Flexbox tech and parent-to-child styling options.
    • DOM Object : I list it again to demonstrate that it is equally parent and child. When in doubt, put it in a DOM Object block.
    • DOM Text : Text field with styling options.
    • DOM Media : Video or social media embed object.
    • DOM Button : Button or link object with options for inheriting button styles ro customizing your own.
    • DOM Card : Stylized card with a tab, title and nested content area.
• Utility : We have a number of purpose-built blocks that can give your AMP site some more advanced tech.
  • AMP-Accordion : The amp-accordion component interfaced through heading and paragraph blocks. An accordion is a block of title bars with hidden content you can toggle open/closed.
  • FAQ Structured Data Block : A question and answer block that generates data used by Google to list the questions and answers in their search results for the page. It can be available on the page, used in an accordion, or hidden as a data object only.
  • PopUp Block : A pop-up window with a title and nested content area over a semi-transparent background overlay. It is triggered open by buttons and links on other AMP Publisher blocks.
  • Infographic Code Block : Share an image on your site with a code box allowing your visitors to copy/paste the HTML code on to their site, with link and attribution back to the source page on your site.
• Accelerate Theme : The theme comes with it’s own blocks that support sitewide settings and theme features.
  • Accelerate Categories : Display categories with a variety of layouts, styles and content options.
  • Accelerate Posts : Display posts with a variety of layouts, styles and content options.
  • Accelerate Spacing : Separate content using a sitewide setting for it’s height. This is a direct repacement for the WP Spacing block in which you have to enter a value every time.

Block-Set Import & Export

You can save AMP Publisher block styling and content as an archive in your site’s database, then import it into other pages or even other sites. This can be useful for reusing blocks that you have created, versioning edits of a block you are working on, or backing up blocks to your local machine. This feature goes beyond the blocks you have in your databse by giving you access to pre-made blocks hosted from our API. Just download a block and start editing. When you download a Block-Set from the API, any images used in it are automatically inserted into your Media Libray. After you download a block you can save it to your database before or after you have edited it. Click here for a tutorial on using Block-Sets.

The Basics

Using our blocks is no different than any other block with one major exception… our blocks are “dynamic”, meaning they are generated by PHP upon page loading rather than being saved as static HTML. This allows for a much more robust group of options, better programming techniques, and most importantly the ability to update a block without causing YOU to jump through the “deprecated block” hoops (thanks WP).

In addition to their base functionality, AMP Publisher blocks have many styling options packed into every level of their DOM: margins, padding, borders, shadows… and more. This gives you the option of creating two entirely different looks from the same block. For the sake of clarity, let me explain a few terms commonly used in our blocks.

What is a “DOM”?

Document Object Model is a programming interface for HTML and XML documents. We use the term “DOM” whenever we are speaking about the hierarchical structure of an HTML object. (an object is a tag: p, h1, div, span… etc) Within that object is text and/or other objects. Within those objects is text and/or objects. You see the pattern.

What is a “node”?

A node is a level of the DOM hierarchy. Each object is a node (XML term) in this structure. Our blocks are rendered as a singular object with child nodes making up it’s DOM. The root node is the outermost HTML tag in this DOM. We usually use the term “node” to describe targets for styles and settings within a block, as not every object is a target especially with nested blocks… but technically every object with a tag is a node.

What is a “nested” block?

Some blocks, and almost all of ours, allow nesting of other blocks within them, we refer to these children as “nested”. Our blocks have styles that are applied to their node, but the way CSS works is to have children inherit most of their parent’s styles. If you color the block text then all objects in that block will inherit that color, unless they too haev a color assignment. Most of our blocks have styles that can be assigned to their nested content area, which is it’s own node. Any blocks nested into that block will inherit the blocks styles, and the content node styles.

So for example, take the Media Split block. I will explain it’s DOM structure as a nested list:

• root object (div) targeted node from Block Settings panel : You may assign style settings that apply to this entire block.
  • internal wrapper (div) untargeted node : Used to support theme full-width options for banners. Most of our blocks have one of these wrappers. It has no styling of it’s own, it’s children are the block’s children.
    • media wrapper (div) targeted node from Media Settings panel : This is a wrapper node to which we apply styles and media object specific rules. It’s children are a series of objects that display either an AMP friendly image or media embed. It’s children will inherit it’s styles, so we only allow certain styles in this node.
      • internal wrapper (div) untargeted node : Used to apply rules for caption placement and responsivity.
        • media object (amp-img or embed) : untargeted node : This is the actual amp component that creates the image or embed object.
        • caption (div) targeted node from Caption panel : This node includes a text field and has standard node styling options in addition to position and margin settings
    • content wrapper (div) targeted node from Content Wrapper panel : This node contains the block title, subtitle and content area so it can be set side-by-side with the media object. Styles applied to this node will be inherited by all children, including nested children and will override the same style applied to the block at root level.
      • title (div) targeted node from Title panel : Single text field, text is edited in the block not in the panel. Styles targeting this node only apply to the title, and will override the same style applied to the block and/or content wrapper.
      • subtitle (div) targeted node from Subtitle panel : same as title
      • content (div) targeted node from Nested Content panel : This node is where you may enter basic text as paragraph blocks (just type) or insert other blocks. Styles applied to this node are inherited by it’s children and it follow suit with previously explained cascading.
        • wp nested wrapper (div) untargeted node : This node is generated by Gutenberg around nested content, we sometimes use it when layout rules need to be applied. Follow suit with the internal wrapper.
          • nested blocks (?) untargeted nodes : Anything put into the nested content area. Each block may have it’s own style rules, some core blocks do. Styles applied to a child “should” be able to override the same style cascaded to it from above. I use the word “should” because we only have control over our own blocks and how styles are applied to them, core and outsider blocks have their own methods.

So there you go, a complicated hierarchy of objects and styles… that is how our blocks are designed, because that is HTML. I didn’t mention our common utility nodes, the difference between the editor DOM an the rendered DOM, nor how classes can be applied to blocks that allow CSS to be applied from stylesheets.

Styling the Nodes

You know what a node is, you know that you can style it… now what? I’ll keep using the Media Split as the example since it is the most commonly needed block in our suite.

The following is an example of basic usage of node styling. [block settings explained]

• root [Block Settings] : light blue background color, black box shadow, 30px padding, middle vertical alignment, 30px top and bottoms margins
  • content [Content Wrapper] : dark blue font color
    • title [Title] : white font color with black text shadow
    • content [Nested Content] : white background color, 10px padding, black border color with 10px rounded corners, 20px top margin

Media Split Block

The image chosen for this block is a square. This creates a larger vertical space to illustrate the content vertical alignment feature.

Paragraph block with some text in it. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed tristique tincidunt augue ullamcorper ultricies. Curabitur lectus felis, dapibus non vulputate id, imperdiet a tellus.

Another paragraph block with a little more text and red text color applied to it.

• List block with a few dummy items
• dummy item
• dummy item

In this example you see the core paragraph block text color override it’s inherited text color. The title overrides the dark blue as well, if any parent had assigned another text shadow color, the title shadow would still be black. Our blocks do not add vertical margins on their own, you must set them yourself if you wish to use them to create space between them and text or other blocks. The example also shows basic usage of settings to create a standout block with a content area with seperation from the rest of the textual side. I applied a vertical alignment to illustrate that feature and to transition to an explanation of image usage.

Image object vs image as background

Sometimes we implement an image as an image object, which normally is rendered as the “img” tag, but in amp it must be the “amp-img” tag. This is not important to you, but it is extremely important and limiting to us. We use and image object when it’s siblings need to be affected by it’s height for responsivity. We use an object (div) with an image as it’s background when the height is determinate or when the siblings do not need to be affected by it’s height ecause it offers more flexibility in styling and responsivity as well as avoiding issues with AMP-IMG rendering. I mention this because our example (Media Split) uses an image object, but most of the images in our other blocks use background. This is how we are able to make the textual area align vertically against a tall image in it’s true aspect ratio.

The next example is the exact same block with only two changes: I set the block alignment to “Full Content Aligned” and set the Image Height by Pixels to 300px. In doing so the block becomes a banner with it’s background color reaching the browser edge and it’s content aligned to the page’s content. By setting an image height that is shorter that the text area it aligns vertically against the text.

• root [Block Settings] : Full Content Aligned block alignment
  • image [Media Layout & Styling] : set Image Height by Pixels to 300px

Media Split Block

The image chosen for this block is a square. This creates a larger vertical space to illustrate the content vertical alignment feature.

Paragraph block with some text in it. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed tristique tincidunt augue ullamcorper ultricies. Curabitur lectus felis, dapibus non vulputate id, imperdiet a tellus.

Another paragraph block with a little more text and red text color applied to it.

• List block with a few dummy items
• dummy item
• dummy item

In this next example we change a few more settings. Just a few changes make a huge difference in what you see.

• root [Block Settings] : assigned a background image (wide format images work best for this, but it will crop to fit any image)
  • image [Media Layout & Settings] : white border color, 8px border width, double border style

Media Split Block

The image chosen for this block is a square. This creates a larger vertical space to illustrate the content vertical alignment feature.

Paragraph block with some text in it. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed tristique tincidunt augue ullamcorper ultricies. Curabitur lectus felis, dapibus non vulputate id, imperdiet a tellus.

Another paragraph block with a little more text and red text color applied to it.

• List block with a few dummy items
• dummy item
• dummy item

Notice the subtitle text color makes it hard to read now, so let’s add something to make it stand out. Also, the square corners of the image do not match the rounded corners os the content window. I applied the same styles to the subtitle as the title to offset it from a darker background.

• image [Media Layout & Settings] : 10px border rounding
• subtitle [Subtitle] : white font color and black text shadow

Media Split Block

The image chosen for this block is a square. This creates a larger vertical space to illustrate the content vertical alignment feature.

Paragraph block with some text in it. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed tristique tincidunt augue ullamcorper ultricies. Curabitur lectus felis, dapibus non vulputate id, imperdiet a tellus.

Another paragraph block with a little more text and red text color applied to it.

• List block with a few dummy items
• dummy item
• dummy item

Using DOM Blocks

DOM blocks are are a suite of blocks meant to be combined into a custom block. Take the nodes and break them into nesting friendly mini-blocks. Each DOM block can be used in the root level, it will just do what it does inline with the blocks above and below it. To create a custom block, you start with the DOM Object (objects are nodes). Click here for a full tutorial on using DOM blocks.

The DOM Object is a wrapper div tag that allows any block to be nested within it. This allows you to put custom styling around another block. You can use create a full-width banner with any outsider block you wish. But where it excels is when it is combined with the other DOM blocks.

• DOM Object : The base of all DOM blocks. It is a styled node, it has root-level options (like full-width) and it has special handling for flex-box display for it’s children.
  • DOM Object : Yes, I list it again because it also works as a child block with special handling in that state.
  • DOM Text : A simple text field with “Text – Font” style settings. If you want to style it as an object, you put it in a DOM Object and style that.
  • DOM Media : Simple image or media embed with “Caption” options (see Media Split).
  • DOM Button : Simple button that uses the link and button settings (see Call to Action Box).
  • DOM Card : A card-style block with a tab, title, and content area that is designed to use the DOM Object’s flex-box mode to create a row of “cards”. You might use them to display categories, compare plans, or hilight products.

Start by inserting a DOM Object. You can enter some text and style the block.

• root [Block Styling] : blue background, 25px padding, black border, 10px border width, 50px border radius
• root [Text / Font] : 20px font size, center text alignment

The text in this block inherits the font size. You override this directly in any paragraph block.

• root : no changes
  • paragraph 1 : no changes
  • paragraph 2 [Color settings] : 14px font size, white font color, black background

The paragraph block settings are minimal, if you wish to do more with it, then you would delete the paragraph block and insert a DOM Object instead. When you type you will end up with a paragraph block nested into the child DOM Object.

• root : no changes
  • paragraph : no changes
  • DOM Object (child) : 14px font size, white font color, black background as before… also added : Lucida Console font family, blue border, 3px border width, dotted border style, 16px padding, white box shadow inset and doubled
    • paragraph : no settings, everything is either styled on the parent or inherited from it

Now we add other DOM blocks to the child DOM Object: an image using the DOM Media block to allow custom borders and shadows, a DOM Text with it’s own font styling, and a basic button as a URL link.

• root : no changes
  • paragraph : no changes
  • DOM Object (child) : no changes
    • paragraph : no changes
    • DOM Image : image with 10px white double border, light blue box-shadow
    • DOM Text : 20px font size, light blue font color, Verdana, bold, italic
    • DOM Button : standard button class, link to home page, 20px top margin

The DOM Object can nest any block, not just DOM blocks or AMP Publisher blocks… the possibilities are endless. It also has options for styling and handling it’s children as “flex items” which can display them in a grid using columns and rows which become responsive to the browser/device width. Like the DOM Object, our advanced blocks also allow children including the DOM Object itself, almost any combination of blocks can be achieved.