diff --git a/gatsby-config.js b/gatsby-config.js index c26a9cb5b..23ecd77af 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -146,6 +146,10 @@ module.exports = { title: "BaseNode", path: "references/document-sandbox/document-apis/classes/BaseNode.md", }, + { + title: "BitmapImage", + path: "references/document-sandbox/document-apis/classes/BitmapImage.md", + }, { title: "ColorUtils", path: "references/document-sandbox/document-apis/classes/ColorUtils.md", @@ -166,10 +170,22 @@ module.exports = { title: "EllipseNode", path: "references/document-sandbox/document-apis/classes/EllipseNode.md", }, + { + title: "ExpressContext", + path: "references/document-sandbox/document-apis/classes/ExpressContext.md", + }, + { + title: "ExpressEditor", + path: "references/document-sandbox/document-apis/classes/ExpressEditor.md", + }, { title: "ExpressRootNode", path: "references/document-sandbox/document-apis/classes/ExpressRootNode.md", }, + { + title: "ExpressViewport", + path: "references/document-sandbox/document-apis/classes/ExpressViewport.md", + }, { title: "FillableNode", path: "references/document-sandbox/document-apis/classes/FillableNode.md", @@ -242,6 +258,10 @@ module.exports = { title: "SolidColorShapeNode", path: "references/document-sandbox/document-apis/classes/SolidColorShapeNode.md", }, + { + title: "StandaloneTextContentModel", + path: "references/document-sandbox/document-apis/classes/StandaloneTextContentModel.md", + }, { title: "StandaloneTextNode", path: "references/document-sandbox/document-apis/classes/StandaloneTextNode.md", @@ -262,6 +282,14 @@ module.exports = { title: "TextNode", path: "references/document-sandbox/document-apis/classes/TextNode.md", }, + { + title: "TextNodeContentModel", + path: "references/document-sandbox/document-apis/classes/TextNodeContentModel.md", + }, + { + title: "ThreadedTextContentModel", + path: "references/document-sandbox/document-apis/classes/ThreadedTextContentModel.md", + }, { title: "ThreadedTextNode", path: "references/document-sandbox/document-apis/classes/ThreadedTextNode.md", @@ -278,10 +306,6 @@ module.exports = { title: "UnknownNode", path: "references/document-sandbox/document-apis/classes/UnknownNode.md", }, - { - title: "Viewport", - path: "references/document-sandbox/document-apis/classes/Viewport.md", - }, { title: "VisualNode", path: "references/document-sandbox/document-apis/classes/VisualNode.md", @@ -553,7 +577,29 @@ module.exports = { }, { title: "Code Playground", - path: "guides/getting_started/code_playground.md", + path: "guides/getting_started/code-playground.md", + pages: [ + { + title: "Overview", + path: "guides/getting_started/code-playground.md", + }, + { + title: "Script Mode", + path: "guides/getting_started/code-playground-script-mode.md", + }, + { + title: "Add-on Mode", + path: "guides/getting_started/code-playground-addon-mode.md", + }, + { + title: "Workflow & Productivity", + path: "guides/getting_started/code-playground-workflow.md", + }, + { + title: "Troubleshooting", + path: "guides/getting_started/code-playground-troubleshooting.md", + }, + ], }, { title: "Local Development", @@ -575,6 +621,10 @@ module.exports = { title: "VS Code debugging", path: "guides/getting_started/local_development/vs-code.md", }, + { + title: "Known Issues & Limitations", + path: "guides/getting_started/local_development/known_issues_limitations.md", + }, ], }, { diff --git a/src/@adobe/gatsby-theme-aio/components/Code/index.js b/src/@adobe/gatsby-theme-aio/components/Code/index.js index 23c988199..1ca2510f6 100644 --- a/src/@adobe/gatsby-theme-aio/components/Code/index.js +++ b/src/@adobe/gatsby-theme-aio/components/Code/index.js @@ -164,7 +164,7 @@ const Code = ({ children, className = "", theme, metastring = "" }) => { !isMobile && openCodePlayground(children, sampleId) } > - Try + Try in playground )} diff --git a/src/@adobe/gatsby-theme-aio/components/Code/styles.css b/src/@adobe/gatsby-theme-aio/components/Code/styles.css index c4543201b..8470f97b7 100644 --- a/src/@adobe/gatsby-theme-aio/components/Code/styles.css +++ b/src/@adobe/gatsby-theme-aio/components/Code/styles.css @@ -40,7 +40,7 @@ } .code-copy-button.with-try { - inset-inline-end: var(--spectrum-global-dimension-size-700); + inset-inline-end: calc(var(--spectrum-global-dimension-size-2000) + var(--spectrum-global-dimension-size-100)); } .code-try-button { @@ -67,7 +67,7 @@ } .code-tooltip-container.with-try { - inset-inline-end: calc(var(--spectrum-global-dimension-size-700) + var(--spectrum-global-dimension-size-600) + var(--spectrum-global-dimension-size-125)); + inset-inline-end: calc(var(--spectrum-global-dimension-size-2000) + var(--spectrum-global-dimension-size-100) + var(--spectrum-global-dimension-size-600) + var(--spectrum-global-dimension-size-125)); } .code-tooltip { diff --git a/src/@adobe/gatsby-theme-aio/components/GlobalHeader/avatar.svg b/src/@adobe/gatsby-theme-aio/components/GlobalHeader/avatar.svg new file mode 100644 index 000000000..75305cc07 --- /dev/null +++ b/src/@adobe/gatsby-theme-aio/components/GlobalHeader/avatar.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/@adobe/gatsby-theme-aio/components/GlobalHeader/index.js b/src/@adobe/gatsby-theme-aio/components/GlobalHeader/index.js new file mode 100644 index 000000000..ac8a17e7b --- /dev/null +++ b/src/@adobe/gatsby-theme-aio/components/GlobalHeader/index.js @@ -0,0 +1,1264 @@ +/* + * Copyright 2020 Adobe. All rights reserved. + * This file is licensed to you under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. You may obtain a copy + * of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under + * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS + * OF ANY KIND, either express or implied. See the License for the specific language + * governing permissions and limitations under the License. + */ + +import React, { Fragment, useRef, useEffect, useState } from "react"; +import PropTypes from "prop-types"; +import nextId from "react-id-generator"; +import { withPrefix } from "gatsby"; +import { GatsbyLink } from "@adobe/gatsby-theme-aio/src/components/GatsbyLink"; +import { + findSelectedTopPage, + findSelectedTopPageMenu, + rootFix, + rootFixPages, + getExternalLinkProps, + DESKTOP_SCREEN_WIDTH, + MOBILE_SCREEN_WIDTH, + DEFAULT_HOME, +} from "@adobe/gatsby-theme-aio/src/utils"; +import { css } from "@emotion/react"; +import { AnchorButton } from "@adobe/gatsby-theme-aio/src/components/AnchorButton"; +import { Button } from "@adobe/gatsby-theme-aio/src/components/Button"; +import { ProgressCircle } from "@adobe/gatsby-theme-aio/src/components/ProgressCircle"; +import { + Adobe, + ChevronDown, + Magnify, + Close, + TripleGripper, + CheckMark, +} from "@adobe/gatsby-theme-aio/src/components/Icons"; +import { + ActionButton, + Text as ActionButtonLabel, +} from "@adobe/gatsby-theme-aio/src/components/ActionButton"; +import { PickerButton } from "@adobe/gatsby-theme-aio/src/components/Picker"; +import { + Menu, + Item as MenuItem, +} from "@adobe/gatsby-theme-aio/src/components/Menu"; +import { Popover } from "@adobe/gatsby-theme-aio/src/components/Popover"; +import { Image } from "@adobe/gatsby-theme-aio/src/components/Image"; +import { Link } from "@adobe/gatsby-theme-aio/src/components/Link"; +import { + Tabs, + HeaderTabItem as TabsItem, + Label as TabsItemLabel, + TabsIndicator, + positionIndicator, + animateIndicator, +} from "@adobe/gatsby-theme-aio/src/components/Tabs"; +import "@spectrum-css/typography"; +import "@spectrum-css/assetlist"; +import { Divider } from "@adobe/gatsby-theme-aio/src/components/Divider"; +import DEFAULT_AVATAR from "./avatar.svg"; + +const getSelectedTabIndex = (location, pages) => { + const pathWithRootFix = rootFix(location.pathname); + const pagesWithRootFix = rootFixPages(pages); + + let selectedIndex = pagesWithRootFix.indexOf( + findSelectedTopPage(pathWithRootFix, pagesWithRootFix) + ); + let tempArr = pathWithRootFix.split("/"); + let inx = tempArr.indexOf("use-cases"); + if (selectedIndex === -1 && inx > -1) { + tempArr[inx + 1] = "agreements-and-contracts"; + tempArr[inx + 2] = "sales-proposals-and-contracts"; + if (tempArr[inx + 3] == undefined) { + tempArr.push(""); + } + let tempPathName = tempArr.join("/"); + selectedIndex = pagesWithRootFix.indexOf( + findSelectedTopPage(tempPathName, pagesWithRootFix) + ); + } + // Assume first item is selected + if (selectedIndex === -1) { + selectedIndex = 0; + } + return selectedIndex; +}; + +const getAvatar = async (userId) => { + try { + const req = await fetch( + `https://cc-api-behance.adobe.io/v2/users/${userId}?api_key=SUSI2` + ); + const res = await req.json(); + return res?.user?.images?.["138"] ?? DEFAULT_AVATAR; + } catch (e) { + console.warn(e); + return DEFAULT_AVATAR; + } +}; + +const GlobalHeader = ({ + hasIMS, + ims, + isLoadingIms, + home, + versions, + pages, + docs, + location, + toggleSideNav, + hasSideNav, + hasSearch, + showSearch, + setShowSearch, + searchButtonId, +}) => { + const [selectedTabIndex, setSelectedTabIndex] = useState( + getSelectedTabIndex(location, pages) + ); + const tabsRef = useRef(null); + const tabsContainerRef = useRef(null); + const selectedTabIndicatorRef = useRef(null); + // Don't animate the tab indicator by default + const [isAnimated, setIsAnimated] = useState(false); + const versionPopoverRef = useRef(null); + const profilePopoverRef = useRef(null); + const [openVersion, setOpenVersion] = useState(false); + const [openProfile, setOpenProfile] = useState(false); + const [openMenuIndex, setOpenMenuIndex] = useState(-1); + const [profile, setProfile] = useState(null); + const [avatar, setAvatar] = useState(DEFAULT_AVATAR); + const [isLoadingProfile, setIsLoadingProfile] = useState(true); + const [selectedMenuItem, setSelectedMenuItem] = useState({}); + + const POPOVER_ANIMATION_DELAY = 200; + const versionPopoverId = "version " + nextId(); + const profilePopoverId = "profile " + nextId(); + const hasHome = home?.hidden !== true; + + const positionSelectedTabIndicator = (index) => { + const selectedTab = pages[index].tabRef; + + if (selectedTab?.current) { + positionIndicator(selectedTabIndicatorRef, selectedTab); + } + }; + + useEffect(() => { + const index = getSelectedTabIndex(location, pages); + setSelectedTabIndex(index); + const pathWithRootFix = rootFix(location.pathname); + setSelectedMenuItem(findSelectedTopPageMenu(pathWithRootFix, pages[index])); + animateIndicator(selectedTabIndicatorRef, isAnimated); + positionSelectedTabIndicator(index); + }, [location.pathname]); + + useEffect(() => { + (async () => { + if (ims && ims.isSignedInUser()) { + const profile = await ims.getProfile(); + setProfile(profile); + setAvatar(await getAvatar(profile.userId)); + setIsLoadingProfile(false); + } else if (!isLoadingIms) { + setIsLoadingProfile(false); + } + })(); + }, [ims]); + + useEffect(() => { + if (versionPopoverRef.current) { + if (openVersion) { + const { left } = versionPopoverRef.current.getBoundingClientRect(); + + versionPopoverRef.current.style.left = `calc(${left}px + var(--spectrum-global-dimension-size-160))`; + versionPopoverRef.current.style.position = "fixed"; + } else { + // Wait for animation to finish + setTimeout(() => { + versionPopoverRef.current.style = ""; + }, POPOVER_ANIMATION_DELAY); + } + } + }, [openVersion]); + + useEffect(() => { + if (openMenuIndex !== -1) { + const menuRef = pages[openMenuIndex].menuRef; + + const { left } = menuRef.current.getBoundingClientRect(); + + menuRef.current.style.left = `${left}px`; + menuRef.current.style.position = "fixed"; + } else { + pages.forEach((page) => { + const menuRef = page.menuRef; + if (menuRef) { + // Wait for animation to finish + setTimeout(() => { + menuRef.current.style = ""; + }, POPOVER_ANIMATION_DELAY); + } + }); + } + }, [openMenuIndex]); + + useEffect(() => { + // Clicking outside of menu should close menu + const onClick = (event) => { + if ( + versionPopoverRef.current && + !versionPopoverRef.current.contains(event.target) + ) { + setOpenVersion(false); + } + + if ( + profilePopoverRef?.current && + !profilePopoverRef.current.contains(event.target) + ) { + setOpenProfile(false); + } + + pages.some((page) => { + if ( + page?.menuRef?.current && + !page.menuRef.current.contains(event.target) + ) { + setOpenMenuIndex(-1); + } + }); + }; + + document.addEventListener("click", onClick); + + return () => document.removeEventListener("click", onClick); + }, []); + + useEffect(() => { + const onScroll = () => { + setOpenVersion(false); + setOpenMenuIndex(-1); + }; + + tabsContainerRef.current.addEventListener("scroll", onScroll, { + passive: true, + }); + + return () => + tabsContainerRef.current.removeEventListener("scroll", onScroll); + }, []); + + const openDropDown = (data) => { + if (data.isOpen) { + setOpenMenuIndex(data.index); + setOpenVersion(data.isOpen); + if (openMenuIndex === -1 || openMenuIndex !== data.index) { + setTimeout(() => { + document.getElementById(`menuIndex${data.index}-0`).focus(); + }, 100); + } + } + }; + + const handleCredential = () => { + const section = document.getElementById("adobe-get-credential"); + + if (section) { + section.scrollIntoView({ + behavior: "smooth", + block: "center", + inline: "center", + }); + } + }; + + return ( +
+ +
+ ); +}; + +GlobalHeader.propTypes = { + ims: PropTypes.object, + isLoadingIms: PropTypes.bool, + home: PropTypes.object, + versions: PropTypes.array, + pages: PropTypes.array, + docs: PropTypes.object, + location: PropTypes.object, + toggleSideNav: PropTypes.func, + hasSideNav: PropTypes.bool, + setShowSearch: PropTypes.func, + hasSearch: PropTypes.bool, + showSearch: PropTypes.bool, + searchButtonId: PropTypes.string, +}; + +export { GlobalHeader }; diff --git a/src/@adobe/gatsby-theme-aio/components/Layout/index.js b/src/@adobe/gatsby-theme-aio/components/Layout/index.js new file mode 100644 index 000000000..b004cac71 --- /dev/null +++ b/src/@adobe/gatsby-theme-aio/components/Layout/index.js @@ -0,0 +1,16 @@ +/* + * Copyright 2020 Adobe. All rights reserved. + * This file is licensed to you under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. You may obtain a copy + * of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under + * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS + * OF ANY KIND, either express or implied. See the License for the specific language + * governing permissions and limitations under the License. + */ + +// Re-export the original Layout component +// This allows the shadowed GlobalHeader to work properly +export { default } from '@adobe/gatsby-theme-aio/src/components/Layout'; + diff --git a/src/pages/guides/build/distribute/private-dist.md b/src/pages/guides/build/distribute/private-dist.md index 85ee79a4d..98387f31f 100644 --- a/src/pages/guides/build/distribute/private-dist.md +++ b/src/pages/guides/build/distribute/private-dist.md @@ -36,7 +36,7 @@ The result will be a distributable zip of your add-on package with the name `dis ## Step 1: Create a new Add-on Listing -In order to get a private distribution link, you will need to create a new add-on listing first; provided that you've enabled Add-on Development in your user's settings as described [here](../../getting_started/quickstart.md#step-3-enable-add-on-development-mode-first-time-only), you can do so in two ways, which will invoke the same in-app distribution experience. +In order to get a private distribution link, you will need to create a new add-on listing first; provided that you've enabled Add-on Development in your user's settings as described [here](../../getting_started/hello-world.md#enable-add-on-development-mode), you can do so in two ways, which will invoke the same in-app distribution experience. 1. From the Adobe Express home page, click the Add-ons link in the left-hand navigation. diff --git a/src/pages/guides/build/distribute/public-dist.md b/src/pages/guides/build/distribute/public-dist.md index 42c9dc8f8..96e2b6613 100644 --- a/src/pages/guides/build/distribute/public-dist.md +++ b/src/pages/guides/build/distribute/public-dist.md @@ -85,7 +85,7 @@ To distribute your add-on, you must create an add-on listing. If you have already performed the listing creation steps, e.g. to create a Private Link as outlined here, feel free to skip to [Step 3](#step-3-create-a-new-public-listing). -Provided that you've enabled Add-on Development in your user's settings as described [here](../../getting_started/quickstart.md#step-3-enable-add-on-development-mode-first-time-only), you can do so in two ways, which will invoke the same in-app distribution experience. +Provided that you've enabled Add-on Development in your user's settings as described [here](../../getting_started/hello-world.md#enable-add-on-development-mode), you can do so in two ways, which will invoke the same in-app distribution experience. **1.** From the Adobe Express home page, click the Add-ons link in the left-hand navigation. @@ -305,7 +305,7 @@ The downloaded `.csv` files are named based on your add-on name and listing type Below is an example of what the insights data might look like: | Week | Installs | Uninstalls | Invocations | -|------------|----------|------------|-------------| +| ---------- | -------- | ---------- | ----------- | | 2025-05-01 | 120 | 10 | 300 | | 2025-05-08 | 150 | 15 | 350 | diff --git a/src/pages/guides/develop/cors.md b/src/pages/guides/develop/cors.md deleted file mode 100644 index 768e6b87d..000000000 --- a/src/pages/guides/develop/cors.md +++ /dev/null @@ -1,108 +0,0 @@ -# CORS Guide - -## Overview - -Express add-ons are run in a sandboxed iframe environment with a `null` origin, and this can cause issues when dealing with fetching from services that don't have CORS enabled or support a null origin. - -When you suspect a CORS issue, check your browser console and you will likely see a message like the following in the browser console: - -```Access to fetch at '' from origin 'null' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.``` - - - -Be sure to have your browser devtools option set to "**Show CORS errors in console**". For example, in Chrome it looks like the screenshot shown below. - -![Show CORS errors in Chrome screenshot](img/show-cors.png) - -## Options - -Some options for handling this error are described in the sections below. - -### Server-side Handling - -First, if you happen to have access to the endpoint server you are fetching from, you can add an `Access-Control-Allow-Origin` header with the value set to `*` in the server's response object. This wildcard setting in the header will allow access to the resources being requested by any site. However, note that this wildcard setting cannot be used with credentials. In the event that you need to use credentials, you can specify the origins that need support specifically, instead of the wildcard. Handling the headers on the server side is the ideal solution, but often times the issue occurs with services outside your control. In that case, your best bet is to use a CORS Proxy Server. - -### CORS Proxy Server - -Typically, the origin responsible for serving resources is also responsible for setting the access headers for those resources. However, in instances where you don't have access to the server, a proxy server can be set up to bypass the issue by acting as the intermediate server that makes the request for you, and returns the `Access-Control-Allow-Origin` header in the response with the required value needed to let the browser permit the access. - -### Hosted CORS Proxy Server - -One of the quickest ways to unblock your requests for testing, is to use a hosted proxy server which adds the CORS headers to the proxied request for you. For instance, `cors-anywhere` is a [NodeJS pakage](https://www.npmjs.com/package/cors-anywhere) which also has a free hosted demo server with it set up that you can use for quick testing. Open your browser to [https://cors-anywhere.herokuapp.com/](https://cors-anywhere.herokuapp.com/) and request temporary access to the demo server with the button shown in the screenshot: - -![CORS diagram](img/cors-demo.png) - -Then, simply prefix the URLs you're fetching with the `cors-anywhere` demo server URL of [https://cors-anywhere.herokuapp.com/](https://cors-anywhere.herokuapp.com/). For instance: - -```js -let cors_anywhere = "https://cors-anywhere.herokuapp.com/"; -let myUrl = "https://example.com/"; -let url = cors_anywhere+myUrl; - -fetch(url).then(function (response) { - console.log(response); -}) -``` - - You should then receive a successful response with that prefixed URL call: - -`Response {type: 'cors', url: 'https://cors-anywhere.herokuapp.com/https://example.com/', redirected: false, status: 200, ok: true, …}` - - - -Hosting your proxy server code in an online service like Cloudinary or Heroku is also a good option for handling CORS issues in your add-on development. These services provide a platform for deploying your code and can handle cross-origin requests for you. Additionally, using Cloudinary's [URL prefix feature](https://cloudinary.com/documentation/fetch_remote_images) can be a quick solution for handling CORS issues with remote images in your add-on development. - -### Locally Hosted CORS Proxy Server - -You can also use the `cors-anywhere` node package to create and run your own proxy server locally for testing for instance, with a few easy steps. This can be useful if you want to modify the default settings or use different functions provided by the library. Follow the steps below to install and use it. Also be sure to run it on it's own port separate from where your add-on is running. Once you have it working as desired, you can modify the settings to host it externally to suit your needs. - -1. Install the `cors-anywhere` node package: - - `npm install -g cors-anywhere` (or `npm i cors-anywhere` to install it in your current directory) - -2. Create a file called `server.js` in your favorite editor and add the following to it: - - ```js - // Listen on a specific host via the HOST environment variable - var host = process.env.HOST || '0.0.0.0'; - // Listen on a specific port via the PORT environment variable - var port = process.env.PORT || 8080; - - var cors_proxy = require('cors-anywhere'); - cors_proxy.createServer({ - originWhitelist: [], // Allow all origins - requireHeader: ['origin', 'x-requested-with'], - removeHeaders: ['cookie', 'cookie2'] - }).listen(port, host, function() { - console.log('Running CORS Anywhere on ' + host + ':' + port); - }); - ``` - -3. Run the server: - `node server.js` - - or optionally pass in a host and port when you run it: - `HOST=0.0.0.0 PORT=8080 node proxy-server.js` - - - -#### HTTPS URL Support - -By default, only `http` URLs are allowed with the sample code above (though the demo server supports either). To access `https` resources with your locally running script, you need to create and pass in a key and certificate in an `httpsOptions` object and include it as another object passed into the `createServer` call, such as: - -```js -cors_anywhere = createServer({ - httpsOptions: { - key: fs.readFileSync(path.join(__dirname, 'key.pem')), - cert: fs.readFileSync(path.join(__dirname, 'cert.pem')), - }, -}); -``` - -## CORS / COEP Handling - -The value of the **Cross-Origin-Embedder-Policy** (COEP) header for add-on resources is set to `require-corp`. With COEP set to `require-corp`, resources loaded from within the document need to have CORP / CORS enabled. If you see any issues with fetch or using images, you can try implementing one of the following solutions. - -1. For http requests, make sure that the resource server responds with the `Cross-Origin-Resource-Policy: cross-origin` header. See [this link](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy) for reference. - -2. If you're using the `` tag and your resource is being served with CORS, add the `crossorigin` attribute to the HTML tag loading it, for example: ``. See [this link](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) for more details. diff --git a/src/pages/guides/develop/img/Cross-origin isolation for third-party add-on developers/images/image14.png b/src/pages/guides/develop/img/Cross-origin isolation for third-party add-on developers/images/image14.png deleted file mode 100644 index 55ab9d9b9..000000000 Binary files a/src/pages/guides/develop/img/Cross-origin isolation for third-party add-on developers/images/image14.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-1.png b/src/pages/guides/develop/img/coi-test-1.png deleted file mode 100644 index e266e7e20..000000000 Binary files a/src/pages/guides/develop/img/coi-test-1.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-10.png b/src/pages/guides/develop/img/coi-test-10.png deleted file mode 100644 index 6607a51e8..000000000 Binary files a/src/pages/guides/develop/img/coi-test-10.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-11.png b/src/pages/guides/develop/img/coi-test-11.png deleted file mode 100644 index 2e60010f2..000000000 Binary files a/src/pages/guides/develop/img/coi-test-11.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-12.png b/src/pages/guides/develop/img/coi-test-12.png deleted file mode 100644 index b9efde6e3..000000000 Binary files a/src/pages/guides/develop/img/coi-test-12.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-13.png b/src/pages/guides/develop/img/coi-test-13.png deleted file mode 100644 index 136d6f6fd..000000000 Binary files a/src/pages/guides/develop/img/coi-test-13.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-14.png b/src/pages/guides/develop/img/coi-test-14.png deleted file mode 100644 index a531073d9..000000000 Binary files a/src/pages/guides/develop/img/coi-test-14.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-2.png b/src/pages/guides/develop/img/coi-test-2.png deleted file mode 100644 index 13ace59fd..000000000 Binary files a/src/pages/guides/develop/img/coi-test-2.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-3.png b/src/pages/guides/develop/img/coi-test-3.png deleted file mode 100644 index eb4e86454..000000000 Binary files a/src/pages/guides/develop/img/coi-test-3.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-4.png b/src/pages/guides/develop/img/coi-test-4.png deleted file mode 100644 index 27857fe24..000000000 Binary files a/src/pages/guides/develop/img/coi-test-4.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-5.png b/src/pages/guides/develop/img/coi-test-5.png deleted file mode 100644 index 53c93c1ce..000000000 Binary files a/src/pages/guides/develop/img/coi-test-5.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-6.png b/src/pages/guides/develop/img/coi-test-6.png deleted file mode 100644 index 5d50bd255..000000000 Binary files a/src/pages/guides/develop/img/coi-test-6.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-7.png b/src/pages/guides/develop/img/coi-test-7.png deleted file mode 100644 index 55ab9d9b9..000000000 Binary files a/src/pages/guides/develop/img/coi-test-7.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-8.png b/src/pages/guides/develop/img/coi-test-8.png deleted file mode 100644 index 3e2cd3efe..000000000 Binary files a/src/pages/guides/develop/img/coi-test-8.png and /dev/null differ diff --git a/src/pages/guides/develop/img/coi-test-9.png b/src/pages/guides/develop/img/coi-test-9.png deleted file mode 100644 index 2cc6e84a1..000000000 Binary files a/src/pages/guides/develop/img/coi-test-9.png and /dev/null differ diff --git a/src/pages/guides/develop/img/cors-demo.png b/src/pages/guides/develop/img/cors-demo.png deleted file mode 100644 index 4975d27cb..000000000 Binary files a/src/pages/guides/develop/img/cors-demo.png and /dev/null differ diff --git a/src/pages/guides/develop/img/lit-logo.svg b/src/pages/guides/develop/img/lit-logo.svg deleted file mode 100644 index 5c92e7d44..000000000 --- a/src/pages/guides/develop/img/lit-logo.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - - - - - - - - - - diff --git a/src/pages/guides/develop/img/memory-consumption.png b/src/pages/guides/develop/img/memory-consumption.png deleted file mode 100644 index df4a20e77..000000000 Binary files a/src/pages/guides/develop/img/memory-consumption.png and /dev/null differ diff --git a/src/pages/guides/develop/img/menu_task_mgr.png b/src/pages/guides/develop/img/menu_task_mgr.png deleted file mode 100644 index 7e85a63c3..000000000 Binary files a/src/pages/guides/develop/img/menu_task_mgr.png and /dev/null differ diff --git a/src/pages/guides/develop/img/show-cors.png b/src/pages/guides/develop/img/show-cors.png deleted file mode 100644 index 9fd5c39cb..000000000 Binary files a/src/pages/guides/develop/img/show-cors.png and /dev/null differ diff --git a/src/pages/guides/develop/img/task-mgr.png b/src/pages/guides/develop/img/task-mgr.png deleted file mode 100644 index 8c4786d04..000000000 Binary files a/src/pages/guides/develop/img/task-mgr.png and /dev/null differ diff --git a/src/pages/guides/develop/img/ts-logo-128.svg b/src/pages/guides/develop/img/ts-logo-128.svg deleted file mode 100644 index b65a93a8d..000000000 --- a/src/pages/guides/develop/img/ts-logo-128.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/src/pages/guides/develop/index.md b/src/pages/guides/develop/index.md deleted file mode 100644 index d6f0be13b..000000000 --- a/src/pages/guides/develop/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -keywords: - - Adobe Express - - Express Add-on SDK - - Express Editor - - Adobe Express - - Add-on SDK - - SDK - - JavaScript - - Extend - - Extensibility - - API - - Add-on Manifest -title: Guides -description: Useful guides to aid in the development of Adobe Express add-ons, including common use case examples, CORS handling and other development-related resources. -contributors: - - https://github.com/hollyschinsky ---- - -# Overview - -This section provides a set of guides to help you in the development stage of your add-on. - -## Introduction - -In these guides, you'll find detailed information about [implementing common use cases](../learn/how_to/index.md), [web frameworks, libraries and bundling](../build/advanced-topics/frameworks-libraries-bundling.md), [performance tips](../build/advanced-topics/performance.md), and more. - -Begin by watching this short video below which provides an introduction to some of the add-on features and APIs available for use in your add-ons.

- -
- -
diff --git a/src/pages/guides/getting_started/changelog.md b/src/pages/guides/getting_started/changelog.md index 9d0e29b6c..9b1c3e088 100644 --- a/src/pages/guides/getting_started/changelog.md +++ b/src/pages/guides/getting_started/changelog.md @@ -3,15 +3,18 @@ keywords: - Adobe Express - Express Add-on SDK - Express Editor - - Adobe Express - Add-on SDK - SDK - JavaScript - Extend - Extensibility - - API + - Add-ons + - Add-on UI SDK - Add-on Manifest - - AddOnSdk + - AddOnUISdk + - Document Sandbox + - Document API + - Changelog title: What's New description: Contains a running log of changes to the add-on documentation, SDK, CLI, etc. contributors: @@ -22,6 +25,36 @@ contributors: # Changelog +## 2025-11-29 + +### Code Playground Updates + +The Adobe Express Code Playground has received a major update with the release of a new set of features and improvements. + +- Open Code Playground with a single click ([https://www.adobe.com/go/addon-playground](https://www.adobe.com/go/addon-playground)) or find the **Code Playground** button in the top navigation bar of the How-to guides, Hello World!, Code Playground pages, and other sections. You can also bookmark links that point to either the [Script](https://www.adobe.com/go/addon-playground?executionMode=script) or [Add-on](https://www.adobe.com/go/addon-playground) Mode. +- The Code Playground now supports multiple sessions backed up in the cloud, allowing you to save your work and resume where you left off anywhere. Check out the **More** menu to [manage your sessions](./code-playground-workflow.md#session-management) (find, rename, or delete). +- Now you can try out the code blocks (e.g. in the [How-to guides](../learn/how_to/use_text.md)) by simply clicking on the **Try in playground** button. +- The [Code Playground](./code-playground.md) documentation has been **updated and split into multiple pages** for better organization. + - [Overview](./code-playground.md) + - [Script Mode](./code-playground-script-mode.md) + - [Add-on Mode](./code-playground-addon-mode.md) + - [Workflow & Productivity](./code-playground-workflow.md) + - [Troubleshooting](./code-playground-troubleshooting.md) + +### Added + +- It's now easier to identify Console logs coming from the CLI or Code Playground, because they automatically include new [helpful prefixes](./code-playground-workflow.md#debugging) such as `[Playground: Add-on]`, `[Playground: Script]`, and `[Add-on: ]`. +- Open Add-on testing window with a single click. Bookmark the URL ([https://www.adobe.com/go/addon-cli](https://www.adobe.com/go/addon-cli)) to easily access it later. +- New Express-specific Document API classes: [`ExpressContext`](../../references/document-sandbox/document-apis/classes/ExpressContext.md), [`ExpressEditor`](../../references/document-sandbox/document-apis/classes/ExpressEditor.md), and [`ExpressViewport`](../../references/document-sandbox/document-apis/classes/ExpressViewport.md), which inherit from the corresponding non-specific Classes. +- New Text classes: [`StandaloneTextContentModel`](../../references/document-sandbox/document-apis/classes/StandaloneTextContentModel.md) and [`ThreadedTextContentModel`](../../references/document-sandbox/document-apis/classes/ThreadedTextContentModel.md), representing a complete piece of text content contained within a single [`StandaloneTextNode`](../../references/document-sandbox/document-apis/classes/StandaloneTextNode.md) or split across multiple [`ThreadedTextNode`](../../references/document-sandbox/document-apis/classes/ThreadedTextNode.md)s. +- **Experimental** [`ImageRectangleNode.fetchBitmapImage()`](../../references/document-sandbox/document-apis/classes/ImageRectangleNode.md#fetchbitmapimage) method - Fetch the bitmap image associated with the image rectangle node. +- **Experimental** [`BitmapImage.data()`](../../references/document-sandbox/document-apis/classes/BitmapImage.md#data) method - Fetch the bitmap image data as a Blob. + +### Updated + +- The `Context.currentPage()` method has moved to the new [`ExpressContext.currentPage()`](../../references/document-sandbox/document-apis/classes/ExpressContext.md#currentpage). +- The `Viewport` class has been renamed to [`ExpressViewport`](../../references/document-sandbox/document-apis/classes/ExpressViewport.md). + ## 2025-11-10 ### Added @@ -35,7 +68,7 @@ contributors: ### Added - **Experimental** [`rescaleProportionalToHeight()`](../../references/document-sandbox/document-apis/classes/Node.md#rescaleproportionaltoheight) method - Proportional height scaling for all node types -- **Experimental** [`rescaleProportionalToWidth()`](../../references/document-sandbox/document-apis/classes/Node.md#rescaleproportionaltowidth) method - Proportional width scaling for all node types +- **Experimental** [`rescaleProportionalToWidth()`](../../references/document-sandbox/document-apis/classes/Node.md#rescaleproportionaltowidth) method - Proportional width scaling for all node types - **Experimental** [`resizeToCover()`](../../references/document-sandbox/document-apis/classes/Node.md#resizetocover) method - Resize nodes to cover specified dimensions - **Experimental** [`resizeToFitWithin()`](../../references/document-sandbox/document-apis/classes/Node.md#resizetofitwithin) method - Resize nodes to fit within specified dimensions - **Experimental** [`appendText()`](../../references/document-sandbox/document-apis/classes/TextContentModel.md#appendtext) method - Append text to existing content @@ -141,7 +174,7 @@ With MCP-enabled IDEs (Cursor, Claude Desktop, VS Code etc.), developers can [co ### Added -- The [Code Playground](./code_playground.md) now includes a download feature that allows developers to export their playground code as a zip file containing both the add-on folder structure and a standalone script file. This enables seamless transition from prototyping in the playground to local development using the CLI. +- The [Code Playground](./code-playground.md) now includes a download feature that allows developers to export their playground code as a zip file containing both the add-on folder structure and a standalone script file. This enables seamless transition from prototyping in the playground to local development using the CLI. ## 2025-07-27 @@ -260,7 +293,7 @@ While there are redirects in place, please **add** `https://express.adobe.com/st ### Updated -- The [Code Playground](./code_playground.md) documentation has been updated with details about the new [Script Mode](./code_playground.md#how-to-use-script-mode) and [Local Persistence](./code_playground.md#saving-your-work) features, as well as additional details around existing features. The updates include: +- The [Code Playground](./code-playground.md) documentation has been updated with details about the new [Script Mode](./code-playground-script-mode.md#how-to-use-script-mode) and [Local Persistence](./code-playground-workflow.md) features, as well as additional details around existing features. The updates include: - New sections explaining Script Mode and Add-on Mode. - Detailed descriptions of the different tabs available in the Add-on mode and what type of code belongs in each. @@ -421,8 +454,8 @@ Stabilized [`importPdf()`](../../references/addonsdk/app-document.md#importpdf) ### Added -- A new [`Viewport`](../../references/document-sandbox/document-apis/classes/Viewport.md) class has been added to the Document APIs. [`Viewport`](../../references/document-sandbox/document-apis/classes/Viewport.md) represents the canvas area currently visible on-screen. -- A new API [`bringIntoView`](../../references/document-sandbox/document-apis/classes/Viewport.md#bringIntoView) have been added which adjusts the viewport to make the node's bounds visible on-screen, assuming all bounds are within the artboard bounds. +- A new [`Viewport`](../../references/document-sandbox/document-apis/classes/ExpressViewport.md) class has been added to the Document APIs. `Viewport` represents the canvas area currently visible on-screen. +- A new API [`bringIntoView`](../../references/document-sandbox/document-apis/classes/ExpressViewport.md#bringIntoView) have been added which adjusts the viewport to make the node's bounds visible on-screen, assuming all bounds are within the artboard bounds. ## 2025-01-13 @@ -508,7 +541,7 @@ You must provide trader details by February 16, 2025, to keep your add-on visibl ## 2024-05-21 -- The [Quickstart](./quickstart.md) and [Distribute](../build/distribute/index.md) guides have been updated to reflect major UI/UX improvements for in-app workflows, particularly around distribution and listing management. +- The [Quickstart](./hello-world.md) and [Distribute](../build/distribute/index.md) guides have been updated to reflect major UI/UX improvements for in-app workflows, particularly around distribution and listing management. - The Add-ons tab is now active also in the Adobe Express home page, regardless of whether a project is open or not. - A new section on Marketplace [rejections](../build/distribute/rejections.md) has been added, highlighting the most common problems found during the add-on review process and how to avoid them. - The [Manifest Reference](../../references/manifest/index.md) has been updated with two new permission properties: `microphone` and `camera`. @@ -517,7 +550,7 @@ You must provide trader details by February 16, 2025, to keep your add-on visibl - A new [`VisualNode`](../../references/document-sandbox/document-apis/classes/VisualNode.md) class has been added to the Document APIs, and represents any node that can be visually perceived in the content. - New Document APIs have been added: - - [`currentPage`](../../references/document-sandbox/document-apis/classes/Context.md#currentpage) Context accessor: returns the active page. + - [`currentPage`](../../references/document-sandbox/document-apis/classes/ExpressContext.md#currentpage) Context accessor: returns the active page. - [`visualRoot`](../../references/document-sandbox/document-apis/classes/VisualNode.md#visualroot) accessor: the highest ancestor that still has visual presence in the document—typically, an Artboard. - [`cloneInPlace()`](../../references/document-sandbox/document-apis/classes/PageNode.md#cloneinplace) method: clones a Page, all artboards within it, and all content within those artboards. - Support to Bounds has been added in several classes: [`boundsInParent`](../../references/document-sandbox/document-apis/classes/Node.md#boundsinparent); `boundsLocal` (for both [GroupNode](../../references/document-sandbox/document-apis/classes/GroupNode.md#boundslocal) and [VisualNode](../../references/document-sandbox/document-apis/classes/VisualNode.md#boundslocal)); [`centerPointLocal`](../../references/document-sandbox/document-apis/classes/VisualNode.md#centerpointlocal); [`topLeftLocal`](../../references/document-sandbox/document-apis/classes/VisualNode.md#topleftlocal); [`boundsInNode()`](../../references/document-sandbox/document-apis/classes/Node.md#boundsinnode); [`localPointInNode()`](../../references/document-sandbox/document-apis/classes/VisualNode.md#localpointinnode); diff --git a/src/pages/guides/getting_started/code-playground-addon-mode.md b/src/pages/guides/getting_started/code-playground-addon-mode.md new file mode 100644 index 000000000..2cfbaa5db --- /dev/null +++ b/src/pages/guides/getting_started/code-playground-addon-mode.md @@ -0,0 +1,217 @@ +--- +keywords: + - Adobe Express + - Express Add-on SDK + - Adobe Express Add-on Development + - Express Editor + - Code Playground + - Add-on Mode + - UI Development + - HTML + - CSS + - JavaScript + - Iframe + - Document Sandbox +title: Code Playground - Add-on Mode +description: Learn how to use Add-on Mode in Code Playground to build complete add-ons with UI and functionality. +contributors: + - https://github.com/padmkris123 + - https://github.com/hollyschinsky + - https://github.com/ErinFinnegan + - https://github.com/undavide + - https://github.com/nimithajalal +--- + +# Code Playground - Add-on Mode + +Add-on Mode in Code Playground allows you to develop and test complete add-ons with user interfaces directly in Adobe Express, without setting up a full development environment. + +## What is Add-on Mode? + +Add-on Mode provides a complete development environment where you can: + +- Build user interfaces with HTML, CSS, and JavaScript. +- Test add-on functionality in a real Adobe Express environment. +- Prototype complete add-ons before building full projects. +- Iterate quickly on UI and logic. + +### When to Use Add-on Mode + +Use Add-on Mode when you want to develop, prototype, and test a complete add-on experience—especially when iterating quickly on UI, logic, and overall functionality within Adobe Express. + +## How to Use Add-on Mode + +### Step 1: Select Add-on Mode + +1. Click the **Add-on** toggle (next to **Script** in the top left corner of the playground window). +2. You'll see four tabs for organizing your code: HTML, CSS, Iframe JS, and Document JS. + +![Code Playground Add-on Mode](./img/addon-mode2.png) + +### Step 2: Write Your Code + +Write code for your add-on in each of the supplied tabs. This includes HTML, CSS, and JavaScript code that will run in the iframe UI or in the Document Sandbox to interact directly with the Express document. + +### Step 3: Execute Your Add-on + +Click **Run Code** to execute your add-on. Your add-on should open in an iframe on the right side of the Adobe Express window. + +### Step 4: Configure Manifest Properties (Optional) + +If you need to set [manifest properties](../../references/manifest/index.md) for your add-on (e.g., if you want to use APIs that are currently marked experimental, set permissions, OAuth domains etc): + +1. Click on the properties icon to open the Manifest JSON editing modal. +2. Configure the necessary properties. + +![Add-on Mode Manifest Settings](./img/manifest-props-addon.png) + +## Understanding the Tabs + +The Add-on mode features four tabs for organizing your code: + +### 1. HTML Tab + +This tab is for writing HTML code that defines the **structure of your add-on's user interface**. You can create elements like buttons, text fields, and layout containers here. Functionally, this tab mirrors the role of the `index.html` file you'd use in a typical add-on project. + +**Example:** + +```html +
+

My Add-on

+ + +
+``` + +### 2. CSS Tab + +**Style** your add-on's HTML elements in this tab. Create a visually appealing interface consistent with Adobe Express design patterns. This section corresponds to the `styles.css` file in a standard add-on project. + +**Example:** + +```css +.addon-container { + padding: 20px; + font-family: 'Adobe Clean', sans-serif; +} + +#myButton { + background-color: #0073e6; + color: white; + border: none; + padding: 10px 20px; + border-radius: 4px; + cursor: pointer; +} + +#myInput { + width: 100%; + padding: 8px; + border: 1px solid #ccc; + border-radius: 4px; + margin-top: 10px; +} +``` + +### 3. Iframe JS Tab + +This tab is for writing **JavaScript code that runs in the iframe context** of your add-on. Here, you can interact with: + +- The [Add-on UI SDK (`addOnUISdk`)](../../references/addonsdk/index.md). +- The DOM elements in your HTML. +- Event handlers for your UI components. + +In case you are familiar with the add-on project structure, this tab corresponds to the code in the `index.js` file. + +**Example:** + +```js +// Wait for the add-on UI SDK to be ready +addOnUISdk.ready.then(() => { + console.log('Add-on UI SDK is ready'); + + // Get references to DOM elements + const button = document.getElementById('myButton'); + const input = document.getElementById('myInput'); + + // Add event listeners + button.addEventListener('click', () => { + const text = input.value; + if (text) { + // Send message to Document JS tab + addOnUISdk.app.documentSandbox.dispatch({ + type: 'ADD_TEXT', + payload: { text } + }); + } + }); +}); +``` + +### 4. Document JS Tab + +This tab is where you write **JavaScript code that interacts directly with the Adobe Express document**. It runs in the [Document Sandbox](../../references/document-sandbox/index.md) environment and gives you access to: + +- Document manipulation capabilities with the [Document APIs](../../references/document-sandbox/document-apis/index.md). +- [Communication APIs](../../references/document-sandbox/communication/index.md) to facilitate interaction between the iframe context and the Document Sandbox. + +The Document JS tab corresponds to the code typically found in the `code.js` file of a complete add-on project. + +**Example:** + +```js +// Import necessary modules +import { editor, text } from 'express-document-sdk'; + +// Listen for messages from the iframe +addOnUISdk.app.documentSandbox.addEventListener('message', (event) => { + if (event.data.type === 'ADD_TEXT') { + addTextToDocument(event.data.payload.text); + } +}); + +async function addTextToDocument(textContent) { + try { + // Create a new text node + const textNode = await text.create({ + text: textContent, + fontSize: 24, + fontFamily: 'Arial' + }); + + // Add it to the document + editor.context.insertNode(textNode); + + console.log('Text added to document'); + } catch (error) { + console.error('Error adding text:', error); + } +} +``` + +## Key Differences from Script Mode + +| Feature | Script Mode | Add-on Mode | +| --------------------- | ------------------ | ----------------------------- | +| **Global Await** | Yes | No - must use async functions | +| **Automatic Imports** | Yes | No - must import manually | +| **UI Building** | No | Yes - full HTML/CSS/JS | +| **API Access** | Document APIs only | Document APIs + Add-on UI SDK | + +## Transitioning from Script Mode + +If you've already developed functionality in Script Mode: + +1. Copy your code from Script Mode +2. Paste it into the **Document JS** tab +3. Add the necessary `import` statements +4. Wrap your code in appropriate functions +5. Build your UI in the other tabs +6. Set up communication between iframe and Document Sandbox + +## Next Steps + +- **[Workflow & Productivity](./code-playground-workflow.md)**: Learn keyboard shortcuts and session management +- **[Troubleshooting](./code-playground-troubleshooting.md)**: Get help with common issues +- **[API References](../../references/index.md)**: Learn about the Document APIs and Add-on SDK +- **[How-To Guides](../learn/how_to/index.md)**: Master specific techniques and best practices diff --git a/src/pages/guides/getting_started/code-playground-script-mode.md b/src/pages/guides/getting_started/code-playground-script-mode.md new file mode 100644 index 000000000..8c4666900 --- /dev/null +++ b/src/pages/guides/getting_started/code-playground-script-mode.md @@ -0,0 +1,132 @@ +--- +keywords: + - Adobe Express + - Express Add-on SDK + - Adobe Express Add-on Development + - Express Editor + - Code Playground + - Script Mode + - Document APIs + - Document Sandbox + - JavaScript + - Prototyping +title: Code Playground - Script Mode +description: Learn how to use Script Mode in Code Playground for quick document manipulation and API testing. +contributors: + - https://github.com/padmkris123 + - https://github.com/hollyschinsky + - https://github.com/ErinFinnegan + - https://github.com/undavide + - https://github.com/nimithajalal +--- + +# Code Playground - Script Mode + +Script Mode in Code Playground is the quickest way to try out [Document APIs](../learn/platform_concepts/document-api.md) that interact with Express document directly without the need for a full user interface. + +## What is Script Mode? + +Script Mode is designed for rapid prototyping and learning. It provides a simplified, code-focused environment where you can: + +- Test Document API calls directly +- Explore how the Document APIs work +- Experiment with document manipulation +- Debug specific pieces of functionality + +Script mode is focused on **code interactions** and **does not support building a user interface**. If you want to create a UI, switch to [Add-on Mode](./code-playground-addon-mode.md). + + + +The code you write in this mode is equivalent to the code you would write and use in the `sandbox/code.js` file in an add-on project running locally. + +### When to Use Script Mode + +Use Script Mode when you want to quickly experiment with Document API behavior—whether you’re learning the APIs, testing specific functionality, debugging isolated code snippets, or prototyping document-manipulation logic without UI considerations. + +Script mode is ideal to test code snippets in our [How-to guides](#how-to-guides). + +## How to Use Script Mode + +![Code Playground Script Mode](./img/script-mode2.png) + +### Step 1: Select Script Mode + +1. Click the **Script** toggle in the top left corner of the playground window +2. You'll see a single code editor where you can write your Document API code + +### Step 2: Write Your Code + +Enter your [Document API](../../references/document-sandbox/document-apis/index.md) code in the editor. You can: + +- Manipulate the document directly. +- Add shapes or text. +- Change styles and properties. +- Use the automatically available [`editor`](../../references/document-sandbox/document-apis/classes/Editor.md) object. + +### Step 3: Execute Your Script + +Click the **Run Code** button in the right corner of the playground window to see changes in the current document. + +### Step 4: Configure Experimental APIs (Optional) + +If you want to use Document APIs that are currently marked experimental: + +1. Click on the properties icon to open the [Manifest JSON](../../references/manifest/index.md#requirements) editing modal +2. Toggle **experimentalApis** to enable experimental features + +![Script Mode Manifest Settings](./img/manifest-props-script.png) + +## Key Features + +### Global Await Support + +The script runtime provides a global `async` wrapper, allowing you to use `await` directly when executing asynchronous code, without needing to wrap it in an `async` function: + +```js +// The script runtime provides an async wrapper to allow this: +const textNode = editor.context.selection[0]; +const lato = await fonts.fromPostscriptName("Lato-Light"); +``` + +This is particularly useful for API calls that return promises, where an `await` is needed to pause the execution of an `async` function until the Promise is resolved or rejected. + +### Automatic Imports + +Script mode automatically imports all the necessary `express-document-sdk` modules like `editor`, `colorUtils`, and `constants` for the [Document APIs](../../references/document-sandbox/document-apis/index.md). + + + +You don't need to, and should not, add any `import` statements yourself in the Script Mode of the Code Playground; they are redundant and will **cause errors**. + +Once you switch to the [Add-on Mode](./code-playground-addon-mode.md) or to your local add-on development environment, you will need to make sure to handle your `async` functions and add back the necessary `import` statements manually. + +## Learning Resources + +### How-to Guides + +Head over to our [How-to guides](../learn/how_to/index.md) to see some examples of using the Document APIs with example code snippets: + +- [How to Use Geometry](../learn/how_to/use_geometry.md) +- [How to Use Color](../learn/how_to/use_color.md) +- [How to Use Text](../learn/how_to/use_text.md) + +### API References + +- [Document APIs](../../references/document-sandbox/document-apis/index.md): Complete reference for all available Document APIs +- [Document Sandbox](../../references/document-sandbox/index.md): Learn about the Document Sandbox environment + +## Transitioning to Add-on Mode + +Once you've tested your code in Script mode, you can easily transition it into [Add-on Mode](./code-playground-addon-mode.md) to build a user interface around your functionality: + +1. Use the **Copy** button in the right corner to quickly copy your code to the clipboard +2. Click the **Add-on** button to enter Add-on Mode +3. Paste the code into the **Document JS** tab +4. Add the necessary `import` statements and handle `async` functions manually +5. Build your UI in the HTML, CSS, and Iframe JS tabs + +## Next Steps + +- **[Add-on Mode Guide](./code-playground-addon-mode.md)**: Learn how to build complete add-ons with UI +- **[Workflow & Productivity](./code-playground-workflow.md)**: Master keyboard shortcuts and session management +- **[Troubleshooting](./code-playground-troubleshooting.md)**: Get help with common issues diff --git a/src/pages/guides/getting_started/code-playground-troubleshooting.md b/src/pages/guides/getting_started/code-playground-troubleshooting.md new file mode 100644 index 000000000..759bfd006 --- /dev/null +++ b/src/pages/guides/getting_started/code-playground-troubleshooting.md @@ -0,0 +1,237 @@ +--- +keywords: + - Adobe Express + - Express Add-on SDK + - Adobe Express Add-on Development + - Code Playground + - Troubleshooting + - FAQs + - Common Issues + - Support + - Help +title: Code Playground - Troubleshooting +description: Get help with common Code Playground issues and find answers to frequently asked questions. +contributors: + - https://github.com/padmkris123 + - https://github.com/hollyschinsky + - https://github.com/ErinFinnegan + - https://github.com/undavide + - https://github.com/nimithajalal +--- + +# Code Playground - Troubleshooting + +Get help with common Code Playground issues and find answers to frequently asked questions. + +## Frequently Asked Questions + +### What is the Adobe Express Code Playground? + +The Adobe Express Code Playground is a lightweight code editor designed for fast and effortless prototyping. It allows you to experiment with simple code snippets to build and refine add-ons, quickly turning ideas into functional features. + +### Is it free to use? + +Yes, the Code Playground is free to use. You can access all its features without any cost and start prototyping and creating add-ons right away. + +### Do I need coding experience? + +While some basic coding knowledge is helpful, Playground is designed to be beginner-friendly and accessible. Its intuitive interface and simple code snippets make it easier for both experienced developers and those newer to coding to create and test add-ons. + +### How do I start creating add-ons? + +Getting started is simple. Activate the playground, experiment with code snippets, and start building your add-ons. Use the real-time preview feature to see your changes instantly and iterate on your ideas with ease. + +### Where can I go for help? + +[Join our Discord](http://discord.gg/nc3QDyFeb4) to chat with the add-on developer community. + +### I can't find my downloaded zip file. Where is it? + +Check your browser's default download location, you can also review your browser's download settings to see where files are being saved. If you have blocked downloads in your browser, you may need to unblock the download. + +## Common Issues + +### Code Playground Not Opening + +**Problem:** The Code Playground window doesn't open when you click the toggle. + +**Solutions:** + +1. Make sure Add-on Development mode is enabled in your Adobe Express settings. +2. Try refreshing the page and attempting again. +3. Check if you have a document open in Adobe Express. +4. Clear your browser cache and cookies. +5. Try using a different browser. + +### Code Not Running + +**Problem:** Your code doesn't execute when you click "Run Code". + +**Solutions:** + +1. Check for syntax errors in your code. +2. Ensure you're using the correct mode (Script vs Add-on) for your use case. +3. Verify that all required APIs are properly imported. +4. Check the browser console for error messages. +5. Sessions that are in the [Archived](./code-playground-workflow.md#session-limits-and-lifecycle) state cannot be run. You can download your code to continue working on it locally, or copy it to a new session. +6. Try running a simple test code first. + +### Session Not Saving + +**Problem:** Your work is not being saved between sessions. + +**Solutions:** + +1. **Check auto-save settings:** Code is not saved automatically. Please read the [Save Your Work](./code-playground-workflow.md#save-your-work) section for more details on how to save. +2. Make sure you're not in incognito/private browsing mode +3. Try saving manually using the keyboard shortcut (Ctrl + Shift + S or Cmd + Shift + S) +4. Clear browser cache and try again +5. Check if you have sufficient storage space—you might have reached the maximum number of sessions per user. Delete unused sessions to free up space. +6. Any changes to [Archived](./code-playground-workflow.md#session-limits-and-lifecycle) sessions are not saved. + +### Performance Issues + +**Problem:** The playground is running slowly or freezing. + +**Solutions:** + +1. Avoid heavy computations in the iframe context. +2. Use async/await properly for document operations. +3. Test with smaller documents first. +4. Break down large operations into smaller chunks. +5. Close other browser tabs to free up memory. + +### API Errors + +**Problem:** Getting errors when using Document APIs. + +**Solutions:** + +1. Check if you need to enable experimental APIs in the manifest. +2. Verify that you're using the correct API syntax. +3. Ensure you're in the right mode (Script vs Add-on). +4. Check the [API documentation](../../references/document-sandbox/document-apis/index.md) for correct usage. +5. Try using the API in a simpler context first. + +### UI Not Displaying + +**Problem:** Your add-on UI is not showing up in Add-on Mode. + +**Solutions:** + +1. Check that your HTML is properly structured. +2. Verify that your CSS is not hiding elements. +3. Ensure your JavaScript is running without errors. +4. Check the browser console for error messages. +5. Try a simple HTML structure first. + +### Communication Issues + +**Problem:** Communication between iframe and Document Sandbox is not working. + +**Solutions:** + +1. Verify that you're using the correct communication APIs. +2. Check that message types and payloads are properly structured. +3. Ensure both sides are listening for messages. +4. Test with simple messages first. +5. Check the [Communication API documentation](../../references/document-sandbox/communication/index.md) + +## Browser Compatibility + +### Supported Browsers + +Code Playground works best with the latest versions of the following browsers: + +- Chrome +- Firefox +- Safari +- Edge + +### Browser-Specific Issues + +**Chrome:** + +- Make sure you have the latest version. +- Check if any extensions are interfering. +- Try disabling extensions temporarily. + +**Firefox:** + +- Ensure JavaScript is enabled. +- Try disabling enhanced tracking protection. + +**Safari:** + +- Make sure JavaScript is enabled. +- Check if content blockers are interfering. +- Try disabling private browsing mode. + +**Edge:** + +- Ensure you're using the Chromium-based version. +- Check if tracking prevention is affecting functionality. +- Try disabling extensions. + +## Getting Additional Help + +### Community Support + +- **[Discord Community](http://discord.gg/nc3QDyFeb4)**: Chat with fellow developers and get real-time help. +- **GitHub Issues**: Report bugs and request features. +- **Documentation**: Check our comprehensive guides and API references. + +### Documentation Resources + +- **[API References](../../references/index.md)**: Complete reference for all available APIs. +- **[How-To Guides](../learn/how_to/index.md)**: Step-by-step tutorials for common tasks. +- **[Code Samples](../learn/samples.md)**: Example code to get you started. +- **[Local Development](../getting_started/local_development/index.md)**: Set up a full development environment. + +### Reporting Issues + +When reporting issues, please include: + +1. **Browser and version** +2. **Operating system** +3. **Steps to reproduce the issue** +4. **Expected vs actual behavior** +5. **Console error messages (if any)** +6. **Screenshots or screen recordings (if helpful)** + +## Best Practices for Avoiding Issues + +### Code Organization + +- Use clear, descriptive variable and function names. +- Comment your code for better maintainability. +- Break down complex functionality into smaller functions. +- Test your code incrementally. + +### Error Handling + +- Always include proper error handling in your code. +- Use try-catch blocks for async operations. +- Log errors to the console for debugging. +- Test edge cases and error conditions. + +### Performance + +- Avoid heavy computations in the iframe context. +- Use async/await properly for document operations. +- Test with different document sizes and complexity. +- Monitor memory usage and performance. + +### Testing + +- Test your add-on with various document types. +- Try different screen sizes and resolutions. +- Test with different user permissions. +- Validate your code before sharing. + +## Next Steps + +- **[Script Mode Guide](./code-playground-script-mode.md)**: Learn how to use Script Mode effectively. +- **[Add-on Mode Guide](./code-playground-addon-mode.md)**: Build complete add-ons with UI. +- **[Workflow & Productivity](./code-playground-workflow.md)**: Master keyboard shortcuts and session management. +- **[Local Development](../getting_started/local_development/index.md)**: Set up a full development environment. diff --git a/src/pages/guides/getting_started/code-playground-workflow.md b/src/pages/guides/getting_started/code-playground-workflow.md new file mode 100644 index 000000000..771c80847 --- /dev/null +++ b/src/pages/guides/getting_started/code-playground-workflow.md @@ -0,0 +1,201 @@ +--- +keywords: + - Adobe Express + - Express Add-on SDK + - Adobe Express Add-on Development + - Code Playground + - Workflow + - Productivity + - Keyboard Shortcuts + - Session Management + - Code Download + - Local Development +title: Code Playground - Workflow & Productivity +description: Master Code Playground workflow with keyboard shortcuts, session management, and productivity tips. +contributors: + - https://github.com/padmkris123 + - https://github.com/hollyschinsky + - https://github.com/ErinFinnegan + - https://github.com/undavide + - https://github.com/nimithajalal +--- + +# Code Playground - Workflow & Productivity + +Master the Code Playground workflow with keyboard shortcuts, session management, and productivity tips to maximize your development efficiency. + +## Transitioning Between Modes + +### From Script Mode to Add-on Mode + +Once you've tested your code in Script mode, you can easily transition it into Add-on Mode to build a user interface around your functionality: + +1. **Copy Your Code**: Use the **Copy** button in the right corner to quickly copy your code to the clipboard +2. **Switch to Add-on Mode**: Click the **Add-on** button to enter Add-on Mode +3. **Paste and Adapt**: Paste the code into the **Document JS** tab. **Note:** Don't forget you'll need to add the `import` statements for the Document APIs and handle your `async` functions manually in this mode +4. **Build Your UI**: Modify your script code to be used in the add-on context along with your front-end logic in the **HTML**, **Iframe JS**, and **CSS** tabs. Use the initial sample code provided as a reference +5. **Configure Manifest**: If you set any manifest properties (e.g., **experimentalApis**) while in Script mode, make sure to set the same in Add-on Mode as well. These settings only apply to the context of the development mode you're in +6. **Test Your Add-on**: Click the **Run Code** button to execute your code within the context of your add-on + +## Keyboard Shortcuts + +Use these keyboard shortcuts to work more efficiently: + +| Action | Windows/Linux | macOS | +| -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- | +| **Save** | Ctrl + Shift + S | Cmd + Shift + S | +| **Run** | Ctrl + Shift + Return/Enter | Cmd + Shift + Return/Enter | +| **Reset** | Ctrl + Shift + X | Cmd + Shift + X | +| **Increase font size** | Ctrl + Shift + Plus (+) | Cmd + Shift + Plus (+) | +| **Decrease font size** | Ctrl + Shift + Minus (-) | Cmd + Shift + Minus (-) | +| **Switch between tabs** | Ctrl + 1, 2, 3, 4 | Cmd + 1, 2, 3, 4 | +| **View the typings suggestions** | Ctrl + space | Cmd + space | + + + +#### TIP + +Use the "**More**" button in the top right corner of the playground window to reference the available keyboard shortcuts, start a new session, link to documentation and more. + +## Debugging + +For debugging your code, you can view the logs from Code Playground in the browser's Console. + + + +The Code Playground **prefixes the messages in the Console** with descriptive strings to help you distinguish them from other messages. + +- `[Playground: Add-on]` for Code Playground in Add-on mode. +- `[Playground: Script]` for Code Playground in Script mode. + +Open the browser's developer tools by right-clicking on the browser window where Adobe Express is running, and selecting **Inspect** from the context menu. In the **Console**, you can filter out the messages from the Code Playground by typing just `Playground` in the filter input. + +![Code Playground Debugging](./img/playground-console-prefix.png) + +## Session Management + +### Save Your Work + +The Code Playground now backs up your sessions in the cloud, ensuring your work is safely stored and protected from accidental loss. You can know whether your session is looking at the status next to the session name. + +![Code Playground Saved Session](./img/playground--saved-session.png) + +If an issue occurs, the status will update accordingly and an error toast will appear. + +Your code is **_not saved automatically_**. The Code Playground saves your session only when you perform the following actions: + +1. Run the code. +2. Save using the [keyboard shortcut for Save](#keyboard-shortcuts). +3. Switch to a new session. +4. Exit the Code Playground (with the **X** in the upper right corner). + +### Manage and Resume Sessions + +There are two ways to resume working on one of your saved sessions: + +#### Via the Home Screen + +1. Click the **Add-ons** button in the left rail. +2. Click the **Add-on development** toggle in the top right corner of the playground window. +3. Click **New sesion** to create a new one, or +4. Select the **Playground Sessions** tab to access your saved sessions. +5. Click on the session you want to resume to open it in the Code Playground. + +![Code Playground Add-on Mode](./img/playground--sessions-from-home.gif) + +#### Via the Add-ons Panel + +If you have a **document open**, you can: + +1. Click the **Add-ons** button in the left rail and select the **Your add-ons** tab. +2. Toggle on **Code Playground** at the bottom of the panel; it will open with the last session you were working on. + +To browse your saved sessions: + +1. Click the **More** button in the top right corner of the playground window +2. Select the **Manage Sessions** item in the dropdown menu +3. You'll see a list of your saved sessions; click on one to **select it** and click the **Open** button to resume working on it. + +![Code Playground Add-on Mode](./img/playground--sessions.gif) + + + +#### Access "Your add-ons" Page + +- **Without a document open:** Click the **Add-ons** button in the left rail, then click the **Add-on development** toggle in the top right +- **With a document open:** Click the **Add-ons** button in the left rail, select the **Your add-ons** tab, then click the "Manage add-ons" link in the Add-on Testing section + +### Rename a Session + +To rename a session, click on the session name and enter a new name. Click anywhere outside the input or press Enter to save the new name. A toast will appear to confirm the change. + +![Code Playground Rename Session](./img/playground--rename-session.gif) + +### Delete a Session + +To delete a session, click on the **•••** button next to the session name and click the **Delete Session** button. You'll need to confirm the deletion by clicking the **Delete** button . A toast will appear to confirm the success of the operation. + +![Code Playground Delete Session](./img/playground--delete-session.gif) + +### Session Limits and Lifecycle + +The Code Playground supports a maximum number of sessions per user. To help manage storage and maintain system performance, sessions automatically transition through different states based on activity: + +- **Active**: Your session is actively maintained and fully functional for development. +- **Inactive**: Sessions become inactive after 60 days without any activity. Simply accessing the session and running your code will reactivate it and reset the inactivity timer. +- **Archived**: After 90 days of inactivity, sessions are automatically archived. While you can no longer run code in an archived session, you can still access and download your code to back it up locally. +- **Permanently Deleted**: Sessions are permanently deleted after 120 days of inactivity. + + + +To preserve your work, regularly access your sessions or download your code for local backup. Running your code in a session resets the inactivity clock. + +## Download Your Code + +### How to Download + +Downloading your code is a great way to save your work and continue working on it locally in your CLI. + +To download your code: + +1. Click the **More** button in the top right corner of the playground window +2. Click the **Download** button +3. This will download a zip file containing your code + +![Code Playground Download code](./img/playground--download.png) + +### Folder Structure + +The downloaded zip file will contain a folder with the following structure: + +- add-on folder +- `script.js` file + +![Downloaded Folder Structure](./img/downloaded-folder-structure.png) + +### Run Downloaded Code + +You can run your add-on folder as a local add-on project in your CLI by following the steps in the [Quickstart Guide](../getting_started/hello-world.md). There is a readme file in the add-on folder that will guide you through the process as well. + +**Note:** You cannot run the `script.js` file alone. + +## Productivity Tips + +### Development Workflow + +1. **Start with Script Mode**: Use Script Mode to prototype and test your core functionality. +2. **Iterate Quickly**: Use keyboard shortcuts to save and run code frequently. +3. **Test Incrementally**: Run your code often to catch issues early. +4. **Transition to Add-on Mode**: Once your logic is working, move to Add-on Mode to build the UI. +5. **Download for Local Development**: Use the download feature to continue development locally. + +## Troubleshooting Common Issues + +See the [Troubleshooting](./code-playground-troubleshooting.md#common-issues) page for more details on common issues and solutions. + +## Next Steps + +- **[Script Mode Guide](./code-playground-script-mode.md)**: Learn how to use Script Mode effectively +- **[Add-on Mode Guide](./code-playground-addon-mode.md)**: Build complete add-ons with UI +- **[Troubleshooting](./code-playground-troubleshooting.md)**: Get help with common issues +- **[Local Development](../getting_started/local_development/index.md)**: Set up a full development environment diff --git a/src/pages/guides/getting_started/code-playground.md b/src/pages/guides/getting_started/code-playground.md new file mode 100644 index 000000000..f1aa3acaf --- /dev/null +++ b/src/pages/guides/getting_started/code-playground.md @@ -0,0 +1,132 @@ +--- +keywords: + - Adobe Express + - Express Add-on SDK + - Adobe Express Add-on Development + - Express Editor + - Code Playground + - In-app editor + - Add-on SDK + - SDK + - JavaScript + - Extend + - Extensibility + - API + - Add-on Manifest + - Add-on dev tool + - Express Document +title: Code Playground +description: A guide to using the Code Playground in Adobe Express. +contributors: + - https://github.com/padmkris123 + - https://github.com/hollyschinsky + - https://github.com/ErinFinnegan + - https://github.com/undavide + - https://github.com/nimithajalal +--- + +# Code Playground + +The Code Playground is an in-app lightweight code editor for fast and effortless prototyping of Adobe Express add-ons. + +## Overview + +### What is Code Playground? + +Code Playground provides developers with a low-barrier entry point for add-on development, allowing you to experiment and iterate on ideas directly without any setup, from within Adobe Express. From learning the basics to rapidly prototyping advanced concepts, Code Playground accommodates all stages of add-on development. + +![Code Playground Overview](./img/playground--hero.png) + +### Key Benefits + +- **Real-Time Preview**: See your changes as you code, allowing for immediate feedback and faster adjustments. +- **Effortless Prototyping**: Quickly turn ideas into add-ons with minimal setup. +- **Rapid Implementation**: Fast-track your prototype to a product by directly pasting your code into an add-on template. +- **Persistence**: Save your work and resume where you left off. +- **Programming Assistance**: Typed definitions and auto-completion. + +### Who Should Use Code Playground? + +The Code Playground is for beginners, learners, prototypers, designers, and experienced developers who want to explore Adobe Express add-on concepts quickly and easily. It provides a lightweight space to test ideas, learn the APIs, and experiment without needing a full development environment. + +### Prerequisites + +Before using Code Playground, ensure you have: + +- An Adobe Express account. +- A document open in Adobe Express (for testing your code). + +## Getting Started + +### How to Launch the Code Playground + +To launch the Code Playground experience, follow [this link](https://www.adobe.com/go/addon-playground) or click the button below. + + + +- [Launch the Code Playground](https://www.adobe.com/go/addon-playground) + +[![Code Playground Launch](./img/playground--splash-screen.png)](https://www.adobe.com/go/addon-playground) + +In the future, you can always open the Code Playground from Adobe Express. + +**From the Home Screen:** + +1. Click the **Add-ons** button in the left rail. +2. Switch on the **Add-on development** toggle in the top right corner. +3. In the **Playground Sessions** tab, either click the **New Session** button to start a new session, or select an existing session to resume working on it. + +![Code Playground from Home Screen](./img/playground--launch-from-home.gif) + +**If you already have a document open:** + +1. With any document open in Adobe Express, click the **Add-ons** button in the left rail. +2. Select the **Your add-ons** tab. +3. Toggle on **Code Playground** at the bottom of the panel. + +![Code Playground from Home Screen](./img/playground--launch-from-doc.gif) + +### Enable Add-on Development Mode + +The Code Playground needs the add-on Development Mode to be enabled in order to work—you only need to toggle it once. When launching the Playground (e.g., from [this link](https://www.adobe.com/go/addon-playground)) for the first time, you'll be prompted to review the Developer Terms of Use and enable the Developer Mode. + +[![Playground Terms of Use](./img/playground--DTOU.png)](https://www.adobe.com/go/addon-playground) + +You can also enable or disable the add-on Development Mode from the Settings panel in Adobe Express. See the [Enable Add-on Development Mode](./hello-world.md#enable-add-on-development-mode) section in the Hello, World! guide for detailed instructions. + +## Playground modes + +The playground offers two distinct development modes (**Script** and **Add-on**), which are designed to suit different needs: + +### Mode Overview + +| Comparison Factor | Script Mode | Add-on Mode | +| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| **Intended Use** | Quick document manipulation tests and API experimentation | Building complete add-ons with full UI and functionality | +| **API Access** | [Document APIs](../../references/document-sandbox/document-apis/index.md) | [Document APIs](../../references/document-sandbox/document-apis/index.md) + [Add-on UI SDK](../../references/addonsdk/index.md) | +| **Global Await** | Yes | No | +| **Automatic Imports** | Yes | No | +| **UI Components** | Not applicable | Full HTML/CSS/JS interface creation | + +### When to Use Each Mode + +Use **Script Mode** for learning and experimenting with the Document APIs—ideal for quick tests, isolated debugging, and prototyping document logic without UI considerations. +Use **Add-on Mode** when developing a full add-on experience, including building UI, testing functionality within Adobe Express, and rapidly iterating on both interface and logic. + +## Quick Start Guides + +- **[Script Mode Guide](./code-playground-script-mode.md)**: Learn how to use Script Mode for quick document manipulation +- **[Add-on Mode Guide](./code-playground-addon-mode.md)**: Build complete add-ons with UI and functionality +- **[Workflow & Productivity](./code-playground-workflow.md)**: Master keyboard shortcuts, saving, and session management +- **[Troubleshooting](./code-playground-troubleshooting.md)**: Get help with common issues and FAQs + +## Next Steps + +Now that you understand the basics of Code Playground, explore our resources to continue building robust add-ons: + +- **[API References](../../references/index.md)**: Learn about the Document APIs and Add-on SDK. +- **[Tutorials](../learn/how_to/tutorials/index.md)**: Follow step-by-step guides to build complete add-ons. +- **[How-To Guides](../learn/how_to/index.md)**: Master specific techniques and best practices. +- **[Local Development](../getting_started/local_development/index.md)**: Set up a full development environment for production-ready add-ons +- **Code Samples:** Get inspired by checking out [our code samples](../learn/samples.md) to see what's possible. +- **Community Support:** Chat with fellow developers on [Discord](http://discord.gg/nc3QDyFeb4), in the [Forums](https://community.adobe.com/t5/adobe-express-developers/ct-p/ct-adobe-express-developers), or join us for our [Office Hours](https://developer.adobe.com/developers-live). diff --git a/src/pages/guides/getting_started/code_playground.md b/src/pages/guides/getting_started/code_playground.md deleted file mode 100644 index 6c2f8680b..000000000 --- a/src/pages/guides/getting_started/code_playground.md +++ /dev/null @@ -1,361 +0,0 @@ ---- -keywords: - - Adobe Express - - Express Add-on SDK - - Adobe Express Add-on Development - - Express Editor - - Code Playground - - In-app editor - - Add-on SDK - - SDK - - JavaScript - - Extend - - Extensibility - - API - - Add-on Manifest - - Add-on dev tool - - Express Document -title: Code Playground -description: A guide to using the Code Playground in Adobe Express. -contributors: - - https://github.com/padmkris123 - - https://github.com/hollyschinsky - - https://github.com/ErinFinnegan - - https://github.com/undavide - - https://github.com/nimithajalal ---- - -# Code Playground - -The Code Playground is an in-app lightweight code editor for fast and effortless prototyping. - -## What is Code Playground? - -Code Playground provides developers with a low-barrier entry point for add-on development, allowing you to experiment and iterate on ideas directly without any setup, from within Adobe Express. From learning the basics to rapidly prototyping advanced concepts, Code Playground accommodates all stages of add-on development. - -## Who Should Use Code Playground? - -The Code Playground is designed for: - -- **Beginners**: New developers who want to experiment with Adobe Express add-on development without setting up a full development environment. -- **Prototypers**: Developers who need to quickly test concepts or ideas before implementing them in a full add-on project. -- **Learners**: Those who are learning the Document APIs and want to see immediate results of their code. -- **Experienced Developers**: Seasoned developers who want to test specific API functionality or debug isolated code snippets. -- **Designers**: UX/UI designers who want to experiment with add-on interfaces without extensive coding setup. - -## Features - -
- -| Feature | Description | -| ---------------------------- | --------------------------------------------------------------------------------------------------------- | -| **Real-Time Preview** | See your changes as you code, allowing for immediate feedback and faster adjustments. | -| **Effortless Prototyping** | Quickly turn ideas into add-ons with minimal setup. | -| **Rapid Implementation** | Fast-track your prototype to a product by directly pasting your code into an add-on template. | -| **Script Mode** | An easy way to interact with the Document APIs quickly. | -| **Programming Assistance** | Typed definitions and auto-completion. | -| **Default Boilerplate Code** | Default boilerplate code for each tab helps you get started quickly. | -| **Local Persistence** | Save your work to your browser's local storage and resume where you left off, preventing accidental loss. | -| **Keyboard Shortcuts** | Use keyboard shortcuts to save, run, and reset your code quickly. | - - - -## Development Workflow Use Cases - -The Code Playground is designed to support the following development workflow use cases: - -- **Experiment First**: Test your ideas and API interactions before committing to full add-on development. -- **Learn as You Go**: Master the basics of the Document APIs and [Add-on SDK](../../references/addonsdk/index.md) without complex setup requirements. -- **Prototype Quickly**: Build and test features in minutes instead of hours with instant feedback. -- **Bridge to Production**: Develop core functionality in Playground before moving to a complete project environment. -- **Debug with Ease**: Isolate and fix specific issues by testing API calls outside your production code. - -## How to Access Code Playground - -### Step 1: Enable Add-on Development Mode - -- Click the avatar icon in the top right corner of Adobe Express, then the gear icon to open the "Settings". -- Enable **Add-on Development** if it's not already enabled (you might need to click the **Developer Terms of Use** link the first time). - -![Enable Add-on Development](./img/playground-enable-dev-mode.gif) - -### Step 2: Open Code Playground - -- With any document open, click the **Add-ons** button in the left rail. -- Select the **Your add-ons** tab. -- Toggle on **Code Playground** at the bottom of the panel: - - ![Adobe Express Code Playground Toggle](./img/toggle-playground.png) - -- Once enabled, the playground window will open, allowing you to begin coding immediately: - - ![Adobe Express Code Playground Open](./img/playground-open.png) - -## Choose Your Development Mode - -The playground offers two distinct development modes: - -- [**Script Mode**](#script-mode): Experiment with the Adobe Express [Document Sandbox](../../references/document-sandbox/index.md). This mode is equivalent to writing code in the `sandbox/code.js` file in an add-on project running locally, but allows you to rapidly test in Express directly. -- [**Add-on Mode**](#add-on-mode): Test and iterate on your [Add-on UI](../../references/addonsdk/) and functionality with no setup required. - -
- -| Comparison Factor | Script Mode | Add-on Mode | -| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| **Purpose** | Quick document manipulation tests | Complete add-on UI and functionality | -| **Environment** | Document Sandbox only | Both iframe and Document Sandbox | -| **API Access** | [Document APIs](../../references/document-sandbox/document-apis/index.md) | [Document APIs](../../references/document-sandbox/document-apis/index.md) + [Add-on UI SDK](../../references/addonsdk/index.md) | -| **Global Await** | Yes | No | -| **Automatic Imports** | Yes | No | -| **UI Components** | No UI building | Full HTML/CSS/JS interface creation | -| **Best For** | Testing document operations | Building complete add-ons | - -## Script Mode - -### When to Use Script Mode - -- To learn how the Document APIs work -- To quickly experiment with Document API calls without UI considerations - -**Note:** The code you write in this mode is equivalent to the code you would write and use in the `sandbox/code.js` file in an add-on project running locally. - -### How to Use Script Mode - -1. Select the **Script** button in the top left corner of the playground window. -2. Enter your [Document API](../../references/document-sandbox/document-apis/index.md) code in the editor. Manipulate the document directly, add shapes or text, change styles, and more using the automatically available [`editor`](../../references/document-sandbox/document-apis/classes/Editor.md) object. -3. Execute your script by clicking the **Run Code** button in the right corner of the playground window to see changes in the current document. - -![Code Playground Script Mode](./img/script-mode.png) - -4. If you want to use Document APIs that are currently marked experimental, click on the properties icon to open the [Manifest JSON](../../references/manifest/index.md#requirements) editing modal and toggle **experimentalApis**: - -![Script Mode Manifest Settings](./img/manifest-props-script.png) - -5. Head over to our [How-to guides](../learn/how_to/index.md) to see some examples of using the Document APIs with example code snippets. For instance, the guides: - - - [How to Use Geometry](../learn/how_to/use_geometry.md) - - [How to Use Color](../learn/how_to/use_color.md) - - [How to Use Text](../learn/how_to/use_text.md) - -#### Key Considerations - -- **No UI**: Script mode is focused on Document API interactions and does not support building a user interface. If you want to create a UI, switch to [Add-on mode](#add-on-mode). - -- **Global Await**: The script runtime provides a global `async` wrapper, allowing you to use `await` directly when executing asynchronous code, without needing to wrap it in an `async` function. This is particularly useful for API calls that return promises, where an `await` is needed to pause the execution of an `async` function until the Promise is resolved or rejected. For example, loading a font is an asynchronous operation, but in Script mode you can use `await` directly to pause the execution of the script until the font is loaded, ie: - -```js -// The script runtime provides an async wrapper to allow this: -const textNode = editor.context.selection[0]; -const lato = await fonts.fromPostscriptName("Lato-Light"); -``` - -In contrast, in [**Add-on mode**](#add-on-mode) you will need to manually wrap the code in an `async` function and use `await` in it, ie: - -```js -//sandbox.code.js or Document JS tab -loadFont: async () => { - const textNode = editor.context.selection[0]; - const lato = await fonts.fromPostscriptName("Lato-Light"); -}; -``` - -- **Automatic Imports**: Script mode automatically imports the `express-document-sdk` modules, so you don't need to add import statements for the [Document APIs](../../references/document-sandbox/document-apis/index.md). However, if you do add import statements, it wont harm anything. - - - -Once you switch to the [Add-on mode](#add-on-mode) or to your local add-on development environment, you will need to make sure to handle your `async` functions and `import` statements manually. - -## Add-on Mode - -### When to Use Add-on Mode - -- To develop and test an add-on directly in Adobe Express, without having to set up a full development environment. -- To prototype an add-on before building a full project. -- To iterate quickly on your add-on's UI and logic. - -### How to Use Add-on Mode - -1. Click on the **Add-on** button (next to the **Script** button in the top left corner of the playground window). -2. Write code for your add-on in each of the supplied tabs (described below). This includes HTML, CSS, and JavaScript code that will run in the iframe UI or in the Document Sandbox to interact directly with the Express document (optionally). -3. Click **Run Code** to execute your add-on. Your add-on should open in an iframe on the right side of the Adobe Express window, ie: - -![Code Playground Add-on Mode](./img/addon-mode.png) - -4. If you need to set [manifest properties](../../references/manifest/index.md) for your add-on (ie: if you want to use APIs that are currently marked experimental, set permissions, OAuth domains etc), click on the properties icon to open the Manifest JSON editing modal: - -![Add-on Mode Manifest Settings](./img/manifest-props-addon.png) - -### Add-on Mode Tabs - -The Add-on mode features four tabs for organizing your code: - -1. **HTML Tab** - -This tab is for writing HTML code that defines the structure of your add-on's user interface. You can create elements like buttons, text fields, and layout containers here. Functionally, this tab mirrors the role of the `index.html` file you'd use in a typical add-on project. - -2. **CSS Tab** - -Style your add-on's HTML elements in this tab. Create a visually appealing interface consistent with Adobe Express design patterns. This section corresponds to the `styles.css` file in a standard add-on project. - -3. **Iframe JS Tab** - -This tab is for writing JavaScript code that runs in the iframe context of your add-on. Here, you can interact with: - -- The [Add-on UI SDK (`addOnUISdk`)](../../references/addonsdk/index.md) -- The DOM elements in your HTML -- Event handlers for your UI components - -This environment corresponds to the code you would typically write in your `index.js` or UI JavaScript files in a full add-on project. - -4. **Document JS Tab** - -This tab is where you write JavaScript code that interacts directly with the Adobe Express document. It runs in the [Document Sandbox](../../references/document-sandbox/index.md) environment and gives you access to: - -- Document manipulation capabilities with the [Document APIs](../../references/document-sandbox/document-apis/index.md) -- [Communication APIs](../../references/document-sandbox/communication/index.md) to facilitate interaction between the iframe context and the Document Sandbox. - -The Document JS tab corresponds to the code typically found in the `code.js` file of a complete add-on project. - -## Transitioning from Script Mode to Add-on Mode - -Once you've tested your code in Script mode, you can easily transition it into the [Add-on mode](#add-on-mode) to build a user interface around your new functionality. Here's how: - -1. Use the **Copy** button in the right corner to quickly copy your code to the clipboard. -2. Click the **Add-on** button to enter [Add-on mode](#add-on-mode). -3. Paste the code into the [**Document JS**](#add-on-mode-tabs) tab. **Note:** Don't forget you'll need to add the `import` statements for the Document APIs and handle your `async` functions manually in this mode. -4. Modify your script code to be used in the add-on context along with your front-end logic in the [**HTML**](#add-on-mode-tabs), [**Iframe JS**](#add-on-mode-tabs), and [**CSS**](#add-on-mode-tabs) tabs. Use the initial sample code provided as a reference. -5. If you set any manifest properties (ie: **experimentalApis**) while in [Script mode](#how-to-use-script-mode), make sure to set the same in the [Add-ons mode - Edit Manifest JSON Modal](#how-to-use-add-on-mode) as well. These settings only apply to the context of the development mode you're in. -6. Click the **Run Code** button to execute your code within the context of your add-on. - -## Workflow Tips - -Keyboard Shortcuts, local save and session management are all designed to help you get the most out of the Code Playground. - -### Keyboard Shortcuts - -
- -| Action | Windows/Linux | macOS | -| -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- | -| **Save** | Ctrl + Shift + S | Cmd + Shift + S | -| **Run** | Ctrl + Shift + Return/Enter | Cmd + Shift + Return/Enter | -| **Reset** | Ctrl + Shift + X | Cmd + Shift + X | -| **Increase font size** | Ctrl + Shift + Plus (+) | Cmd + Shift + Plus (+) | -| **Decrease font size** | Ctrl + Shift + Minus (-) | Cmd + Shift + Minus (-) | -| **Switch between tabs** | Ctrl + 1, 2, 3, 4 | Cmd + 1, 2, 3, 4 | -| **View the typings suggestions** | Ctrl + space | Cmd + space | - - - -#### TIP - -Use the "**...**" button in the top right corner of the playground window to reference the available keyboard shortcuts, start a new session, link to documentation and more. - -### Saving Your Work - -The Code Playground features local persistence to help prevent the loss of your work. This functionality ensures that your code is stored in your browser's local storage, providing a safeguard against accidental data loss. - -Code in the playground is **_not saved automatically_**. To ensure it's saved, you need to take one of the following steps: - -1. Save your work using the [keyboard shortcut for Save](#keyboard-shortcuts). -2. Run the code via the **Run Code** button or with the [keyboard shortcut for Run](#keyboard-shortcuts). -3. Exit the playground (with the **X** in the upper right corner). - -If you don't want to save your work at any time, use the [keyboard shortcut to Reset](#keyboard-shortcuts). - - - -#### IMPORTANT - -- Only your most recent session is saved. -- Storage is browser-specific (not synced across devices). -- Code is not saved in incognito/private browsing modes. -- Clearing browser data will delete saved code. - -### Downloading Your Code - -Downloading your code is a great way to save your work and continue working on it locally in your CLI. - -To download your code, click the **...** button in the top right corner of the playground window, then click the **Download** button. This will download a zip file containing your code. - -**Folder Structure:** - -The downloaded zip file will contain a folder with the following structure: - -- add-on folder -- `script.js` file - -![Downloaded Folder Structure](./img/downloaded-folder-structure.png) - -You can run your add-on folder as a local add-on project in your CLI by following the steps in the [Quickstart Guide](../getting_started/quickstart.md#step-4-load-and-run-your-add-on). There is a readme file in the add-on folder that will guide you through the process as well. - -**Note:** You cannot run the `script.js` file alone. - -### Resuming Sessions - -There are two ways to resume working on your last saved session: - -1. **Via the Add-ons Panel:** - - - With any document open, click the **Add-ons** button in the left rail. - - Select the **Your add-ons** tab. - - Toggle on **Code Playground** at the bottom of the panel. - - ![Code Playground Add-on Mode](./img/playground-on.png) - -2. **Via the Your add-ons Page:** - - - The **Your add-ons** page where you manage your add-ons now features a dedicated section for the playground, allowing you to quickly access your last session or create a new one. - - Find the **Playground Sessions** section in the **Your add-ons** page. - - Access your last session or create a new one with one click. - -![Manage Your add-ons page](./img/playground-sessions.png) - - - -#### Accessing "Your add-ons" Page - -- **Without a document open:** Click the **Add-ons** button in the left rail, then click the **Add-on development** toggle in the top right. -- **With a document open:** Click the **Add-ons** button in the left rail, select the **Your add-ons** tab, then click the "Manage add-ons" link in the Add-on Testing section. - -## Next Steps - -Now that you have the downloaded code from the Code Playground, explore our resources to continue building robust add-ons: - -- **[API References](../../references/index.md)**: Learn about the Document APIs and Add-on SDK -- **[Tutorials](../learn/how_to/tutorials/index.md)**: Follow step-by-step guides to build complete add-ons -- **[How-To Guides](../learn/how_to/index.md)**: Master specific techniques and best practices -- **[Local Development](../getting_started/local_development/index.md)**: Set up a full development environment for production-ready add-ons -- **Code Samples:** Get inspired by checking out [our code samples](../learn/samples.md) to see what's possible. -- **Community Support:** Chat with fellow developers on [Discord](http://discord.gg/nc3QDyFeb4). - -## FAQs - -### What is the Adobe Express Code Playground? - -The Adobe Express Code Playground is a lightweight code editor designed for fast and effortless prototyping. It allows you to experiment with simple code snippets to build and refine add-ons, quickly turning ideas into functional features. - -### Is it free to use? - -Yes, the Code Playground is free to use. You can access all its features without any cost and start prototyping and creating add-ons right away. - -### Do I need coding experience? - -While some basic coding knowledge is helpful, Playground is designed to be beginner-friendly and accessible. Its intuitive interface and simple code snippets make it easier for both experienced developers and those newer to coding to create and test add-ons. - -### How do I start creating add-ons? - -Getting started is simple. activate the playground, experiment with code snippets, and start building your add-ons. Use the real-time preview feature to see your changes instantly and iterate on your ideas with ease. - -### Where can I go for help? - -[Join our Discord](http://discord.gg/nc3QDyFeb4) to chat with the add-on developer community. - -### I can't find my downloaded zip file. Where is it? - -Check your browser's default download location, you can also review your browser's download settings to see where files are being saved. If you have blocked downloads in your browser, you may need to unblock the download. diff --git a/src/pages/guides/getting_started/developer-journey.md b/src/pages/guides/getting_started/developer-journey.md index 00353abf8..15085c22d 100644 --- a/src/pages/guides/getting_started/developer-journey.md +++ b/src/pages/guides/getting_started/developer-journey.md @@ -74,7 +74,7 @@ You now have a basic understanding of the Adobe Express ecosystem; if you want t ## Learn -The best way to learn is by doing! Adobe Express integrates a [Playground](../getting_started/code_playground.md) environment that allows you experiment with the code directly in the application, without the need to set up a local development environment. +The best way to learn is by doing! Adobe Express integrates a [Playground](../getting_started/code-playground.md) environment that allows you experiment with the code directly in the application, without the need to set up a local development environment.

@@ -83,13 +83,15 @@ The best way to learn is by doing! Adobe Express integrates a [Playground](../ge ### Run the Code Playground -You need to tick a few boxes in the application in order to enable it, as the animation below shows. +To launch the Code Playground experience, follow [this link](https://www.adobe.com/go/addon-playground) or click the button below. -![Enable Developer Settings](./img/enable-playground.gif) + -Once it's open, you can play with the code directly in the editor, and see the changes you make reflected in the document. The [Script Mode](./code_playground.md#script-mode) is particularly useful for experimenting with the add-on's APIs. Please refer to the complete guide to the [Code Playground](./code_playground.md) for more details. +- [Launch the Code Playground](https://www.adobe.com/go/addon-playground) -[![Code Playground](./img/playground.png)](./code_playground.md) +Once it's open, you can play with the code directly in the editor, and see the changes you make reflected in the document. The [Script Mode](./code-playground-script-mode.md) is particularly useful for experimenting with the add-on's APIs. Please refer to the complete guide to the [Code Playground](./code-playground.md) for more details. + +[![Code Playground](./img/playground.png)](./code-playground.md) ### Explore the How-to Guides @@ -111,9 +113,9 @@ To build a more complex add-on, you can use our free [Command Line Interface (CL ![doc sandbox prompt](./local_development/img/CLI-template-prompt.png) - + -We're actively working on improving the Code Playground so that existing project can be migrated to the CLI seamlessly. +The Code Playground can [export your project as a zip file](./code-playground-workflow.md#download-your-code) so that existing add-ons projects can be migrated to the CLI seamlessly. ### Next steps diff --git a/src/pages/guides/getting_started/hello-world.md b/src/pages/guides/getting_started/hello-world.md index b30d911f3..4cd31c28a 100644 --- a/src/pages/guides/getting_started/hello-world.md +++ b/src/pages/guides/getting_started/hello-world.md @@ -46,28 +46,40 @@ The [Command Line Interface (CLI)](#command-line-interface-cli) path will teach - Basic familiarity with JavaScript, HTML and CSS. - Node.js version 18 or higher (optional, only for the CLI track). -### Add-on Development mode +### Enable Add-on Development Mode -A pre-requisite for both tracks is to have enabled the **Add-on Development** mode. Open Adobe Express in the browser and see the following animation for instructions, or expand the details below for a step-by-step guide. +Before you can build add-ons, you need to enable Add-on Development mode in Adobe Express—you only need to do this once. -![Enable Add-on Development](./img/playground-enable-dev-mode.gif) + + +The first time you launch the [Code Playground](https://www.adobe.com/go/addon-playground) or [connect to your local add-on development environment](https://www.adobe.com/go/addon-cli), you can review the Developer Terms of Use and enable Developer mode.
- Click to view a list of steps to enable the Development Mode + Click to view a list of steps to manually toggle the Developer Mode
    -
  1. Click the avatar icon in the top right corner of Adobe Express, then the gear icon to open the Settings.
    2. -
  2. Enable Add-on Development if it's not already enabled. You might need to read the Developer Terms of Use first.
    3. -
  3. Close the Settings dialog.
    4. +
  4. Open Adobe Express in your browser and click the avatar icon in the top right corner.
    5. +
  5. Click the gear icon to open Settings.
    6. +
  6. Click the Developer Terms of Use link to review the terms (opens in a new tab) if you haven't already.
    7. +
  7. Click Accept and Enable to enable Add-on Development.
+ +![Enable Add-on Development](./img/playground-enable-dev-mode.gif) +
## Code Playground -We have a [dedicated page](./code_playground.md) for the Code Playground, which you can always refer to for more detailed information. Here, we'll focus on the basics to get you started, linking to the relevant sections of the full documentation and including screenshots to help you navigate the interface. +The [Code Playground](./code-playground.md) is a browser-based editor built right into Adobe Express. No installation required—just open it and start coding. -### 1. Launch it +### 1. Launch the Playground -To launch the Code Playground, see the following animation or expand the details below for a step-by-step guide. +To launch the Code Playground experience, follow [this link](https://www.adobe.com/go/addon-playground) or click the button below. + + + +- [Launch the Code Playground](https://www.adobe.com/go/addon-playground) + +Alternatively, see the following animation or expand the details below for a step-by-step guide. ![How to open the Code Playground](./img/playground-open-the-playground.gif) @@ -81,12 +93,12 @@ To launch the Code Playground, see the following animation or expand the details -### 2. Run your first script +### 2. Run Your First Script -The Code Playground allows you to operate in [two modalities](./code_playground.md#choose-your-development-mode): +The Code Playground allows you to operate in [two modalities](./code-playground.md#playground-modes): -- **Script**: directly runs code that operates on the current document. -- **Add-on**: creates an add-on, with a custom User Interface and logic, that is able to run code on the current document. +- [**Script Mode**](https://www.adobe.com/go/addon-playground?executionMode=script): Directly runs code that operates on the current document +- [**Add-on Mode**](https://www.adobe.com/go/addon-playground): Creates an add-on with a custom User Interface and logic that can run code on the current document Make sure you've selected the **Script** tab, which is pre-filled with a sample script: @@ -94,7 +106,7 @@ Make sure you've selected the **Script** tab, which is pre-filled with a sample Click the **Run Code** button on the Playground's toolbar to see the rectangle added to the document. Not much, but it's a start! -### 3. Edit the script +### 3. Edit the Script Feel free to tweak the script to change the properties in the `color` object, or the `translation` and Rectangle dimensions; click **Run Code** again to see what happens. @@ -117,9 +129,9 @@ console.log("Text: ", textNode.fullContent.text); You've been using the Document Sandbox APIs, a very extensive set of APIs that let you create all sorts of objects and manipulate the Adobe Express documents. They are documented in the [SDK References](../../references/document-sandbox/index.md) and explained in detail in the [Platform Concepts](../learn/platform_concepts/document-api.md) section. -### 4. Create an add-on +### 4. Create an Add-on -Click the **Add-on** tab to switch to the [Add-on mode](./code_playground.md#add-on-mode). You'll see that the Playground now shows four tabs: +Click the **Add-on** tab to switch to the [Add-on mode](./code-playground.md#playground-modes). You'll see that the Playground now shows four tabs: - `HTML`: controls the add-on's User Interface. - `CSS`: adds styles. @@ -138,9 +150,9 @@ Even if the result of both the Script and Add-on modes in the Code Playground is ## Command Line Interface (CLI) -The [Adobe Express add-on CLI](./local_development/dev_tooling.md#using-the-cli) allows you to create and host Adobe Express add-ons directly from your local machine. Make sure you have [enabled Add-on Development](#prerequisites) first. +The [Adobe Express add-on CLI](./local_development/dev_tooling.md#using-the-cli) allows you to create and host Adobe Express add-ons directly from your local machine. -### 1. Scaffold a new project +### 1. Scaffold a New Project Open your Terminal and run the following command: @@ -152,7 +164,7 @@ This command will scaffold a new add-on based on "pure" JavaScript with Document - `npx` is a package runner that can execute packages without installing them explicitly. - `@adobe/create-ccweb-add-on` is the CLI maintained by Adobe to scaffold a new add-on. -- `hello-world` is the name of the add-on projectyou are creating. +- `hello-world` is the name of the add-on project you are creating. - The `--template` flag specifies the template to use for the add-on; in this case, `javascript-with-document-sandbox`. The parameter is optional, and when missing, the CLI will prompt you to choose one from a list. The [Templates section](./local_development/dev_tooling.md#templates) on the **Development Tools** page provides a list of available options. @@ -180,7 +192,7 @@ The above may prove useful when updated versions of the CLI are released. If you npx @adobe/ccweb-add-on-scripts start --help ``` -### 2. Build & start your add-on +### 2. Build & Start Your Add-on Next, execute the following commands to change into the newly created **hello-world** add-on folder, `build` the add-on, and `start` the add-on in a local server: @@ -196,11 +208,19 @@ The `start` script will display messages like the following after it executes: Done. Your add-on 'hello-world' is hosted on: https://localhost:5241/ ``` +Look for the **Development Mode activation URL** in the terminal output—click it to quickly enable development features without manually navigating to Settings, or read along. + The add-on's code is now running on a local server; you must tell Adobe Express to load it. -### 3. Load & run your add-on +### 3. Load & Run Your Add-on -To _sideload_ your add-on into Adobe Express, see the following animation or expand the details below for a step-by-step guide. +To _sideload_ your add-on into Adobe Express, follow [this link](https://www.adobe.com/go/addon-cli) or click the button below. + + + +- [Sideload your add-on](https://www.adobe.com/go/addon-cli) + +You can also do it manually by following the steps below. ![How to sideload an add-on](./img/playground-sideload-add-on.gif) @@ -214,15 +234,9 @@ To _sideload_ your add-on into Adobe Express, see the following animation or exp
  • Click the Connect button.
  • Click the Hello World add-on icon on the Add-ons tab on the left.
    • - - - It's possible to achieve the same result when a document is already open clicking the **Add-ons** icon on the left hand rail, then browse to Your add-ons and switch on **Add-on testing**. -
    - Click to see the screenshot - ![Add-on testing](./img/playground-alt-testing.png)
    @@ -231,7 +245,7 @@ If you click the **Create Rectangle** button, you'll see the rectangle being add ![Create Rectangle](./img/playground-run-addon.png) -### 4. Edit your add-on's code +### 4. Edit Your Add-on's Code While your add-on is still loaded and running, open the `src/index.html` file and update the **"Create Rectangle"** string in the `