Sidekick Library

` tags, with the outermost `

` carrying the block's name as a CSS class. Inner `

` elements represent rows and columns of content entered by the author. This example shows a single-cell block containing a paragraph. ```HTML

Hello, World.

``` -------------------------------- ### SharePoint Website Root URL Format in fstab.yaml Source: https://www.aem.live/docs/setup-customer-sharepoint This snippet shows the general URL format required for configuring the SharePoint website root in the fstab.yaml file. It specifies the tenant, SharePoint site, and the path to the website folder within Shared Documents. This URL is crucial for AEM to correctly mount the SharePoint content. ```YAML https://.SharePoint.com/sites//Shared%20Documents/website ``` -------------------------------- ### Creating Enterprise Application via PowerShell Source: https://www.aem.live/docs/setup-customer-sharepoint This PowerShell snippet shows how to create an Enterprise application. First, it connects to Microsoft Graph with the necessary 'Application.ReadWrite.All' scope. Then, it uses 'New-MgServicePrincipal' to create the service principal, specifying the 'AppId' and adding the 'WindowsAzureActiveDirectoryIntegratedApp' tag to ensure visibility in the Azure UI. ```PowerShell PS> connect-MgGraph -Scopes "Application.ReadWrite.All" PS> New-MgServicePrincipal -AppId e34c45c4-0919-43e1-9436-448ad8e81552 -Tags WindowsAzureActiveDirectoryIntegratedApp ``` -------------------------------- ### Configuring robots.txt for Sitemap Discovery Source: https://www.aem.live/docs/go-live-checklist This snippet illustrates a standard `robots.txt` configuration. It grants all user agents permission to crawl the entire site and explicitly declares the URL of the sitemap, which is vital for search engine optimization (SEO) as it helps search engines efficiently discover and index the website's content. This configuration is essential for ensuring proper indexing and avoiding duplicate content issues. ```robots.txt User-agent: * Allow: / Sitemap: https:///sitemap.xml ``` -------------------------------- ### Assigning Sites.Selected Application Role using PowerShell Source: https://www.aem.live/docs/setup-customer-sharepoint This PowerShell script assigns the 'Sites.Selected' application role to a specified enterprise application's service principal. It first retrieves the service principals for the target application and Microsoft Graph, then finds the 'Sites.Selected' app role ID, and finally creates the app role assignment. Remember to replace `$ObjectId` with your enterprise application's ID. ```PowerShell $ObjectId = "abcdef-1234-49b6-b660-cc85b34fe516" <<------ replace with your enterprise app id $AAD_SP = Get-AzureADServicePrincipal -SearchString "Microsoft Graph"; $AAD_SP $MSI = Get-AzureADServicePrincipal -ObjectId $ObjectId if($MSI.Count -gt 1) { Write-Output "More than 1 principal found, please find your principal and copy the right object ID. Now use the syntax $MSI = Get-AzureADServicePrincipal -ObjectId " Exit } $AAD_AppRole = $AAD_SP.AppRoles | Where-Object {$_.Value -eq "Sites.Selected"} New-AzureADServiceAppRoleAssignment -ObjectId $MSI.ObjectId -PrincipalId $MSI.ObjectId -ResourceId $AAD_SP.ObjectId[0] -Id $AAD_AppRole.Id ``` -------------------------------- ### Basic AEM Sidekick Configuration in JSON Source: https://www.aem.live/developer/sidekick-development This JSON snippet shows a basic `config.json` structure for customizing the AEM Sidekick. It allows setting a project name and defining an empty array for plugins. This file should be placed at `/tools/sidekick/config.json` in your project's GitHub repository. ```JSON { "project": "My project", "plugins": [] } ``` -------------------------------- ### Configuring a Standard Palette AEM Sidekick Plugin (JSON) Source: https://www.aem.live/developer/sidekick-development This JSON configuration sets up a URL-based plugin for AEM Sidekick that opens its target URL ('/tools/sidekick/foo-palette.html') within a floating palette instead of a new browser tab. The `isPalette` property is set to `true` to enable this behavior, creating a standard palette. ```JSON { "plugins": [ { "id": "foo", "title": "Foo", "url": "/tools/sidekick/foo-palette.html", "isPalette": true } ] } ``` -------------------------------- ### Creating Enterprise Application via MSGraph API Source: https://www.aem.live/docs/setup-customer-sharepoint This snippet demonstrates how to create an Enterprise application using a POST request to the Microsoft Graph API's servicePrincipals endpoint. It includes the 'appId' and the 'WindowsAzureActiveDirectoryIntegratedApp' tag, which is necessary for the application to be visible in the Azure UI. The 'Content-type' header specifies JSON for the request body. ```HTTP POST https://graph.microsoft.com/v1.0/servicePrincipals Content-type: application/json { "appId": "e34c45c4-0919-43e1-9436-448ad8e81552", "tags": [ "WindowsAzureActiveDirectoryIntegratedApp" ] } ``` -------------------------------- ### Configuring a Container AEM Sidekick Plugin (JSON) Source: https://www.aem.live/developer/sidekick-development This JSON configuration demonstrates how to create a container plugin named 'Tools' using `isContainer: true`. It then places another plugin, 'Foo', inside this container by setting its `containerId` to 'tools'. Container plugins group related functionalities, saving space in the toolbar and toggling a dropdown when clicked. ```JSON { "plugins": [ { "id": "tools", "title": "Tools", "isContainer": true }, { "id": "foo", "containerId": "tools", "title": "Foo", "event": "foo" } ] } ``` -------------------------------- ### Displaying AEM CLI General Help Source: https://www.aem.live/developer/cli-reference This command displays the general help information for the AEM CLI, listing all available top-level commands and global options. It's useful for quickly understanding the CLI's capabilities. ```Shell $ aem --help ``` -------------------------------- ### Adding Write Permissions to SharePoint Site using Microsoft Graph API Source: https://www.aem.live/docs/setup-customer-sharepoint This POST request to the Microsoft Graph API adds write permissions to a specific SharePoint site using its previously obtained SiteId. The request body specifies the 'write' role and grants it to a defined application identity, identified by its ID and display name. Site Admin permissions and additional 'Sites' scopes consent are prerequisites. ```HTTP POST https://graph.microsoft.com/v1.0/sites/adobeenterprisesupportaem.sharepoint.com,03cc3587-0e4d-405e-b06c-ffb0a622b7ac,5fbc1df5-640c-4780-8b59-809e3193c043/permissions Content-type: application/json { "roles": [ "write" ], "grantedToIdentities": [ { "application": { "id": "83ab2922-5f11-4e4d-96f3-d1e0ff152856", "displayName": "AEM Content Integration" } } ] } ``` -------------------------------- ### Configuring a Badge AEM Sidekick Plugin (JSON) Source: https://www.aem.live/developer/sidekick-development This JSON configuration creates a 'Stage' badge plugin for AEM Sidekick, which is rendered as a decorative label on the right side of the toolbar. The `isBadge` property is set to `true`, and the `environments` array specifies that this badge should only appear in the 'preview' environment. Badges are not clickable and serve a purely informational purpose. ```JSON { "plugins": [ { "id": "stage", "title": "Stage", "isBadge": true, "environments" ["preview"] } ] } ``` -------------------------------- ### Adding AEM Content Integration Service Principal using PowerShell Source: https://www.aem.live/docs/setup-customer-sharepoint This snippet provides PowerShell commands to add the AEM Content Integration enterprise application as a service principal in Azure Active Directory. It first connects to Microsoft Graph with necessary permissions (`Application.ReadWrite.All`) and then creates the service principal using its `AppId` and `Tags`. ```PowerShell PS> connect-MgGraph -Scopes "Application.ReadWrite.All" PS> New-MgServicePrincipal -AppId 83ab2922-5f11-4e4d-96f3-d1e0ff152856 -Tags WindowsAzureActiveDirectoryIntegratedApp ``` -------------------------------- ### Initializing Adobe FEDS Configuration (JavaScript) Source: https://status.adobe.com/products/503489 This snippet initializes the `window.fedsConfig` object, which configures the Adobe Global Navigation (FEDS) system. It sets the locale, disables sticky behavior, defines content experience, subnav theme, and a function for the footer's region modal to display a language change modal. It also includes privacy settings for OneTrust. ```JavaScript var modal,langLocale=document.querySelector("html").getAttribute("data-gnav-lang-key");window.fedsConfig={locale:langLocale||window.locale||"en",disableSticky:!1,content:{experience:"acom"},subnav:{theme:{base:"light",gradient:{toColor:"#FAFAFA",fromColor:"#FAFAFA",opacity:1}}},footer:{regionModal:function(){(modal=document.getElementById("changeLanguageModal")).style.display="block"}},privacy:{otDomainId:"7a5eb705-95ed-4cc4-a11d-0cc5760e93db",footerLinkSelector:'\\[data-feds-action=\"open-adchoices-modal\"\]'}} ``` -------------------------------- ### Audit Log Entry for Preview Operation (Audit Log Format) Source: https://www.aem.live/docs/auditlog This snippet shows the audit log entry for a 'Preview' operation triggered via Sidekick. It indicates that the operation uses the HTTP POST method and targets the `/preview` route. ```Audit Log Format method: POST, route: /preview ``` -------------------------------- ### Assigning Application Role to Managed Identity (Graph Explorer - Generic) Source: https://www.aem.live/docs/setup-customer-sharepoint This POST request to the Microsoft Graph API assigns an application role to a service principal. It requires the 'principalId' of the managed identity, the 'resourceId' of the resource defining the role, and the 'appRoleId' of the specific role to be assigned. The request body is a JSON object containing these three IDs. ```HTTP POST https://graph.microsoft.com/v1.0/servicePrincipals/${principalId}/appRoleAssignedTo Content-Type: application/json { "principalId": "${principalId}", "resourceId": "${resourceId}", "appRoleId": "${appRoleId}" } ``` -------------------------------- ### HTML Structure for AEM Sidekick Custom JSON Viewer (HTML) Source: https://www.aem.live/developer/sidekick-development This HTML snippet provides the basic structure for a custom JSON viewer page, intended to be hosted at the `viewer` path defined in the special views configuration. It includes meta tags for character set and viewport, links to an external CSS file (`custom-json-viewer.css`), and references a JavaScript file (`custom-json-viewer.js`) for custom logic. ```HTML Custom JSON Viewer ``` -------------------------------- ### Audit Log Entry for Publish Operation (Audit Log Format) Source: https://www.aem.live/docs/auditlog This snippet shows the audit log entry for a 'Publish' operation triggered via Sidekick. It indicates that the operation uses the HTTP POST method and targets the `/live` route. ```Audit Log Format method: POST, route: /live ``` -------------------------------- ### Defining a URL-based AEM Sidekick Plugin in JSON Source: https://www.aem.live/developer/sidekick-development This JSON snippet illustrates how to define a URL-based plugin within the AEM Sidekick configuration. When the plugin button is clicked, it opens the specified `url` in a new tab. Essential properties include a unique `id`, a `title` for the button, and the `url` to be opened. ```JSON { "plugins": [ { "id": "foo", "title": "Foo", "url": "/tools/sidekick/foo.html" } ] } ``` -------------------------------- ### Configuring CDN Opt-In Header for Cache TTLs (Plain Text) Source: https://www.aem.live/docs/setup-byo-cdn-push-invalidation This snippet specifies the 'X-Push-Invalidation' header that the production CDN must send to the origin server. Its purpose is to signal the origin to enable long cache Time-To-Live (TTL) values, optimizing content delivery and reducing origin load. ```Plain Text X-Push-Invalidation: enabled ``` -------------------------------- ### Configuring a Standard Popover AEM Sidekick Plugin (JSON) Source: https://www.aem.live/developer/sidekick-development This JSON configuration defines a URL-based plugin for AEM Sidekick that opens its target URL ('/tools/sidekick/foo-popover.html') within a popover, centered above the plugin's button, instead of a new tab. The `isPopover` property is set to `true` to enable this behavior. ```JSON { "plugins": [ { "id": "foo", "title": "Foo", "url": "/tools/sidekick/foo-popover.html", "isPopover": true } ] } ``` -------------------------------- ### Defining Special View for JSON Files in AEM Sidekick (JSON) Source: https://www.aem.live/developer/sidekick-development This JSON configuration defines a "special view" within the AEM Sidekick. When a tab's URL matches the `path` pattern (`**.json`), the sidekick redirects to the specified `viewer` URL (`/tools/sidekick/custom-json-viewer/index.html`). This enables custom rendering logic for specific media types, with the original resource URL passed as a query parameter. ```JSON { "specialViews": [ { "title": "Custom JSON Viewer", "path" : "**.json", "viewer": "/tools/sidekick/custom-json-viewer/index.html" } ] } ``` -------------------------------- ### Adding AEM Content Integration Service Principal using Microsoft Graph API Source: https://www.aem.live/docs/setup-customer-sharepoint This snippet demonstrates how to add the AEM Content Integration enterprise application as a service principal in Azure Active Directory using a POST request to the Microsoft Graph API. It specifies the `appId` and `tags` for the service principal, enabling the application to be recognized within Azure AD. ```HTTP Request POST https://graph.microsoft.com/v1.0/servicePrincipals Content-type: application/json { "appId": "83ab2922-5f11-4e4d-96f3-d1e0ff152856", "tags": [ "WindowsAzureActiveDirectoryIntegratedApp" ] } ``` -------------------------------- ### Restricting Sidekick Access: Allowing Specific Hosts (JSON) Source: https://www.aem.live/docs/sidekick-security This configuration demonstrates a restrictive approach where the AEM Sidekick extension is blocked from all URLs (`http*://*/*`) except those explicitly listed in `runtime_allowed_hosts`. This ensures maximum security while allowing interaction with essential AEM-related domains and local development environments. It complements the `host_permissions` defined in the extension's manifest file. ```JSON { "igkmdomcgoebiipaifhmpfjhbjccggml": { "runtime_blocked_hosts": ["http*://*/*"], "runtime_allowed_hosts": [ "https://admin.hlx.page/*", "https://rum.hlx.page/*", "http://localhost:3000/*", "https://*.sharepoint.com/*", "https://*--project--example.aem.*/*" ] } } ``` -------------------------------- ### JavaScript Logic for AEM Sidekick Custom JSON Viewer (JavaScript) Source: https://www.aem.live/developer/sidekick-development This JavaScript snippet implements the core logic for the custom JSON viewer. It retrieves the original resource URL from the current page's query parameters, fetches the content, parses it as JSON, and then displays the formatted JSON data within a `

` tag in the document body. It includes error handling for failed fetches or parsing.

```JavaScript
try {
  // get the resource URL from the url query parameter
  const url = new URL(window.location.href).searchParams.get('url');
  if (url) {
    const res = await fetch(url);
    if (res.ok) {
      const text = await res.text();
      const data = JSON.parse(text);
      // do something with the data, e.g.
      document.body.innerHTML = `\n        \n          ${JSON.stringify(data, null, 2)}\n        \n       `;
    } else {
      throw new Error(`failed to load ${url}: ${res.status}`);
    }
  }
} catch (e) {
  console.error('error rendering custom json view', e);
}
```

--------------------------------

### Configuring a Custom-Sized Palette AEM Sidekick Plugin (JSON)

Source: https://www.aem.live/developer/sidekick-development

This JSON configuration extends the palette plugin by specifying a custom size and position using the `paletteRect` property. The `paletteRect` string defines the CSS properties for the palette's dimensions and placement, allowing for precise control over its appearance on the page.

```JSON
{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "url": "/tools/sidekick/foo-palette.html",
      "isPalette": true,
      "paletteRect": "top:150px;left:7%;height:675px;width:85vw;"
    }
  ]
}
```

--------------------------------

### Audit Log Entry for Delete Operation (Audit Log Format)

Source: https://www.aem.live/docs/auditlog

This snippet shows the audit log entry for a 'Delete' operation triggered via Sidekick. It indicates that the operation involves two steps: first, an HTTP DELETE method to the `/preview` route, and then another HTTP DELETE method to the `/live` route.

```Audit Log Format
method: DELETE, route: /preview
method: DELETE, route: /live
```

--------------------------------

### Listening to AEM Sidekick Events in JavaScript

Source: https://www.aem.live/developer/sidekick-development

This snippet demonstrates how to listen for custom AEM Sidekick events, such as 'foo', in your project's JavaScript code. It handles scenarios where the sidekick is already loaded or waits for the 'sidekick-ready' event before attaching the listener. The event payload is accessed via `event.detail`.

```JavaScript
const doFoo = ({ detail: payload }) => {
  console.log('something happened', payload);
  // your custom code goes here
};

const sk = document.querySelector('aem-sidekick');
if (sk) {
  // sidekick already loaded
  sk.addEventListener('foo', doFoo);
} else {
  // wait for sidekick to be loaded
  document.addEventListener('sidekick-ready', () => {
    // sidekick now loaded
    document.querySelector('aem-sidekick')
      .addEventListener('foo', doFoo);
  }, { once: true });
}
```

--------------------------------

### Aggregating Multiple AEM Indexes into a Single Sitemap (YAML)

Source: https://www.aem.live/developer/sitemap

This YAML configuration shows how to combine content from multiple language-specific query indexes (e.g., Danish and Norwegian) into a single sitemap file (`/sitemap.xml`). By specifying the same `destination` for different language entries, AEM aggregates their content, which is useful for managing sitemap limits for search engines.

```YAML
 sitemaps:
   example:
     lastmod: YYYY-MM-DD
     languages:
       dk:
         source: /dk/query-index.json
         destination: /sitemap.xml
         hreflang: dk
         alternate: /dk/{path}
       no:
         source: /no/query-index.json
         destination: /sitemap.xml
         hreflang: no
         alternate: /no/{path}
```

--------------------------------

### Configuring Multiple Language Sitemaps in AEM (YAML)

Source: https://www.aem.live/developer/sitemap

This YAML configuration defines how AEM generates multiple sitemaps for different languages (English and French). It specifies the `lastmod` date, the source query index for each language, the destination sitemap file, and the `hreflang` attribute. The `alternate` property defines a path pattern for alternate language versions.

```YAML
 sitemaps:
   example:
     lastmod: YYYY-MM-DD
     languages:
       en:
         source: /en/query-index.json
         destination: /sitemap-en.xml
         hreflang: en
       fr:
         source: /fr/query-index.json
         destination: /sitemap-fr.xml
         hreflang: fr
         alternate: /fr/{path}
```

--------------------------------

### Handling Custom AEM Sidekick Plugin Events (JavaScript)

Source: https://www.aem.live/developer/sidekick-development

This JavaScript code demonstrates how to listen for a custom event ('custom:foo') dispatched by an AEM Sidekick event-based plugin. It checks if the sidekick is already loaded or waits for the 'sidekick-ready' event, then attaches an event listener to execute custom logic when the plugin button is clicked. The event detail contains the current sidekick state.

```JavaScript
const doFoo = ({ detail: payload }) => {
  console.log('a custom event happened', payload);
  // your custom code goes here
};

const sk = document.querySelector('aem-sidekick');
if (sk) {
  // sidekick already loaded
    sk.addEventListener('custom:foo', doFoo);
} else {
  // wait for sidekick to be loaded
  document.addEventListener('sidekick-ready', () => {
    // sidekick now loaded
    document.querySelector('aem-sidekick')
      .addEventListener('custom:foo', doFoo);
  }, { once: true });
}
```

--------------------------------

### Configuring an Event-based AEM Sidekick Plugin (JSON)

Source: https://www.aem.live/developer/sidekick-development

This JSON configuration defines an event-based plugin for AEM Sidekick. When the 'Foo' button is clicked, a custom 'foo' event is dispatched, allowing custom JavaScript code to react to this action. This type of plugin is restricted to Development, Preview, Live, and Production environments.

```JSON
{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "event": "foo"
    }
  ]
}
```

--------------------------------

### Configuring Custom Edit URL for AEM Sidekick (JSON)

Source: https://www.aem.live/developer/sidekick-development

This JSON snippet configures the AEM Sidekick to use a custom URL for the 'Edit' button. It defines `editUrlLabel` for the button's text and `editUrlPattern` which supports placeholders like `{{contentSourceUrl}}` and `{{pathname}}` to dynamically construct the edit URL. This allows integration with non-SharePoint/Google Drive content sources.

```JSON
{
  "editUrlLabel": "Your Editor",
  "editUrlPattern": "{{contentSourceUrl}}{{pathname}}?cmd=open"
}
```

--------------------------------

### Configuring a Custom-Sized Popover AEM Sidekick Plugin (JSON)

Source: https://www.aem.live/developer/sidekick-development

This JSON configuration allows customization of a popover plugin's dimensions using the `popoverRect` property. This string defines the `width` and `height` of the popover, enabling control over its size while maintaining its centered position above the plugin button. A `theme` query parameter is also appended to the URL for styling.

```JSON
{
  "plugins": [
    {
      "id": "foo",
      "title": "Foo",
      "url": "/tools/sidekick/foo-popover.html",
      "isPopover": true,
      "popoverRect": "width:300px;height:200px;"
    }
  ]
}
```

--------------------------------

### Configuring Multiple hreflangs for a Single AEM Subtree (YAML)

Source: https://www.aem.live/developer/sitemap

This YAML configuration demonstrates how to assign an array of `hreflang` values to a single language subtree (`la`). This allows a single source to be associated with multiple regional or linguistic variations (e.g., `es-VE`, `es-SV`, `es-PA`) in the generated sitemap, ensuring comprehensive alternate linking.

```YAML
 sitemaps:
   example:
     lastmod: YYYY-MM-DD
     languages:
       la:
         source: /la/query-index.json
         destination: /sitemap-la.xml
         hreflang:
           - es-VE
           - es-SV
           - es-PA
```