How embedding works
Content Block Embedding is mainly handled in the Publishing API, with some shared code in the Content Block Tools gem detailed in the diagram and steps below:
flowchart-elk TD;
subgraph Publishing App
A(Save draft)
L(Publish Saved Draft)
end
subgraph Content Block Manager
P[Content Block updated]
end
subgraph Publishing API
A --> B(Host Document sent to PUT content endpoint)
B --> C(Embedded Content Finder Service is called)
C --> D(Iterates through details to find embedded content blocks)
D --> E(Content Block Tools finds all Content Block References)
E --> F(References passed back to Service)
F --> G{Live editions found?}
G -- Yes --> H(Create embed link for Host Document)
H --> I(Send Downstream to DownstreamDraftJob)
I --> J(DownstreamPayload calls EditionPresenter)
J --> K(ContentEmbedPresenter replaces embed codes with relevant content)
L --> M(DownstreamDraftJob and DownstreamLiveJob executed)
M --> J
P --> Q
Q(Publishing API calls send_downstream to DownstreamLiveJob) --> R(DownstreamLiveJob calls HostContentUpdateJob)
R --> S(Fetch all linked documents)
S --> T(Republish linked documents)
T --> J
T --> U(Create event to record republished documents)
end
Adding embed code to a host document
Saving a draft
When saving the changes to a Host Document, we trigger an update of the draft Content Store:
The publishing app updates the Host Document via the PUT content endpoint in Publishing API
The Embedded Content Finder Service is called.
The service then iterates through the
details
of an Edition to pass it to the Content Block Tools to find any embedded content blocksContent Block Tools finds all the Content Block References and passes them back to the Service.
If live editions are found of the references, then a link of type
embed
is created for the Host Document with thecontent_id
of the embedded block.Once the links have been created, the Publishing API calls
send_downstream
to send to theDownstreamDraftJob
.The Downstream job then calls, via
DownstreamPayload
, anEditionPresenter
, which eventually gets to theContentEmbedPresenter
The
ContentEmbedPresenter
then looks for anyembed
Links and replaces any embed codes with the relevant content for the latest live edition of the Block.
Publishing a saved draft
Once the draft is saved, the publishing app makes a subsequent call to the Publishing API to publish:
The Publishing API calls
send_downstream
to send to theDownstreamDraftJob
andDownstreamLiveJob
.The Downstream jobs then call, via
DownstreamPayload
, anEditionPresenter
, which eventually gets to theContentEmbedPresenter
The
ContentEmbedPresenter
then looks for anyembed
Links and replaces any embed codes with the relevant content for the latest live edition of the Block.
Updating a content block
When a change to a content block is published, we trigger the following process in Publishing API:
The Publishing API calls
send_downstream
to send to theDownstreamLiveJob
.The Downstream job then calls the
HostContentUpdateJob
(which is a subclass ofDependencyResolutionJob
The Host Content Update job then fetches all the linked documents
Each of the linked documents is then republished. This kicks off the process outlined in Publishing a saved draft to re-render the page and send the new version to the Content Store.
The Host Content Update job also creates an Event to record that the linked document was republished by a change to a content block. This can be used by publishing apps to track changes to a content block. See tracking when a content block changes for more.