Using blocks in injectables
Pointing an injectable at a block, stacking several blocks, laying them out with wrapper HTML, filling in variables, and what happens when the block changes later.
There are two ways an injectable uses blocks, and a Blocks injectable can also be plain HTML with no block at all.
One block as the whole content
In the injectable form's Content card, set Content source to the block instead of Inline content. The picker lists every active block by name; archived blocks are not offered, and the picker only appears once the store has at least one block.
The editor is replaced by a note: This injectable renders the selected block. Editing the block updates every injectable referencing it; this form only picks which block to use. A mega menu can point a submenu block at a saved block in the same way.
The live preview card is not shown for a block-backed injectable. See Styling and preview.
A stack of blocks
Choose the content type Blocks. The stack editor, Stack (top to bottom), has Add block to append a block and Create a block to make a new one without leaving the page. Drag to reorder. A stack holds a limited number of blocks (see Limits), and a block you have hidden still counts.
Each copy in the stack lists the block's variables. For every variable the copy either follows the block, using the block's default, or is set here, with its own value. The row's summary reads, for example, Overrides 2 of 5, and Reset all drops every override on that copy.
Laying the blocks out yourself
Leave the Wrapper HTML & CSS section blank and the blocks show one after another in stack order. To lay them out yourself, write the HTML around them and place each block where it should appear with a {{> name }} placeholder. Each copy in the stack has a placeholder name you can change; Insert block drops the placeholder for a copy at the cursor and names the copy if it has no name yet. A copy the wrapper places shows a Placed ×N badge.
The wrapper CSS is scoped to this injectable, so its plain selectors cannot affect the rest of the storefront page; each placed block keeps its own scoped CSS as well. @keyframes, @font-face and @page stay as written and apply to the whole page; @import is removed. Wrapper HTML is limited to 100,000 characters and wrapper CSS to 50,000.
Saving checks the wrapper:
- A placeholder that is not written as
{{> name }}, or one that names no block in the stack, refuses the save and quotes the placeholder. - A wrapper that places none of the stacked blocks, a block in the stack the wrapper never places, or a placed block that is archived or missing, lets the save through with a caution. In the first and last cases nothing shows on the storefront until you fix it.
- Writing a block's name as a variable,
{{ name }}instead of{{> name }}, is pointed out in the editor: the storefront would treat it as data and never place the block.
Wrapper HTML with no block
With no block in the stack and no {{> }} placeholder of any kind, the wrapper HTML alone is the injectable. That is the way to publish a small piece of HTML with a couple of editable values without creating a block first. The stack pane says so while it is empty, and the preview shows the wrapper HTML.
Your own variables
The Template variables section below the wrapper holds the injectable's own {{name}} values, the same name and value pairs a Template injectable has: up to 50 of them, each value up to 2,048 characters. They work in the wrapper HTML, as do the visitor details from the Insert variable menu in the wrapper toolbar; they do not work in CSS. These values are filled in on the loader script and BigCommerce widget routes only; a server-rendered injectable or a static page shows the placeholder text as written, so keep such an injectable on one of the first two routes. Blocks in the stack still take their values from their own variable rows, described above.
External CSS
The External CSS section at the bottom applies to the whole storefront page, like the External CSS tab of a Custom HTML & CSS injectable (see Content types): it can restyle any element, including your theme's header, footer or checkout; comments, @import and @charset are removed and broken rules are dropped; variables do not work in it; up to 50,000 characters. Keep rules meant only for this injectable in the wrapper CSS, which is scoped. It is served only when the Blocks injectable is delivered as its own body; a block referenced from elsewhere never carries page-wide CSS. The preview holds only this injectable, so page-wide changes show only on the storefront once saved.
When the block changes later
Saving a block updates every injectable that uses it. Active injectables pick the change up within about a minute; you do not republish them. An injectable delivered as a widget is nudged so the change lands within seconds rather than at the next scheduled sync.
In a stack, copies that follow the block take the new default; copies that are set here keep their value. When a default changed recently, the stack editor points it out with notes such as Follows the block · changed (date) (was old value) and set here · Block default is now new value, and offers Keep this value, Follow the block again, Use the new default or Use the default. A variable the block no longer declares shows Remove. A variable that is now required but has no value on a copy says needs a value · The block has no default for this.
The Used by panel
Under the block form, the Used by panel shows where the block is used:
- A summary line, for example Used by 3 injectables · 5 places.
- One row per injectable that is not archived: its name, status, what it overrides, an Open link and a See differences disclosure.
- Compare all: a table of every variable's value across the injectables that stack this block, where follows means the injectable uses the block's value.
- Per variable, Reset '(name)' in N injectables…, which makes those injectables follow the block again, with a confirm and an Undo. Undo may restore only some values if a copy was removed, the value no longer fits, or another save happened in between; the message says how many it restored.