diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/consistency-checks.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/consistency-checks.md index d216d63c0e6..847b3b151da 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/consistency-checks.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/consistency-checks.md @@ -102,7 +102,7 @@ export const component: IComponent = { } ``` -Every `errorCode` returned by your check function must be listed in `reservedErrorCodes`. You cannot use the Mendix reserved prefixes `cw`, `ce`, or `ci`during registration or the check will fail and a generic error message will appear in the **Errors** pane. +Every `errorCode` returned by your check function must be listed in `reservedErrorCodes`. You cannot use the Mendix reserved prefixes `cw`, `ce`, or `ci` during registration, or the check will fail and a generic error message will appear in the **Errors** pane. In addition, error codes reserved by another extension cannot be reused, or the API will fail. {{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/consistencyChecks/generic_error.png" alt="" >}} diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/custom-blob-document-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/custom-blob-document-api.md index d28a3f5e511..43449a33b94 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/custom-blob-document-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/custom-blob-document-api.md @@ -17,7 +17,7 @@ Before starting this how-to, make sure you have completed the following prerequi ## Custom Document Model -Studio Pro allows you to extend its metamodel by adding custom document types. These documents can store arbitrary data that can be serialized as strings. When you register an editor (a user-defined UI component) for a specific document type, documents of that type appear in the UI alongside built-in document types such as constants, Java actions, and pages. They appear in the **New Document** and **Find Advanced** dialogs, context menus for adding documents, the App Explorer, and other UI elements that display Studio Pro documents. You can register custom editors to appear as tabs or as modal dialogs. +Studio Pro allows you to extend its metamodel by adding custom document types. These documents can store arbitrary data that can be serialized as strings. When you register an editor (a user-defined UI component) for a specific document type, documents of that type appear in the UI alongside built-in document types such as constants, Java actions, and pages. They appear in the **New Document** and **Find Advanced** dialogs, context menus for adding documents, the App Explorer, and other UI elements that display Studio Pro documents. You can register custom editors to appear as tabs or as modal dialogs. You can also add [Consistency Checks](/apidocs-mxsdk/apidocs/web-extensibility-api-11/consistency-checks/) and [Java Action Activities](/apidocs-mxsdk/apidocs/web-extensibility-api-11/java-action-activities-blob-documents/) for custom blob documents. ## Registering a New Document Type @@ -28,7 +28,7 @@ To register a new document type, do the following: ```typescript {hl_lines=["8-24"]} import { IComponent, getStudioProApi } from "@mendix/extensions-api"; - import { personDarkThemeIcon, personDocumentType, personLightThemeIcon } from "../model/constants"; + import { personDarkThemeIcon, personDocumentType, personLightThemeIcon, personReadableDocumentType } from "../model/constants"; import { PersonInfo } from "../model/PersonInfo"; export const component: IComponent = { @@ -36,7 +36,7 @@ To register a new document type, do the following: const studioPro = getStudioProApi(componentContext); await studioPro.app.model.customBlobDocuments.registerDocumentType({ type: personDocumentType, - readableTypeName: 'Person', + readableTypeName: personReadableDocumentType, defaultContent: { firstName: '', lastName: '', @@ -60,6 +60,7 @@ To register a new document type, do the following: ```typescript export const personDocumentType = 'myextension.Person'; + export const personReadableDocumentType = 'Person'; export const personLightThemeIcon = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAERlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAGKADAAQAAAABAAAAGAAAAADiNXWtAAABKElEQVRIDd2Vyw3CMBBEAxIUAWVQBxIcKIBiuNAAFVAIV2iAA2cKoAGYF9nIctaxscIBRhrZ2Z3d9T9N8++YaoIb8ShexYcjfWz40FRhraib+MwQDdpijKXci7nEsZ8YYrOoSe6LEdsLpurFtW1yudiskjXPFSaHufGciFxwqZ9cLcJNWXnjAK2Zi7NdOsKcjlwdcIlygaV+crUIl8jbwnauj5F4CY2ujw0fmiTCAndDtXC2g+HzNq8JJVau9m2Jl+CkKAYxEbfi2ZE+Nnxo4jjeqQ5Sx3QnZThTH4gNX5yc7/cx9WLavovGKJfizJG+NXKSJy+afO2raI3oE1vyqaAA+OpjRwHWtqYIMdZekdMEUy15/NBkl8WsICMbz4ng2A3+y1TOH8ALNqHxhf/P+xwAAAAASUVORK5CYII='; export const personDarkThemeIcon = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABHNCSVQICAgIfAhkiAAAAWdJREFUSIm1ljFuwkAQRd/giFTkABS5gMsolBRcIFBwCOTGNUfgDtDRJ9yDioaCKlJ8B0dYmyLjZGLtrh0Jj7SyNPP3f894dtbinHP0aIM+yQHuYkERuQdegDnwBIw1VABH4BV4c86VQRIXMGABXADXsi7AIsjjIR4AG0NwAnIgBUa6UvWdDG4DDLoI1OQlkAFJJMtEMWUtEhXQstTksxCxR2hmRP6UCwMamppnXcnN/sx8k6FPYGlqHixLRCAx32RZ++05mOtz65y7Btsu3I1XYNvgwmZwJty1XbNINYOzL4MxgIg8/Pftjb1bLmgZFSJSiAgiMvHEJhorYhxWoAY+Gt9RnyvP3lUDY/f+ipr67fmuX258U6ACPoEd8Kxrp74KmBp8rhz7H58JetsUWCtRcwZVwLqtTTsdNM3kAHzoOtg3V0z8oCmov1FhwP0NO93U77g2Qje5cETJvHaLKzMqcAvr/a/iC+JcVEP5CMhEAAAAAElFTkSuQmCC'; ``` @@ -267,6 +268,82 @@ In the next highlighted block, document contents are fetched whenever a new docu The code then provides a way to save changes. +### Creating a Document from Code {#creating-a-document-from-code} + +The `createDocument` method creates a new document and requires a container ID (a module or a folder), a type, content, and a document name. Documents can only be created when the project is initialized: when an extension first loads as its containing project opens, the project database is not yet built. It becomes available after the extension updates and reloads. Check that the project is available before creating or updating documents. + +Add the following code in the `async loaded` of `src/main/index.ts` and import `ProjectMetadata` from `"@mendix/extensions-api"` to try it out: + +```typescript {hl_lines=["5-17"]} +await studioPro.ui.extensionsMenu.add({ + caption: "My Extension", + menuId: "main", + action: async() => { + const project: ProjectMetadata | null = await studioPro.app.projectManager.getProjectMetadata(); + const myModuleContainer = await studioPro.app.model.modules.getModule("MyFirstModule"); + if (project !== null && myModuleContainer !== null){ + await studioPro.app.model.customBlobDocuments.createDocument({ + containerId: myModuleContainer.$ID, + type: personDocumentType, + content: { + firstName: 'John', + lastName: 'Doe', + age: 30, + email: 'john.doe@info.com' + }, + documentName: "person_document" + }); + } + } +}); +``` + +### Updating a Document from Code + +It is also possible to update an existing document from the api, using the `updateDocumentContent` method. It is also necessary for the project to be initialized, or the document will not be found. + +```typescript +const project: ProjectMetadata | null = await studioPro.app.projectManager.getProjectMetadata(); + +if (project !== null){ + await studioPro.app.model.customBlobDocuments.updateDocumentContent(documentId, newContent); +} +``` +To test the feature, add the following code inside the `async loaded` method in `src/main/index.ts`. +```typescript {hl_lines=["25-29"]} +await studioPro.ui.extensionsMenu.add({ + caption: "My Update", + menuId: "updatemenu", + action: async () => { + const documents = + await studioPro.app.model.customBlobDocuments.getDocumentsOfType( + personDocumentType + ); + + const personDocument = documents.find( + document => document.name === "person_document" + ); + + if (!personDocument) { + return; + } + + const newContent: PersonInfo = { + firstName: "Jane", + lastName: "Doe", + age: 31, + email: "jane.doe@info.com" + }; + + await studioPro.app.model.customBlobDocuments + .updateDocumentContent( + personDocument.id, + newContent + ); + } +}); +``` + ### Update Build and Manifest Files The highlighted text in `build-extension.mjs` and `manifest.json` shows the changes necessary to ensure the `editor` entry point builds and loads properly. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/java-action-activities-blob-documents.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/java-action-activities-blob-documents.md new file mode 100644 index 00000000000..f9b7979e252 --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/java-action-activities-blob-documents.md @@ -0,0 +1,301 @@ +--- +title: "Java Action Activities for Custom Blob Documents" +linktitle: "Java Action Activities" +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/java-action-activities/ +description: "Describes how to allow a Custom Blob Document to have its own Java Action activity in a microflow" +--- + +## Introduction + +Java Actions can have Custom Blob Documents as a parameter. You can link the Java Action directly to a document type when the type is registered. This allows the user to drag a Custom Blob Document from the **App Explorer** directly into a microflow, and a new Java Action Activity is automatically generated with that exact Blob Document as the parameter value for the Java Action. + +## Prerequisites + +* This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). Complete that how-to before starting this one. +* Familiarize yourself with creating custom documents as described in [Custom Blob Documents](/apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/). Also useful to know about [consistency checks for blob documents](/apidocs-mxsdk/apidocs/web-extensibility-api-11/consistency-checks/). + +## Registering a Custom Blob Document with a Java Action + +If the Java Action that contains a Blob Document type as its parameter already exists in your extension, you can use its qualified name during the registration call of your Blob Document type. The registration method triggers when the app opens and extensions are loaded, linking the two. + +```typescript + async loaded(componentContext) { + const studioPro = getStudioProApi(componentContext); + await studioPro.app.model.customBlobDocuments.registerDocumentType({ + type: personDocumentType, + readableTypeName: 'Person', + defaultContent: { + firstName: '', + lastName: '', + age: 0, + email: '' + }, + javaActionQualifiedName: 'MyModule.MyJavaAction' + }); + + ... +} +``` + +If you want to create the Java Action that has your new Blob Document Type as a parameter at the same time as registering the document, you can do so as shown below. However, be aware that the Java Action will be created every time your extension gets loaded. This code below is a simple example to show how to create a Java Action and assign its parameter types to a Blob Document type. + +```typescript + + async loaded(componentContext) { + const studioPro = getStudioProApi(componentContext); + + const moduleName = "MyFirstModule"; + const javaActionName = "MyJavaAction"; + + await createJavaActionWithBlobDocumentParameter(studioPro, moduleName, javaActionName, personDocumentType, "Person"); + + await studioPro.app.model.customBlobDocuments.registerDocumentType({ + type: personDocumentType, + readableTypeName: 'Person', + defaultContent: { + firstName: '', + lastName: '', + age: 0, + email: '' + }, + javaActionQualifiedName: `${moduleName}.${javaActionName}` + }); + + ... +} + +async function createJavaActionWithBlobDocumentParameter(studioPro: StudioProApi, moduleName: string, javaActionName: string, customDocumentTypeName: string, customDocumentReadableTypeName: string) { + const module = await studioPro.app.model.modules.getModule(moduleName); + + if (!module) { + throw new Error(`Module was not found.`); + } + + const javaActions = studioPro.app.model.javaActions; + + const javaAction = await javaActions.createUnit(module.$ID, { + name: javaActionName + }); + + const parameterType = await javaActions.createElement( + "CodeActions$CustomBlobDocumentParameterType" + ); + + parameterType.customDocumentTypeName = customDocumentTypeName; + parameterType.customDocumentReadableTypeName = customDocumentReadableTypeName; + + const parameter = await javaActions.createElement("JavaActions$JavaActionParameter", { + name: "document" + }); + + parameter.actionParameterType = parameterType; + + javaAction.actionParameters.push(parameter); + + await javaActions.save(javaAction); + + return javaAction; +} + +``` + +## Consistency Checks for Lost Action and Parameter Types + +### Define a Sample Type That Keeps Track of the Java Action Name + +Add this type next to your other document content types, for example in `src/model/PersonInfo.ts`. It represents the contents of the document that tracks the Java Action linked to it: + +```typescript +export type JavaActionDocument = { + javaActionQualifiedName: string | undefined; + renamedJavaActionQualifiedName?: string | undefined; + someValue?: string | undefined; +}; +``` + +### Write the Consistency Check + +Add the following to your extension's entry point, for example `src/main/index.ts`. It defines the error codes and the `getConsistencyCheck` function that validates a `JavaActionDocument`: + +```typescript +const withJavaActionDocumentType = "myextension.JavaActionDocument"; + +const wrongActionParameterErrorCode = "WRNJAP"; +const noJavaActionErrorCode = "NOJAA"; +const wrongNamedJavaActionErrorCode = "WRNJAA"; +const reservedErrorCodes = [wrongActionParameterErrorCode, noJavaActionErrorCode, wrongNamedJavaActionErrorCode]; + +async function getConsistencyCheck(studioPro: StudioProApi) { + return async (data: JavaActionDocument) => { + const errors: ConsistencyError[] = []; + + if (!data.javaActionQualifiedName || data.javaActionQualifiedName.trim().length === 0) { + errors.push({ + errorCode: noJavaActionErrorCode, + errorDescription: `The Document of type ${withJavaActionDocumentType} must have a java action associated with it.`, + severity: "error", + elementText: "Parameter" + }); + } + + const [action] = await studioPro.app.model.javaActions.loadAll(unit => { + const name = `${unit.moduleName}.${unit.name}`; + return name === data.javaActionQualifiedName || name === data.renamedJavaActionQualifiedName; + }); + + const dependentElementIds: string[] = []; + + if (!action) { + errors.push({ + errorCode: noJavaActionErrorCode, + errorDescription: `The Document of type ${withJavaActionDocumentType} must have a java action associated with it.`, + severity: "error", + elementText: "Parameter" + }); + + return { + errors, + dependentElementIds + }; + } else dependentElementIds.push(action.$ID); // track the JavaAction as a dependency of this document. + + if (data.renamedJavaActionQualifiedName && data.renamedJavaActionQualifiedName !== data.javaActionQualifiedName) { + errors.push({ + errorCode: wrongNamedJavaActionErrorCode, + errorDescription: `The Java action was renamed from ${data.javaActionQualifiedName} to ${data.renamedJavaActionQualifiedName}.`, + severity: "error", + elementText: "Name" + }); + + return { + errors, + dependentElementIds + }; + } + + const blobDocumentParameters = action.actionParameters.filter( + parameter => parameter.actionParameterType.$Type === "CodeActions$CustomBlobDocumentParameterType" + ); + + const correctTypeParameter = blobDocumentParameters.filter( + parameter => + parameter.actionParameterType.$Type === "CodeActions$CustomBlobDocumentParameterType" && + parameter.actionParameterType.customDocumentTypeName === withJavaActionDocumentType + ); + + const wrongTypeParameter = blobDocumentParameters.filter( + parameter => + parameter.actionParameterType.$Type === "CodeActions$CustomBlobDocumentParameterType" && + parameter.actionParameterType.customDocumentTypeName !== withJavaActionDocumentType + ); + + if (correctTypeParameter.length !== 1 || wrongTypeParameter.length > 0) { + errors.push({ + errorCode: wrongActionParameterErrorCode, + errorDescription: `The Java Action "${data.javaActionQualifiedName}" must have a single parameter of type ${withJavaActionDocumentType}.`, + severity: "error", + elementText: "Parameter" + }); + } + + return { + errors, + dependentElementIds + }; + }; +} +``` + +### Register the Document Type with Its Consistency Check + +Add the following code inside the `loaded` function in `src/main/index.ts`, after registering the `Person` document type. Do this by building a `ConsistencyCheckRegistration` and passing it to `registerDocumentType`, the same way you registered the `Person` document type earlier: + +```typescript +const consistencyCheckRegistration: ConsistencyCheckRegistration = { + check: await getConsistencyCheck(studioPro), + reservedErrorCodes +}; + +await studioPro.app.model.customBlobDocuments.registerDocumentType({ + type: withJavaActionDocumentType, + readableTypeName: "Java Action Document", + defaultContent: { + javaActionQualifiedName: undefined + }, + consistencyCheckRegistration +}); +``` + +## Tracking Java Action Renamed or Re-Added with Same Name After Deletion + +Using events from `studioPro.app.projectChanges`, you can track when a Java Action is renamed or re-added with the same name: + + ```typescript + studioPro.app.projectChanges.addEventListener("elementsRenamed", async ({ elements }) => { + const javaActionsRenamed = elements.filter(element => element.documentType === "JavaActions$JavaAction"); + + const javaActionBlobDocuments = await studioPro.app.model.customBlobDocuments.getDocumentsOfType(withJavaActionDocumentType); + for (const doc of javaActionBlobDocuments) { + const d = await studioPro.app.model.customBlobDocuments.getDocumentById(doc.id); + + if ("document" in d && d.document) { + for (const javaActionRenamed of javaActionsRenamed) { + // renamed JavaAction's old name matches our JavaAction, so we track the new name. + if (javaActionRenamed.oldName.qualifiedName === d.document.contents.javaActionQualifiedName) { + d.document.contents.renamedJavaActionQualifiedName = javaActionRenamed.newName.qualifiedName; + + // always save the document so that the consistency checks run again + await studioPro.app.model.customBlobDocuments.updateDocumentContent(d.document.$ID, d.document.contents); + } + + // renamed JavaAction new name matches our name, we can stop tracking the rename + if (javaActionRenamed.newName.qualifiedName === d.document.contents.javaActionQualifiedName) { + d.document.contents.renamedJavaActionQualifiedName = undefined; + + // always save the document so that the consistency checks run again + await studioPro.app.model.customBlobDocuments.updateDocumentContent(d.document.$ID, d.document.contents); + } + } + } + } +}); + +studioPro.app.projectChanges.addEventListener("documentAdded", async ({ document }) => { + const javaActionDocuments = await studioPro.app.model.customBlobDocuments.getDocumentsOfType(withJavaActionDocumentType); + + for (const doc of javaActionDocuments) { + const d = await studioPro.app.model.customBlobDocuments.getDocumentById(doc.id); + + if ("document" in d && d.document) { + const javaAction = (await studioPro.app.model.javaActions.loadAll(ja => ja.$ID === document.documentId)).find( + ja => ja.$ID === document.documentId + ); + + if (javaAction) { + const qualifiedName = (javaAction as JavaActions.JavaAction & { $QualifiedName: string }).$QualifiedName; + + // new JavaAction is in fact our own + if (d.document.contents.javaActionQualifiedName === qualifiedName) { + d.document.contents.javaActionQualifiedName = qualifiedName; + d.document.contents.renamedJavaActionQualifiedName = undefined; + + // trigger the change to run consistency checks again, since this new + // action is probably missing the required parameters of the correct type. + await studioPro.app.model.customBlobDocuments.updateDocumentContent(d.document.$ID, d.document.contents); + } + } + } + } +}); + ``` + +{{% alert color="info" %}} +Studio Pro does not track the deletion or renaming of Java Actions that are linked to Custom Blob Documents. These consistency checks can help you handle those cases. These code samples are simple examples to use as a basis for your own production code. +{{% /alert %}} + + +## Limitations + +A Custom Blob Document and Java Action relationship is one-to-one. There can only be one Java Action per document type. If an extension tries to link a Java Action that is already linked to another type, the API will throw an error. + +It is recommended to write some [consistency checks](/apidocs-mxsdk/apidocs/web-extensibility-api-11/consistency-checks/) to detect when the Java Action is renamed or deleted, or when its parameter types change. Add the `javaActionQualifiedName` property to the Custom Blob Document contents so it is included in the document data when the consistency checks run. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/projects.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/projects.md new file mode 100644 index 00000000000..a03dda48062 --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/projects.md @@ -0,0 +1,110 @@ +--- +title: "Project Related APIs" +linktitle: "Project related APIs" +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/projects/ +--- + +## Introduction + +This how-to describes the APIs that allow users to get information about the current project or document events. + +## Prerequisites + +{{% alert="info" %}} +If you are using Studio Pro 11.0–11.5 and your extension includes menus, your existing menu code will not work when you upgrade to Studio Pro 11.6. To restore full functionality and support, upgrade to the Extensibility API 11.6 and follow the steps in the [Migration Guide](/apidocs-mxsdk/apidocs/web-extensibility-api-11/migration-guide/). +{{% /alert%}} + +This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). Complete that how-to before starting this one. + +## Element Changes API + +This API provides events that relate to elements (documents or entities). + +* `documentsChanged` +* `documentAdded` +* `elementsRenamed` + +| Event | Description | Payload | +|-----------------------|---------------------------------------------|------------------------------| +| `documentsChanged` | Contains a list of changed documents. | Array of `DocumentInfo` | +| `documentAdded` | A single document that was added. | A single `DocumentInfo` | +| `elementsRenamed` | Contains a list of renamed elements. | Array of `ElementRenameInfo` | + +### `DocumentInfo` Properties + +| Property | Type | Description | +|----------------|--------|--------------------------------------------------------------------------------------| +| `documentId` | string | The ID of the document. | +| `documentType` | string | The type of the document (for example, `Microflows$Microflow` or `myExtension.MyBlobDocument`). | +| `documentName` | string | The name of the document. | +| `moduleName` | string | Optional name of the containing module. | + +### `ElementRenameInfo` Properties + +| Property | Type | Description | +|----------------|-------------|------------------------------------------------------| +| `oldName` | ElementName | The old name of the document. | +| `newName` | ElementName | The new name of the document. | +| `documentType` | string | The type of the document (for example, `Microflows$Microflow`). | + +### `ElementName` Properties + +| Property | Type | Description | +|------------------|--------|---------------------------------------------| +| `qualifiedName` | string | The qualified name of the document. | +| `name` | string | The name of the document. | + +These events are useful when working with [Consistency Checks](/apidocs-mxsdk/apidocs/web-extensibility-api-11/consistency-checks/) for Custom Blob Documents. + +### How to Listen to an Event + +```typescript +studioPro.app.projectChanges.addEventListener("documentsChanged", async ({ documents }) => { + ... +} +studioPro.app.projectChanges.addEventListener("documentAdded", async ({ document }) => { + ... +} +studioPro.app.projectChanges.addEventListener("elementsRenamed", async ({ elements }) => { + ... +} +``` + +## Project Manager API + +This API provides events and methods that relate to the current Studio Pro project. + +* `projectOpened` +* `projectClosing` +* `getProjectMetadata` + +| Event | Description | Payload | +|-----------------------|------------------------------------------------------------|-------------------| +| `projectOpened` | Triggers when the project is initialized. | `ProjectMetadata` | +| `projectClosing` | Triggers when the project is closing, unloading extensions. | `ProjectMetadata` | + +### `ProjectMetadata` Properties + +| Property | Type | Description | +|----------------|--------|----------------------------------| +| `projectId` | string | The ID of the project. | +| `projectFile` | string | The file path of the project. | +| `projectName` | string | The name of the project. | +| `caption` | string | The description of the project. | + +These events are useful when working with [Consistency Checks](/apidocs-mxsdk/apidocs/web-extensibility-api-11/consistency-checks/) for Custom Blob Documents. + +### How to Listen to an Event + +```typescript +studioPro.app.projectManager.addEventListener("projectOpened", async ({ project }) => { + ... +} +studioPro.app.projectManager.addEventListener("projectClosing", async ({ project }) => { + ... +} +``` + +### Getting the Current Project + +This API provides a `getProjectMetadata` method that you can use whenever an extension needs to perform an action requiring an initialized project, such as [creating a blob document](/apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/{#creating-a-document-from-code}). It returns a `ProjectMetadata` object that can also be `null`. \ No newline at end of file diff --git a/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md b/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md index 0bd6fc6a57c..d59cbe285ef 100644 --- a/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md +++ b/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md @@ -8,116 +8,192 @@ numberless_headings: true These release notes cover changes to the [Extensibility API for Web Developers](/apidocs-mxsdk/apidocs/extensibility-api/). +## Version 11.15.0 + +### New Features + +* We added a feature flag API under `studioPro.featureFlags.isCommandLineFlagProvided("flag-name")` so developers can check if a specified feature flag exists in the command-line arguments when running Studio Pro from the terminal. +* We added a Register Tool API under `studioPro.ai.tools.registerTool(toolDefinition)` that lets users extend Maia's capabilities by running custom logic. +* We added `javaActionQualifiedName` to the `CustomBlobDocumentRegistrationOptions`, which allows the Studio Pro user to link a blob document type to an existing Java Action, allowing the user to drag a `CustomBlobDocument` straight into a microflow from the **App Explorer**, creating a new `JavaActionActivity` for the `CustomBlobDocument` type. +* We added a `projectClosing` event in the `studioPro.app.projectManager` API to allow the developer to perform any cleanup functions that were dependent on the current project. Both events contain the current open project as their payload. + +### Improvements + +* We added readable names and descriptions for each permission that an extension requires in the Extensions Overview. +* We now ensure that two different extensions cannot use the same prefixes for their consistency error codes. + +### Fixes + +* We fixed an issue where creating or searching for `CustomBlobDocuments` gave unexpected results when called before the project was initialized. To address this, we added `projectOpened` and `projectClosing` events to the `studioPro.app.projectManager` API and the `getProjectMetadata` method, so developers can determine when the project is available before calling the `CustomBlobDocument` API. +* We fixed the issue that `CustomBlobDocumentApi` returned null when calling `getDocumentsOfType` when the project was not yet initialized. It now throws an error instead of returning null. Using `studioPro.app.projectManager.getProjectMetadata` will allow a developer to know when it is safe to call it. +* We fixed a bug where `CustomBlobDocument` type names were not displayed as their registered type in the `Commit` pane in version controlled apps. + ## Version 11.14.0 +### Improvements + * A module ID can now be passed to the element selector for the `selectedElementId` property, and the corresponding module will be preselected and expanded. This will allow the user to directly create a new document of the desired type in that module. * We improved the Extensions Overview UI to be more modern and consistent with the rest of Studio Pro. * We added support for direct assignment to model element array properties (for example, `element.property = [value1, value2]`). ## Version 11.13.0 +### Improvements + * We updated the progress dialog cancellation behavior: the process now waits for the cancelled step to finish before resolving, rather than immediately returning a snapshot of the progress at the time of cancellation. A new `resolveImmediatelyOnCancel` parameter restores the previous behavior. + +### Fixes + * We fixed an issue where reloading an extension with open tabs caused an Oops crash. ## Version 11.12.3 +### Improvements + * We added support for preselecting modules in the [Document Selector API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/element-selector-api/). * We improved the [Permissions API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions/). ## Version 11.12.2 -* We fixed a bug where the Extensions Overview page would not open if the user was not signed in. -* We fixed a bug where reloading a Dev extension would cause a crash if extension tabs were still open. +### Fixes + +* We fixed a bug where the Extensions Overview page did not open if the user was not signed in. +* We fixed a bug where reloading a Dev extension crashed if extension tabs were still open. * We fixed an issue where progress dialogs did not behave like their C# counterpart. Canceling a step now waits for it to finish and return its result. To exit the step and return its result immediately on cancel, pass `resolveImmediatelyOnCancel` to `IDialogApi.showProgressDialog`. ## Version 11.12.1 +### Improvements + * We removed timeouts for Custom Blob Document consistency checks instead of showing a generic error in the **Errors** pane. We also added analytics to identify extensions that exceed the previous timeout. + +### Fixes + * We fixed a bug where the icon next to a tab title did not appear. * We fixed a bug where the Module Settings form incorrectly showed modules other than Add-on when packaging an extension into a module. ## Version 11.12.0 -* We removed the elements helper methods (`add*()`, `get*()`, `getContainer()`, and `delete()`) from the Model API types. +### New Features + * We added a `permissionsChanged` event to the [Permissions API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions/) that notifies you when the user changes the permissions of your extension. * We added the `documentsChanged` event, which notifies you when a document that your extension depends on is modified in Studio Pro. + +### Improvements + * The Studio Pro version is now available through the [Preferences API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/preference-api/). +### Deprecations + +* We removed the elements helper methods (`add*()`, `get*()`, `getContainer()`, and `delete()`) from the Model API types. + ## Version 11.11.0 +### New Features + * We added a **New** button to the [Element Selector API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/element-selector-api/), which allows users to add new documents and entities from the element selector. -* We added a fast reload capability for [Custom Blob documents](/apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/). When a **Custom Blob** document is saved or updated you can see your changes in your locally running app immediately, without having to stop and restart the app. + +### Improvements + * We allow [Custom Blob documents](/apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/) to have a basic properties form with the title and documentation of the **Custom Blob** document. +* We added a fast reload capability for [Custom Blob documents](/apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/). When a **Custom Blob** document is saved or updated you can see your changes in your locally running app immediately, without having to stop and restart the app. ## Version 11.10.0 +### New Features + * We added a **Show** button to the [Element Selector API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/element-selector-api/), which allows users to navigate to the selected element in the editor. + +### Improvements + * We added visual highlighting to the Element Selector API. You can now pass a `selectedElementId` to highlight a previously-selected element in the selector dialog, making it easier for users to identify their last selection when reopening it. * We introduced a change for the Model API that makes it easier to create Import Mappings and Export Mappings based on JSON structure documents. You can now use `addJsonStructure` to create a JSON structure from JSON content, and `getElements` to see the elements inside a JSON structure document. To build mappings, the API now includes `addImportMapping` and `addExportMapping`, which create mapping documents based on a JSON structure. You can then refine or adjust those mappings using `setElementMapping` and `clearElementMapping`. ## Version 11.9.0 +### New Features + * We introduced a new Runtime Configuration API under `studioPro.runtime.configuration`, which allows you to retrieve runtime constants from the active configuration. For more information, see [Access Runtime Constants Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-configuration-api/). * We introduced a new Runtime Controller API under `studioPro.runtime.controller`, which allows you to listen for runtime connection state changes to detect when your app starts or stops running. For more information, see [Listen for Connection Changes](/apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-controller-api/). * We introduced a permission system for web extensions. Extensions can now request access to sensitive APIs and users can grant or revoke permissions through the Extensions Overview pane. For more information, see [Extension Permissions](/apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions/). ## Version 11.8.0 +### Improvements + * We introduced a change in the [Progress Dialog API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/dialog-api/), so when the progress dialog only has one step, only the progress bar is shown. ## Version 11.7.0 +### Improvements + * We added functionality to select a **Custom Blob** document by using its registered name in our [Element Selector](/apidocs-mxsdk/apidocs/web-extensibility-api-11/element-selector-api/) API. -* We fixed an issue where using the **New** button in the selector dialog shown when using the Element Selector API would throw an error. The button has now been removed. + +### Fixes + +* We fixed an issue where using the **New** button in the selector dialog shown when using the Element Selector API threw an error. The button has now been removed. ## Version 11.6.0 -* We introduced a breaking change in the Web Extensibility API. Menus will no longer support commands and will instead allow users to define their own actions. This change will affect extension developers upgrading from Studio Pro 11.5 to 11.6. Review the [Migration Guide](/apidocs-mxsdk/apidocs/web-extensibility-api-11/migration-guide/) to learn how to safely convert your code for the latest version. +### Improvements + * We have added the possibility for registered Custom Blob documents to be passed as parameters to Java Actions. For more information, see [Register New Document Types With a Corresponding Editor](/apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/). +### Breaking Changes + +* We introduced a breaking change in the Web Extensibility API. Menus will no longer support commands and will instead allow users to define their own actions. This change will affect extension developers upgrading from Studio Pro 11.5 to 11.6. Review the [Migration Guide](/apidocs-mxsdk/apidocs/web-extensibility-api-11/migration-guide/) to learn how to safely convert your code for the latest version. + ## Version 11.5.0 -* You can now see all the extensions of your application by clicking **View** > **Extensions**. +### New Features + * We introduced a new Document Selector API under `studioPro.ui.elementSelectors` that allows the user to choose a document or an entity from the project's structure. For more information, see [Using the Element Selector API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/element-selector-api/). +### Improvements + +* You can now see all the extensions of your application by clicking **View** > **Extensions**. + ## Version 11.4.0 +### New Features + * We introduced a new Progress Dialog API under `studioPro.ui.dialogs.showProgressDialog(, <steps>)`, which opens a modal containing a series of steps that perform actions in sequence. For more information, see the [Showing a Progress Dialog](/apidocs-mxsdk/apidocs/web-extensibility-api-11/dialog-api/#process-dialog) section of *Open a Modal Dialog Using Web API*. * We introduced a new Custom Document Model API under `studioPro.app.model.customBlobDocuments`. This allows extensions to register new document types in Studio Pro, which can store arbitrary data and appear in the App Explorer, New Document dialog, and other UI elements. For more information, see [Register New Document Types With a Corresponding Editor](/apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/). ## Version 11.3.0 +### New Features + * We introduced a new Version Control API under `studioPro.ui.versionControl`, which allows you to display version control information about the current version control system, branch, and last commit in Studio Pro. For more information, see [Show Version Control Information Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/version-control-api/). -* We introduced an option in the [Preferences](/refguide/preferences-dialog/#extension-development) menu to enable extension development without using the --enable-extension-development feature flag. It requires a restart of Studio Pro. -* We introduced a new Message Passing API under `studioPro.ui.messagePassing`, to pass information between different active contexts within an extension. This API supports two communication patterns: request-reply and message broadcasting. For more information, see [Exchange Information Between Active Views Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/message-passing-api/). +* We introduced an option in the [Preferences](/refguide/preferences-dialog/#extension-development) menu to enable extension development without using the `--enable-extension-development` feature flag. This requires a restart of Studio Pro. +* We introduced a new Message Passing API under `studioPro.ui.messagePassing` to pass information between different active contexts within an extension. This API supports two communication patterns: request-reply and message broadcasting. For more information, see [Exchange Information Between Active Views Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/message-passing-api/). ## Version 11.2.0 -* We included a new method for initializing the studio Pro API. (this is a breaking change) For more information, see [Getting Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). +### New Features + * We introduced a new command registration API. +### Breaking Changes + +* We included a new method for initializing the Studio Pro API. For more information, see [Getting Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). + ## Version 11.1.0 +### New Features + * We introduced a new Editors API under `studioPro.ui.editors`, which allows you to get the active document and open the default editor for a document. For more information, see [Editor API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/editor-api/). ## Version 11.0.0 +### New Features + * We introduced a new API for showing modal dialogs from web extensions. It is available under `studioPro.ui.dialogs` in the web extensibility API. For more details and practical examples, see [Open a Modal Dialog](/apidocs-mxsdk/apidocs/web-extensibility-api-11/dialog-api/). * We introduced a new API for accessing user preferences from web extensions, which retrieves the user’s selected theme preference (light or dark) and language settings (for exampl, `en-US`). It is available under `studioPro.ui.preferences` in the web extensibility API. For more details and practical examples, see [Show User's Preferences](/apidocs-mxsdk/apidocs/web-extensibility-api-11/preference-api/). * We introduced a new API for showing notification popups from web extensions. It is available under `studioPro.ui.notifications` in the web extensibility API. For more details and practical examples, see [Show a Pop-up Notification](/apidocs-mxsdk/apidocs/web-extensibility-api-11/notification-api/). -## Version 10.24.0 - -* No user facing changes. However, the extension package version must be the same as your Studio Pro version. - -## Version 10.23.0 - -* No user facing changes. However, the extension package version must be the same as your Studio Pro version. - -## Version 10.22.0 - -* No user facing changes. However, the extension package version must be the same as your Studio Pro version. - ## Version 10.21.0 -* The first [beta](/releasenotes/release-status/) release of the Web Extensibility API. +### New Features + +* We introduced the first [beta](/releasenotes/release-status/) release of the Web Extensibility API.