adobe/helix-sidekick-extension

Browser extension for authors on AEM projects

AEM Sidekick Extension

Browser extension for authoring AEM sites

Status

Installation

Installing the Chrome extension

1. Go to the Chrome Web Store
2. Click Add to Chrome
3. Confirm by clicking Add extension
4. Click the extensions icon next to Chrome's address bar to see a list of all extensions:
   
5. Verify that there's an icon like this:
   
   
6. Click the pin button next to it to make sure it always stays visible.

Adding projects to the Chrome extension

1. Right-click the extension's icon and select Options:
   
   On this page, you can add projects by either pasting a share URL* or a GitHub URL in the respective fields and clicking Add. This page will also allow you to view, edit and delete existing projects.
   1. Alternatively, you can also navigate to a share URL* or a GitHub project, click the extension's icon and select Add project.
2. Navigate to your project's homepage and click on the extension's icon to toggle the Sidekick.

* Share URLs start with https://www.hlx.live/tools/sidekick/...

Usage

Refer to the Sidekick documentation to learn more about its features.

Development

Build

$ npm install
$ npm run build

Test

$ npm test

Lint

$ npm run lint

Local testing

Testing a local Chrome extension

1. Run npm run build:chrome
2. Open Chrome and navigate to chrome://extensions
3. Turn on Developer mode at the top right of the header bar
   
4. Click the Load unpacked button in the action bar
   
5. Navigate to the dist > chrome folder and click Select to install and activate the Sidekick extension.
6. Verify that your Extensions page displays a box like this:
   
   
7. Configurations are not automatically migrated to the Unpacked extension. Either follow the steps under Adding projects to the extension or Export/Import the other plugin's configuration.
8. If you do not see the Sidekick JavaScript files in the browser debug window, check that they are not being ignored. Ensure "Content scripts injected by extensions" is unchecked:
   

Testing a local project config

If you want to test a config file before deploying it to your project:

1. Run hlx up on your local checkout of the project repository
2. Add your project to the sidekick extension
3. Enable local project configruation:
   1. Right-click the extension's icon and select Options
   2. Click Advanced on the left
   3. Click Edit on the project configuration you want to test locally
   4. Tick the Test project configuration locally checkbox
   5. Click Save
4. Navigate to a project URL and activate the sidekick extension

Deployment

Deploying Chrome Extension

The Chrome extension is automatically built and uploaded to Chrome Web Store every time a pull request triggering a semantic-release is merged into main. Once reviewed by Google, it will be auto-published and pushed to end users' browsers.

The following environment variables are required in the CircleCI project settings: GOOGLE_APP_ID, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REFRESH_TOKEN. See here for detailed instructions how to obtain and generate them.

Chrome Developer Dashboard (Adobe only)

As an Adobe developer, see https://wiki.corp.adobe.com/x/xJlMqQ for instructions how to get access to the Chrome Developer Dashboard and make changes to the Chrome Web Store listing.

Safari Extension

The Safari Extension is built, signed and uploaded to App Store Connect automatically each time a pull request triggering a semantic-release is merged into main.

An Xcode Cloud workflow is listening for changes made to the change log file in the main branch.

App Store Connect (Adobe only)

As an Adobe developer, see https://wiki.corp.adobe.com/x/xJlMqQ for instructions how to get access to the App Store Connect and make new builds available via TestFlight and public release.

helix-sidekick-extension's Issues

Reduce code complexity of environment switcher

The environment switcher is currently being assembled as a special case in the add() method. Since the introduction of plugin properties such as container and isDropDown, this code could be simplified.

Branch versions

For reviewing purposes, it would be great if the extension could be configured to invoke a branch version of the sidekick.

Auto-install project config from share URL

• If a user without sidekick extension opens a share URL, there should be a button to install the sidekick extension from the Chrome Web Store, and the instruction to come back to this page after the installation to add the project config.
• If a user with sidekick extension opens a share URL (or switches to a previously opened tab with a share URL), the extension should
  • hide the install button
  • automatically add the config (if not already added)

JSON view: all media links get rendered as images

Leading to broken images being displayed, e.g. in case of videos.

Config picker: misaligned close button

There's a regression in the config picker causing the close buton to be rendered the wrong way:

Disable `User-friendly data rendition` on `/helix-env.json`

With https://github.com/adobe/helix-admin/pull/604 we will be generating /helix-env.json which will contain a merged (public) configuration from multiple sources.

I believe this may be the first time we are serving a json file through the pipeline that is not backed by a spreadsheet??

The problem

Currently the sidekick see that we are requesting something with a .json extension and assumes it's in the serialized spreadsheet format and tries to render it using the User-friendly data rendition. The result is an empty page.

Proposed solution

Disable User-friendly data rendition on the path /helix-env.json.

Add project from preview or live URL

Projects can be added from GitHub URLs and share URLs. In addition, it would be convenient if projcts could be added from preview or live URLs.

Refactor from browser to chrome API

Safari and Firefox both support the chrome extension API, so there's no real need for the overhead of polyfilling browser for Chrome to retain a cross-browser implementation.

Disable projects

It would sometimes be helpful if projects could be temporary disabled instead of deleted.

Sidekick with a reference to a repo with Uppercase letters does not display any actions on preview page

adobe/helix-sidekick#137 has been fixed, but the extension is still affected.

Config picker does not respect pushDown flag

The config picker currently always pushed down content, regardless of the user setting under Options > User Experience.

Safari (macOS) support

Enable sidekick extension for Safari (macOS).

Permission handling

Companion issue for adobe/helix-sidekick#255

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• chore(deps): update dependency ajv to v8.14.0

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update external major (major) (semantic-release, sinon)

Detected dependencies

circleci

.circleci/config.yml

• cimg/node 18.20
• browser-tools 1.4.8
• codecov 4.1.0

npm

package.json

• @adobe/eslint-config-helix 2.0.6
• @adobe/fetch 4.1.2
• @babel/eslint-parser 7.24.6
• @esm-bundle/chai 4.3.4-fix.0
• @semantic-release/changelog 6.0.3
• @semantic-release/exec 6.0.3
• @semantic-release/git 10.0.1
• @web/test-runner 0.18.2
• @web/test-runner-commands 0.9.0
• ajv 8.13.0
• archiver 7.0.1
• c8 9.1.0
• codecov 3.8.3
• eslint 8.57.0
• express 4.19.2
• fs-extra 11.2.0
• husky 9.0.11
• jsdoc-to-markdown 8.0.1
• lint-staged 15.2.5
• mime 4.0.3
• mocha 10.4.0
• mocha-multi-reporters 1.5.1
• nock 13.5.4
• puppeteer 21.1.1
• puppeteer-core 21.1.1
• puppeteer-to-istanbul 1.4.0
• request 2.88.2
• semantic-release 22.0.12
• semantic-release-discord-bot ^1.1.0
• semantic-release-react-native 1.10.0
• shelljs 0.8.5
• sinon 17.0.2

---

• Check this box to trigger a request for Renovate to run again on this repository

Auto-reload

The sidekick could auto-reload the main section of the document in case the lastModified in the preview status is newer than when the document was last (re)loaded.

GH branch support in development environment

When using the sidekick on http://localhost:3000, it would be helpful if the sidekick could

• let the user open the GH repo with the current branch
• open preview and live links with the current branch

Remove legacy support and default to *.hlx.page

The sidekick extension no longer has to deal with Helix 2 configs.

Edits of project settings are not persisted.

Description
Changes to project settings via Options -> Edit -> Save are not persisted.

To Reproduce
Steps to reproduce the behavior:

1. Go to Options
2. On a project entry, click on 'Edit'
3. Make a change to title
4. Click on 'Save'
5. => change is not persisted

Expected behavior
Changes get persisted.

Config picker: UX issue with lots of matching projects

A lot of matching configs can make the config picker difficult to use.

JS error on blank share URL

When visiting https://www.hlx.live/tools/sidekick/ without query parameters, the extension throws a JS error in the background page.

Encourage bookmarklet users to install sidekick extension

To promote the usage of the sidekick extension, bookmarklet users should be encouraged to install the extension when they click on the bookmarklet.

Share URL instrumentation fails intermittently

The extension doesn't have access to global variables defined by the content window, so it needs to use a different way to detect if the share URL is ready to be instrumented.

Support custom SharePoint domains

The sidekick currently expects a SharePoint domain to be *.sharepoint.com.

CI/CD

Automate build, upload and publication of sidekick extension to Chrome Web Store.

https://circleci.com/blog/continuously-deploy-a-chrome-extension/

Add project option missing if no projects configured yet

When installing the sidekick for the first time, or deleting its config, it won't show an "Add project" option in the context menu on GitHub or preview URLs until the user adds a first project manually via the "Options" page.

502 on new documents

I think the flow is like this:

• open the sidekick on an existing page
• go to Sharepoint, create a new document
• edit the document, rename it
• hit the "Preview" button

-> nothing happens

The admin requests go to /document while the document has now a different name. See screenshot:

Use hlx:proxyUrl meta tag for local development

Extension manifest v3 no longer allows reading request headers from the content window. An alternative approach to detecting the proxyUrl is the merta tag hlx:proxyUrl which the Helix CLI is injecting now.

Use /helix-env.json to add projects

The sidekick extension currently uses GH's raw API to extract project information from the GitHub repo. This is a bit shaky and doesn't work if repositories are private. It would be much better to use the new setup API.

Update: /helix-env.json already provides what the sidekick needs to add a project.

Regression: chrome API refactoring reverted support for personal onedrive folders

#46 reverted #43.

Improve help UX

Getting feedback that the current help UX is not intuitive enough. People have difficulty acknowledging topics ("got it!") so the same content keeps reappearing over and over. Also clicking the white dots to go to the next balloon seems to be a challenge.

I propose to add a dedicated "next" to help with navigation, and a combobox-like "close" button to dismiss the help content, letting the user choose between the following options:

• show this again later: the same help topic will be displayed again
• don't show this anymore: the same help topic will not reappear
• never show any help content: opt out of all help topics

Enable and disable project config via context menu

Users currently need to go to the options page to enable/disable project configs. It would save a few clicks if the feature would be available in the extension's context menu.

Add basic telemetry

During the sidekick launch I noticed that we do not know how many people have the sidekick open at a time. It may be useful to add some basic telemetry logging so that we know when and how much sidekick is used, where outdated versions are used, and which features are used and unused.

I'd re-use the /.rum/ endpoint for logging and extend the RUM collector to write to a different data sink if the URL is /.rum/sidekick/.

New project configuration

With extension manifest v3, the sidekick will no longer be able to execute /tools/sidekick/config.js. Instead, the project configuration will need to be defined in a /tools/sidekick/config.json, combined with a new way how projects can add custom functionality beyond simple URLs opened in a new window.

• Update schema
• Update documentation

New login flow without 3rd party cookie

Remove Helix 2 support

Once Helix 2 is EOL,the sidekick no longer has to support it. Existing configurations should be marked as unsupported. For now. See also adobe/helix-sidekick#225.

Provide cmd+s hint to Word users

Word can be a bit sluggish when it comes to saving changes back for Helix to render out during the preview action. Pressing command (Mac) or ctrl (Windows) + S before clicking preview has been a proven way to always get the latest version of the document.

When Word users click preview (or reload) in the sidekick, it could let them know about this trick:

Pro tip: Press command/ctrl + S in Word before clicking preview to always see the latest changes

Support shared secret for Admin API

See adobe/helix-sidekick#124

Migrate to manifest v3

Manifest v2 EOL schedule:

• June 2022: Chrome Web Store stops accepting new Manifest V2 extensions with visibility set to “Public" or "Unlisted”
• January 2024: Chrome Web Store stops accepting updates to existing Manifest V2 extensions,
  Chrome stops running Manifest V2 extensions

https://developer.chrome.com/docs/extensions/mv3/intro/mv3-migration/

Issues directly related to the manifest v3 migration:

• #103
• #102

More issues to be bundled:

• #100
• #104
• #110
• #111

Add project context menu should reload page

Fragment support

When opening the sidekick on a fragment URL (*.plain.html), the sidekick acts like the source doesn't exist and only offers to delete the content:

Sidekick does not work with mountpoints in personal sharepoint storage.

Description
The sidekick won't open when a helix site is setup in personal sharepoint storage. Since the rest of the helix stack works with personal share point it feels like maybe sidekick should also support this?

To Reproduce
Steps to reproduce the behavior:

1. Create repo based on the helix-project-boilerplate
2. Create a directory in a personal OneDrive storage and share with helix integration ([email protected])
3. Update fstab mount point and commit.
4. Add the helix-bot to the repo
5. Add the project to sidekick using the Add Project button
6. Create an index document within the project directory in OneDrive.
7. Attempt to open the sidekick

Expected behavior
The sidekick opens

Options: remember area states

When expanding or collapsing areas on the options page, the states should be remembered.

Add option to push down content

After we switch to not pushing down content by default anymore, users should have the option to turn it back on.

Add support for developers to set admin version

So extension users can make use of adobe/helix-sidekick#240

Safari (iOS) support

Enable sidekick extension for Safari (iOS).

Unsupported SP URL format prevents sidekick from showing up

E.g. https://adobe.sharepoint.com/:f:/r/sites/MySite/Shared%20Documents/website is a valid SP sharing URL, even though the /:f:/r is redundant.

cc @davidnuescheler

Preview URL on projects page in sidekick shows hlx.page instead of hlx3.page for Helix 3 sites

Description
The preview URL listed on the sidekick options page is displaying hlx.page for Helix 3 sites.

To Reproduce
Steps to reproduce the behavior:

1. Create repo based on the helix-project-boilerplate
2. Create a directory in OneDrive and share with helix integration ([email protected])
3. Update fstab mount point and commit.
4. Add the helix-bot to the repo
5. Add the project to sidekick using the Add Project button

Expected behavior
The projects page in sidekick should show hlx3.page as the preview url.

Screenshots

Show help for FTUE and new features

When users open the sidekick for the first time, or new features have been added, the sidekick should display help content.

Add support for PDF in SharePoint

It should be possible to preview and publish PDF documents in SharePoint.

See also https://github.com/adobe/helix-admin/issues/705

Add Preview URLs button that lists all urls from the current folder

In Sharepoint / Google Drive, when you are on the "directory" view - currently the Sidekick shows the "Preview" button which is not doing anything (the extension does not show up at all).
We could leverage the Sidekick on that view to generate a list of all the preview urls from that folder as root. A dialog could show the list as links to be able to open each of them and a "Copy" button to copy the list in clipboard to be pasted in the organizer or in a spreadsheet.