Introduction to Adobe Edge Delivery Services and Document-Based Authoring

What is Edge Delivery Services?

Edge Delivery Services refers to a composable set of services offered by AEM to enable a rapid development environment where new sites can be launched fast and authors can update and publish content quickly.

With Edge Delivery Services, businesses can:

• Create high-impact experiences fast.

• Deliver experiences that drive engagement and conversions.

• Go from editing to seeing the content live in just a few.

• Allow multiple content sources to be used for the same site while streamlining the publishing process independently.

Edge Delivery Services has the following characteristics:

• It is decoupled from the content source and can ingest content from different content sources.

• It uses GitHub so customers can manage and deploy code directly from their GitHub repository.

• The content authored using Edge Delivery Services with AEM as a Cloud Service is persisted in AEM as a Cloud Service.

• It is based around the concept of blocks (AEM provides OOTB blocks, which can be extended to meet specific project needs).

• It can be integrated into an existing AEM project.

• Ensure a perfectLighthouse score.

How to Author Content (Pages) using Adobe Edge Delivery Services?

Edge Delivery Services provides different options for authoring content:

1. The OOTB AEM WYSIWYG authoring capabilities to create content in AEM.

   • Used for creating new pages, Experience Fragments, Content Fragments, etc

   • Provides advanced AEM features like Workflows, Live Copies, Launches, MSM, etc.

2. The Universal Headless Editor for authoring content already created in AEM.

   • The new modern headless UI for authoring content within AEM by dragging-and-dropping blocks.

   • A perfect fit for users that:

     • Prefer WYSIWYG features provided by AEM.

     • Cannot use Sharepoint or Google Drive.

     • Have a headless Native App. Note: the app must be instrumented by a developer to support the Universal Editor.

   • Characteristics:

     • Authors can use default blocks (provided OOTB by Adobe) or customized blocks (developed for a specific project).

     • All changes are persisted to AEM.

     • Still some AEM features of the AEM Page Editor may not be available in the Universal Editor.

3. Document-based authoring (Microsoft Word or Google Docs for example) to create and author content outside AEM but be able to import it into AEM.Document-based authoring allows documents (Google Docs and Word documents) to be translated into website pages (markdown and HTML markup).

   • A perfect fit for users that:

     1. Have content already created in documents.

     2. Require fast content creation and publication.

     3. Need to provide a very easy onboarding for Authors.

     4. Prefer simplicity and do not require the advanced features provided by AEM (Workflows, Live Copies, Launches, MSM, etc).

Document-based authoring:

How does it work?

• Each document represents one page.

• There are different documents for the header and footer.

• Each page’s content is rendered using one main document.

• A document can be included in another document.

• Document path and name are used as URL in browser, except by the landing page.

• The landing of the site corresponds to a page in the root path named “index".

• The path of the landing page corresponds to the main site URL (www.mydomain.com for example).

• To access other documents on the root level of the site (same level as index/landingpage) the route starts with the main site URL (www.mydomain.com/mydoc for example).

• Adobe provides a quick step-by-step tutorial to set up a demo Helix project in case you are interested in a quick hands on experience with Document Based authoring.

How are common documents´ elements converted into HTML?

Regular document elements like lists, headings, font elements, images and videos can be transferred from the initial source into your website.

1. Images will be resized to fit the browser window of the visitor. Any resizing done in Word or Google Docs will have no effect.

2. Videos: with the help of the AEM Slack Bot, you can add videos or large images to your documents.

3. Links: use the absolute, public URL, as internal links will be adjusted to be relative to your website.

4. Metadata and SEO: at the end of the document, create a table like this

Blocks:

Blocks are the fundamental components of a page delivered by Edge Delivery Services. Allows authors to work with more structured content while adding functionality to the site.

1. Structure of a block:

   • Every block is a table

   • Requires a header row (a merged first row containing the block name).

   • Every single table cell after the header row is considered content that may or may nor contain configuration or references

2. In code, some blocks are build out of:

   • CSS if their intent is to provide some styling to a specific type of content

   • Javascript if their intent is to provide an standard behavior for some specific type content

   • Both CSS and Javascript if both applies

3. Developers can change all the .css and .js code to meet specific project needs.

4. There’s a full blocks documentation that explains every current block usage, shows live examples and points to the source code.

5. Boilerplate blocks' source codes are available in the aem-boilerplate project repository.

Structured Data (Spreadsheets):

Structured data allows Spreadsheets (Microsoft Excel workbooks and Google Sheets) to be translated into and delivered as JSON files to be easily consumed by a website or web application.

Naming convention:

1. AEM delivers only sheets whose name starts with helix- prefix.

2. Any sheets not following the naming convention cannot be accessed, which allows to keep additional information that is not expected to be exposed.

Handling multiple sheets:

1. One sheet: the only existing sheet is used as default.

2. Multiple sheets: a sheet query parameter allows to specify the name of one or more sheet names to be retrieved. For example a request like ?sheet=budget2023&sheet=budget2024 will return the JSON representation of the information of sheets named helix-budget2023 and helix-budget2024.

Default sheet:

1. A sheet called helix-default is used by default when there's not additional query parameters supplied to the request.

Other Parameters:

1. offset and limit: Used to indicate which rows are delivered. If limit is not specified, then AEM will return 1000 rows by default.

Spreadsheets are read only, except by two specific files:

1. incoming: is a spreadsheet(Microsoft Excel or Google Sheet document) used by the forms service to ingest submitted data. This file cannot be delivered as JSON.

2. raw_index: used by the index service to write a list of all published pages in a section of the website. This file can also be delivered as JSON.

Example:

1. Let’s say this Google Sheet has been created in the root directory of the Google drive used as content source for Edge Delivery Services for Document-based authoring:

   

2. The adobe-aem-tech-support Google Sheet can be accessed (after been published using the Sidekick) at [your_instace].hlx.live/adobe-aem-tech-support.json and this will be it's corresponding JSON output:

{
  "total": 3,
  "offset": 0,
  "limit": 3,
  "data": [
    {
      "AEM Version": "6.3",
      "CurrentlySupported?": "No",
      "End of core support": "4/30/2020"
    },
    {
      "AEM Version": "6.4",
      "CurrentlySupported?": "No",
      "End of core support": "4/30/2021"
    },
    {
      "AEM Version": "6.5",
      "CurrentlySupported?": "Yes",
      "End of core support": "N/A"
    }
  ],
  ":type": "sheet"
}

How to Publish pages Using the AEM Sidekick?

The AEM Sidekick is required to publish documents to the AEM as a Cloud instance. Adobe provides three installation options to choose from.

Note:

• The root page of a site can be accessed at [your_instance].hlx.live and all documents of the site can be accessed by path using this root URL as prefix.

• It’s not required to publish a document to see changes reflected. Any document can be previewed using the Sidekick plugin. For example, changes made to the root page of a site can be previewed at [your_instance].hlx.page. This is helpful to share content with stakeholders even before it has been published.

Wrap Up

Adobe Edge Delivery Services has provided different ways to Author content. Document-based authoring, in particular, allows users to use well known tools such as Microsoft Word or Google Docs to create and author documents that can be easily converted into web pages of a website hosted in AEM as a Cloud. In the same way, document-based authoring allows the use of well known Spreadsheets as data sources to be consumed as JSON files. 

By doing this, Adobe empowers authors to own site content and create high-impact experiences that drive engagement and conversions while allowing them to easily share content that can be previewed and published with just one click using the AEM Sidekick.