From bd05dff111657963c2e30a76023a323843d948d6 Mon Sep 17 00:00:00 2001 From: Nimitha Jalal Date: Thu, 18 Sep 2025 17:56:09 +0530 Subject: [PATCH 01/11] WIP --- gatsby-config.js | 22 ++ .../guides/getting_started/code_playground.md | 338 +++--------------- .../code_playground_addon_mode.md | 245 +++++++++++++ .../code_playground_script_mode.md | 134 +++++++ .../code_playground_troubleshooting.md | 236 ++++++++++++ .../code_playground_workflow.md | 189 ++++++++++ 6 files changed, 882 insertions(+), 282 deletions(-) create mode 100644 src/pages/guides/getting_started/code_playground_addon_mode.md create mode 100644 src/pages/guides/getting_started/code_playground_script_mode.md create mode 100644 src/pages/guides/getting_started/code_playground_troubleshooting.md create mode 100644 src/pages/guides/getting_started/code_playground_workflow.md diff --git a/gatsby-config.js b/gatsby-config.js index 6ac34db67..d0b7d6ef4 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -554,6 +554,28 @@ module.exports = { { title: "Code Playground", 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", diff --git a/src/pages/guides/getting_started/code_playground.md b/src/pages/guides/getting_started/code_playground.md index 6c2f8680b..3032b8265 100644 --- a/src/pages/guides/getting_started/code_playground.md +++ b/src/pages/guides/getting_started/code_playground.md @@ -27,83 +27,68 @@ contributors: # Code Playground -The Code Playground is an in-app lightweight code editor for fast and effortless prototyping. +The Code Playground is an in-app lightweight code editor for fast and effortless prototyping of Adobe Express add-ons. -## What is Code Playground? +## Overview -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: +### What is Code Playground? -- **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. +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. -## Features +### 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 +- **Local Persistence**: Save your work to your browser's local storage and resume where you left off +- **Programming Assistance**: Typed definitions and auto-completion -| 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. | +### Who Should Use Code Playground? - +## Getting Started -## Development Workflow Use Cases +### Prerequisites -The Code Playground is designed to support the following development workflow use cases: +Before using Code Playground, ensure you have: -- **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. +- An Adobe Express account +- Add-on Development mode enabled in your Adobe Express settings +- A document open in Adobe Express (for testing your code) -## How to Access Code Playground +### How to Access Code Playground -### Step 1: Enable Add-on Development Mode +#### 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). +1. Click the avatar icon in the top right corner of Adobe Express, then the gear icon to open the "Settings" +2. 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 +#### 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: +1. With any document open, 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: - ![Adobe Express Code Playground Toggle](./img/toggle-playground.png) + ![Adobe Express Code Playground Toggle](./img/toggle-playground.png) -- Once enabled, the playground window will open, allowing you to begin coding immediately: +4. Once enabled, the playground window will open, allowing you to begin coding immediately: - ![Adobe Express Code Playground Open](./img/playground-open.png) + ![Adobe Express Code Playground Open](./img/playground-open.png) -## Choose Your Development Mode +## Development Modes -The playground offers two distinct development modes: +The playground offers two distinct development modes to suit different needs: -- [**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. - -
+### Mode Overview | Comparison Factor | Script Mode | Add-on Mode | | --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | @@ -115,247 +100,36 @@ The playground offers two distinct development modes: | **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. +### When to Use Each Mode -The Document JS tab corresponds to the code typically found in the `code.js` file of a complete add-on project. +**Use Script Mode when:** -## Transitioning from Script Mode to Add-on Mode +- Learning how the Document APIs work +- Quickly experimenting with Document API calls without UI considerations +- Testing specific API functionality +- Debugging isolated code snippets -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: +**Use Add-on Mode when:** -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. +- Developing and testing a complete add-on directly in Adobe Express +- Prototyping an add-on before building a full project +- Iterating quickly on your add-on's UI and logic +- Building user interfaces around your functionality -## Workflow Tips +## Quick Start Guides -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. +- **[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 have the downloaded code from the Code Playground, explore our resources to continue building robust add-ons: +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). - -## 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. +- **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) 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..c8a692cc6 --- /dev/null +++ b/src/pages/guides/getting_started/code_playground_addon_mode.md @@ -0,0 +1,245 @@ +--- +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 and test a complete add-on directly in Adobe Express +- Prototype an add-on before building a full project +- Iterate quickly on your add-on's UI and logic +- Build user interfaces around your functionality +- Test the complete add-on experience + +## How to Use Add-on Mode + +### Step 1: Select Add-on Mode + +1. Click the **Add-on** button (next to the **Script** button 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-mode.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 + +This environment corresponds to the code you would typically write in your `index.js` or UI JavaScript files in a full add-on project. + +**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 | +| **Environment** | Document Sandbox only | Both iframe and Document Sandbox | +| **API Access** | Document APIs only | Document APIs + Add-on UI SDK | + +## Best Practices + +### Code Organization + +- Keep UI logic in the **Iframe JS** tab +- Keep document manipulation in the **Document JS** tab +- Use clear, descriptive variable and function names +- Comment your code for better maintainability + +### Communication Between Tabs + +- Use the communication APIs to send data between iframe and Document Sandbox +- Define clear message types and payload structures +- Handle errors gracefully in both contexts + +### Performance + +- Avoid heavy computations in the iframe context +- Use async/await properly for document operations +- Test your add-on with different document sizes and complexity + +## 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..c5042063a --- /dev/null +++ b/src/pages/guides/getting_started/code_playground_script_mode.md @@ -0,0 +1,134 @@ +--- +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 allows you to quickly experiment with Adobe Express Document APIs without the complexity of building a full user interface. + +## What is Script Mode? + +Script Mode is designed for rapid prototyping and learning. It provides a simplified environment where you can: + +- Test Document API calls directly +- Learn how the Document APIs work +- Experiment with document manipulation +- Debug specific functionality + +**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. + +## When to Use Script Mode + +Use Script Mode when you want to: + +- Learn how the Document APIs work +- Quickly experiment with Document API calls without UI considerations +- Test specific API functionality +- Debug isolated code snippets +- Prototype document manipulation logic + +## How to Use Script Mode + +### Step 1: Select Script Mode + +1. Click the **Script** button 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 + +![Code Playground Script Mode](./img/script-mode.png) + +### 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 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 won't harm anything. + +### No UI Building + +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](./code_playground_addon_mode.md). + + + +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 `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..ed6db097d --- /dev/null +++ b/src/pages/guides/getting_started/code_playground_troubleshooting.md @@ -0,0 +1,236 @@ +--- +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. Try running a simple test code first + +### Session Not Saving + +**Problem:** Your work is not being saved between sessions. + +**Solutions:** + +1. Make sure you're not in incognito/private browsing mode +2. Check that your browser allows local storage +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 + +### 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: + +- Chrome (latest version) +- Firefox (latest version) +- Safari (latest version) +- Edge (latest version) + +### 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 +- Check if strict privacy mode is affecting local storage +- 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..0bba70039 --- /dev/null +++ b/src/pages/guides/getting_started/code_playground_workflow.md @@ -0,0 +1,189 @@ +--- +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 "**...**" 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. + +## Session Management + +### 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 + +### Resuming Sessions + +There are two ways to resume working on your last saved session: + +#### Via the Add-ons Panel + +1. With any document open, 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 Add-on Mode](./img/playground-on.png) + +#### Via the Your add-ons Page + +1. 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 +2. Find the **Playground Sessions** section in the **Your add-ons** page +3. 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 + +## Downloading 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 **...** 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 + +### 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) + +### Running 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/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. + +## 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 + +### Code Organization + +- **Use Clear Naming**: Choose descriptive names for variables and functions +- **Comment Your Code**: Add comments to explain complex logic +- **Modular Approach**: Break down complex functionality into smaller functions +- **Error Handling**: Always include proper error handling in your code + +### Testing Strategy + +- **Test with Different Documents**: Try your add-on with various document types and sizes +- **Edge Cases**: Test with empty documents, single elements, and complex layouts +- **Performance**: Monitor how your add-on performs with large documents +- **User Experience**: Test the complete user flow from start to finish + +## Troubleshooting Common Issues + +### Code Not Running + +- Check for syntax errors in your code +- Ensure you're using the correct mode for your use case +- Verify that all required APIs are properly imported +- Check the browser console for error messages + +### Session Not Saving + +- Make sure you're not in incognito/private browsing mode +- Check that your browser allows local storage +- Try saving manually using the keyboard shortcut +- Clear browser cache and try again + +### Performance Issues + +- Avoid heavy computations in the iframe context +- Use async/await properly for document operations +- Test with different document sizes +- Consider breaking down large operations into smaller chunks + +## 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 From 7d6f70f62edc2f1e9d23ea40a0b0bb56ffeea8b9 Mon Sep 17 00:00:00 2001 From: Nimitha Jalal Date: Fri, 7 Nov 2025 08:56:58 +0530 Subject: [PATCH 02/11] review-comments --- .../guides/getting_started/code_playground.md | 28 ++++++++++++------- .../code_playground_workflow.md | 4 +++ .../guides/getting_started/quickstart.md | 6 ++++ 3 files changed, 28 insertions(+), 10 deletions(-) diff --git a/src/pages/guides/getting_started/code_playground.md b/src/pages/guides/getting_started/code_playground.md index 3032b8265..0f4082ef6 100644 --- a/src/pages/guides/getting_started/code_playground.md +++ b/src/pages/guides/getting_started/code_playground.md @@ -60,21 +60,13 @@ The Code Playground is designed for: Before using Code Playground, ensure you have: - An Adobe Express account -- Add-on Development mode enabled in your Adobe Express settings - A document open in Adobe Express (for testing your code) ### How to Access Code Playground -#### Step 1: Enable Add-on Development Mode +#### Step 1: Open Code Playground -1. Click the avatar icon in the top right corner of Adobe Express, then the gear icon to open the "Settings" -2. 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 - -1. With any document open, click the **Add-ons** button in the left rail +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: @@ -84,6 +76,22 @@ Before using Code Playground, ensure you have: ![Adobe Express Code Playground Open](./img/playground-open.png) +#### Step 2: Enable Add-on Development Mode (if needed) + +If this is your first time using Code Playground or any add-on development features, you may need to enable Add-on Development mode: + +1. Click the avatar icon in the top right corner of Adobe Express, then the gear icon to open the "Settings" +2. Click the **Developer Terms of Use** link to review the terms (opens in a new tab) +3. Click **Accept and Enable** to enable **Add-on Development** + +![Enable Add-on Development](./img/playground-enable-dev-mode.gif) + + + +#### Quick Access to Development Mode + +When using the [CLI to build add-ons](./quickstart.md), the terminal output includes a direct URL to activate Development Mode. Look for this URL in the terminal after running `npm run start` to quickly enable development features without manually navigating to Settings. + ## Development Modes The playground offers two distinct development modes to suit different needs: diff --git a/src/pages/guides/getting_started/code_playground_workflow.md b/src/pages/guides/getting_started/code_playground_workflow.md index 0bba70039..884af8fc9 100644 --- a/src/pages/guides/getting_started/code_playground_workflow.md +++ b/src/pages/guides/getting_started/code_playground_workflow.md @@ -92,6 +92,10 @@ There are two ways to resume working on your last saved session: ![Code Playground Add-on Mode](./img/playground-on.png) + + +If you haven't enabled Add-on Development mode yet, you'll be prompted to do so. See the [Getting Started section](./code_playground.md#step-2-enable-add-on-development-mode-if-needed) for details on enabling Development Mode. + #### Via the Your add-ons Page 1. 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 diff --git a/src/pages/guides/getting_started/quickstart.md b/src/pages/guides/getting_started/quickstart.md index 85721cfb0..5a5f36e90 100644 --- a/src/pages/guides/getting_started/quickstart.md +++ b/src/pages/guides/getting_started/quickstart.md @@ -98,6 +98,12 @@ Done. Your add-on 'hello-world' is hosted on: https://localhost:5241/ You can now sideload your add-on by enabling the Developer Mode in the Add-ons panel. ``` + + +#### Quick Setup Tip + +**Look for the Development Mode activation URL in the terminal output above!** The CLI provides a direct link to enable Developer Mode in Adobe Express. Click this URL to skip manually navigating through Settings. If you don't see it or prefer to enable it manually, follow the steps below. + ## Step 3: Enable add-on development mode (first-time only) - Navigate to [Adobe Express](https://express.adobe.com/). From f548694f09afd6108f046cea1e294942f19deaa3 Mon Sep 17 00:00:00 2001 From: Nimitha Jalal Date: Fri, 7 Nov 2025 13:38:27 +0530 Subject: [PATCH 03/11] Refactor dev mode setup and highlight CLI activation URL - Make hello-world.md the canonical reference for enabling dev mode - Add prominent callouts for CLI's dev mode activation URL (addresses feedback) - Update all docs to reference hello-world.md instead of duplicating instructions - Fix broken links, improve heading consistency, fix typos No code samples changed. --- .../guides/getting_started/code_playground.md | 22 ++------ .../code_playground_workflow.md | 2 +- .../guides/getting_started/hello-world.md | 54 ++++++++++--------- 3 files changed, 35 insertions(+), 43 deletions(-) diff --git a/src/pages/guides/getting_started/code_playground.md b/src/pages/guides/getting_started/code_playground.md index 0f4082ef6..794a9cfee 100644 --- a/src/pages/guides/getting_started/code_playground.md +++ b/src/pages/guides/getting_started/code_playground.md @@ -64,7 +64,11 @@ Before using Code Playground, ensure you have: ### How to Access Code Playground -#### Step 1: Open Code Playground +#### Step 1: Enable Add-on Development Mode (if needed) + +If this is your first time using Code Playground or any add-on development features, you'll need to enable Add-on Development mode. See the [Enable Add-on Development Mode](./hello-world.md#enable-add-on-development-mode) section in the Hello, World! guide for detailed instructions. + +#### Step 2: Open Code Playground 1. With any document open in Adobe Express, click the **Add-ons** button in the left rail 2. Select the **Your add-ons** tab @@ -76,22 +80,6 @@ Before using Code Playground, ensure you have: ![Adobe Express Code Playground Open](./img/playground-open.png) -#### Step 2: Enable Add-on Development Mode (if needed) - -If this is your first time using Code Playground or any add-on development features, you may need to enable Add-on Development mode: - -1. Click the avatar icon in the top right corner of Adobe Express, then the gear icon to open the "Settings" -2. Click the **Developer Terms of Use** link to review the terms (opens in a new tab) -3. Click **Accept and Enable** to enable **Add-on Development** - -![Enable Add-on Development](./img/playground-enable-dev-mode.gif) - - - -#### Quick Access to Development Mode - -When using the [CLI to build add-ons](./quickstart.md), the terminal output includes a direct URL to activate Development Mode. Look for this URL in the terminal after running `npm run start` to quickly enable development features without manually navigating to Settings. - ## Development Modes The playground offers two distinct development modes to suit different needs: diff --git a/src/pages/guides/getting_started/code_playground_workflow.md b/src/pages/guides/getting_started/code_playground_workflow.md index 884af8fc9..11e4b2232 100644 --- a/src/pages/guides/getting_started/code_playground_workflow.md +++ b/src/pages/guides/getting_started/code_playground_workflow.md @@ -94,7 +94,7 @@ There are two ways to resume working on your last saved session: -If you haven't enabled Add-on Development mode yet, you'll be prompted to do so. See the [Getting Started section](./code_playground.md#step-2-enable-add-on-development-mode-if-needed) for details on enabling Development Mode. +If you haven't enabled Add-on Development mode yet, you'll be prompted to do so. See [Enable Add-on Development Mode](./hello-world.md#enable-add-on-development-mode) for detailed instructions. #### Via the Your add-ons Page diff --git a/src/pages/guides/getting_started/hello-world.md b/src/pages/guides/getting_started/hello-world.md index b30d911f3..d46af1429 100644 --- a/src/pages/guides/getting_started/hello-world.md +++ b/src/pages/guides/getting_started/hello-world.md @@ -46,26 +46,28 @@ 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: + +1. Open Adobe Express in your browser and click the **avatar icon** in the top right corner +2. Click the gear icon to open **Settings** +3. Click the **Developer Terms of Use** link to review the terms (opens in a new tab) +4. Click **Accept and Enable** to enable **Add-on Development** ![Enable Add-on Development](./img/playground-enable-dev-mode.gif) -
- Click to view a list of steps to enable the Development 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. -
-
+ + +#### Quick Access via CLI + +When using the CLI (see below), look for the **Development Mode activation URL** in your terminal output after running `npm run start`. Click this link to quickly enable development features without manually navigating to Settings. ## 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. @@ -81,12 +83,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#development-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**: Directly runs code that operates on the current document +- **Add-on Mode**: 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 +96,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 +119,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#development-modes). You'll see that the Playground now shows four tabs: - `HTML`: controls the add-on's User Interface. - `CSS`: adds styles. @@ -138,9 +140,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 +154,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 +182,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,9 +198,11 @@ 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. + 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. @@ -231,7 +235,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 `