### Install DrPublish Plugin API via NPM Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/README.md Command to install the necessary package for developing DrPublish plugins. ```bash npm install --save @aptoma/drpublish-plugin-api ``` -------------------------------- ### Start Plugin using ArticleCommunicator.startPlugin Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md This JavaScript method, ArticleCommunicator.startPlugin, is used to initiate or start a specified plugin within the DrPublish environment. It takes the plugin name, optional configuration options, and a callback function that is executed upon successful startup. This method enables dynamic loading and management of plugins. ```javascript PluginAPI.ArticleCommunicator.startPlugin('myPluginName', { setting: 'value' }, function(result) { console.log('Plugin started:', result); }); ``` -------------------------------- ### ArticleCommunicator.startPlugin Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Initializes and starts a plugin with specified options and a callback function. ```APIDOC ## ArticleCommunicator.startPlugin ### Description Initializes and starts a plugin with specified options and a callback function. ### Method Not specified (assumed to be a JavaScript function call) ### Endpoint N/A (Client-side JavaScript API) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **name** (String) - Required - Name of the plugin as defined on publication settings - **options** (Object) - Required - Options for initializing the plugin - **callback** (Function) - Required - function(Boolean), called after plugin is started ### Request Example ```javascript ArticleCommunicator.startPlugin('myPlugin', { setting: true }, function(started) { console.log('Plugin started:', started); }); ``` ### Response #### Success Response (200) - **Void** - This method does not return a value directly, but invokes the callback. #### Response Example N/A ``` -------------------------------- ### Get Modal Input Values Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Illustrates how to retrieve the values of input and select elements within a modal using PluginAPI.getModalInputs. The example shows the expected input HTML and the resulting JSON output. ```javascript Given a modal with the following HTML content:
getModalInputs would return: { "number-0": {VALUE} "name": {VALUE}, "languages": "en" } ``` -------------------------------- ### Get Application Name - JavaScript Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the name of the application hosting the plugin. Returns false if the application name cannot be detected. ```javascript PluginAPI.getAppName() ``` -------------------------------- ### Initialize Context Menu - JavaScript Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/simple/index.html This example demonstrates how to register a delete button for elements that have been inserted by this plugin. It uses `PluginAPI.Editor.initMenu()` to initialize the context menu with the specified button. ```javascript document.addEventListener('DOMContentLoaded', function() { // register a delete button for elements inserted by this plugin PluginAPI.Editor.initMenu(['deleteButton']); }); ``` -------------------------------- ### Define Plugin Configuration with JSON Schema Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/README.md Example of a JSON schema used to define the configuration structure for a plugin, allowing DrPublish to validate and manage app settings. ```json { "search": { "type": "string", "title": "Default Search", "required": true }, "images": { "type": "array", "title": "Image Sizes", "items": { "type": "object", "title": "Image Size", "properties": { "name": { "type": "string", "title": "name", "required": true }, "filter": { "type": "string", "title": "Filter", "enum": [ "grayscale", "sepia", "none" ] }, "height": { "type": "integer", "title": "Height" } } } } } ``` -------------------------------- ### Manage Article Properties Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Allows getting all article properties, setting multiple properties at once using an object, or setting a single property. Callbacks are used for asynchronous operations. ```javascript PluginAPI.Article.getProperties(function(properties) { console.log('Article properties:', properties); properties.forEach(function(prop) { console.log(prop.name + ':', prop.value); }); }); PluginAPI.Article.setProperties({ fooProperty: 'bar', barProperty: 'foo', priority: 'high' }, function(updatedProperties) { console.log('Properties updated:', updatedProperties); }); PluginAPI.Article.setProperty('featured', true, function(properties) { console.log('Property set, all properties:', properties); }); ``` -------------------------------- ### Get Tags Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/hello-world-plugin/index.html Retrieves the tags associated with the current article. ```APIDOC ## Get Tags ### Description Retrieves the tags associated with the current article. The tags are provided to a callback function. ### Method N/A (JavaScript function) ### Endpoint N/A ### Parameters - **callback** (function) - Required - A function that receives an array of tags as an argument. ### Request Example ```javascript PluginAPI.Article.getTags(function (tags) { $('#getTags-result').val(tags.length > 0 ? JSON.stringify(tags) : 'article has no tags'); }); ``` ### Response Provides an array of tags to the callback function. If no tags are found, it indicates so. ``` -------------------------------- ### PluginAPI.Article.getId / getPackageGuid Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Retrieves the unique identifier (ID) or the package GUID for the currently edited article. ```APIDOC ## PluginAPI.Article.getId ### Description Gets the article ID of the currently edited article. ### Method `PluginAPI.Article.getId(callback)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```javascript PluginAPI.Article.getId(function(id) { console.log('Article ID:', id); loadRelatedContent(id); }); ``` ### Response #### Success Response (200) - **id** (string) - The unique identifier for the current article. #### Response Example ```json { "id": "article-12345" } ``` ### Error Handling Errors may occur if the callback function is not provided or if the article ID cannot be retrieved. ``` ```APIDOC ## PluginAPI.Article.getPackageGuid ### Description Gets the package GUID of the currently edited article. ### Method `PluginAPI.Article.getPackageGuid(callback)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```javascript PluginAPI.Article.getPackageGuid(function(guid) { console.log('Package GUID:', guid); }); ``` ### Response #### Success Response (200) - **guid** (string) - The package GUID for the current article. #### Response Example ```json { "guid": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ``` ### Error Handling Errors may occur if the callback function is not provided or if the package GUID cannot be retrieved. ``` -------------------------------- ### Get Plugin Name - JavaScript Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the name of the currently loaded plugin. Returns false if the plugin name cannot be detected. ```javascript PluginAPI.getPluginName() ``` -------------------------------- ### ArticleCommunicator.getPackageGuid Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the package GUID of the currently edited article. ```APIDOC ## ArticleCommunicator.getPackageGuid(callback) ### Description Get the guid of the article package currently edited. ### Method Not specified (assumed to be a JavaScript function call) ### Endpoint N/A (Client-side JavaScript API) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **callback** (Function) - Required - function(Int), id of the current article ### Request Example ```javascript ArticleCommunicator.getPackageGuid(function(packageGuid) { console.log('Current package GUID:', packageGuid); }); ``` ### Response #### Success Response (200) - **Void** - This method does not return a value directly, but invokes the callback. #### Response Example N/A ``` -------------------------------- ### Manage Article Categories Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Provides functionality to get, set, add, and set the main category for an article. It operates on category IDs and uses callbacks to handle results. ```javascript PluginAPI.Article.getSelectedCategories(function(categoryIds) { console.log('Selected category IDs:', categoryIds); }); PluginAPI.Article.setCategories([101, 205, 310], function(success) { console.log('Categories updated:', success); }); PluginAPI.Article.addCategories([401, 502], function(success) { console.log('Categories added:', success); }); PluginAPI.Article.setMainCategory(101, function(success) { console.log('Main category set:', success); }); ``` -------------------------------- ### Access Article Metadata Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Retrieves core identifiers for the article currently being edited, such as the internal ID or package GUID. ```javascript PluginAPI.Article.getId(function(id) { console.log('Article ID:', id); }); PluginAPI.Article.getPackageGuid(function(guid) { console.log('Package GUID:', guid); }); ``` -------------------------------- ### Transfer Focus with PluginAPI.giveFocus Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Transfers focus to another plugin, optionally passing data and arguments. It can also start the target plugin if it's not already running. The receiving plugin can listen for the 'receivedFocus' event to handle the incoming data and context. ```javascript PluginAPI.giveFocus('image-plugin', { action: 'selectImage', context: 'featured-image' }, true); PluginAPI.on('receivedFocus', function(data) { console.log('Previous plugin:', data.previousPluginName); if (data.action === 'selectImage') { openImageSelector(data.context); } }); ``` -------------------------------- ### Insert Element into Editor - JavaScript Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/simple/index.html This example demonstrates how to insert an HTML element into the DrPublish editor at the current cursor position. It creates a `div` element, populates it with content, and uses `PluginAPI.Editor.insertElement()`. The API automatically adds necessary attributes for draggable and non-editable elements. ```javascript document.addEventListener('DOMContentLoaded', function() { document.querySelector('#objectButton').addEventListener('click', function() { var value = getValue(); if (value === null) { return false; } // insert an element at the current cursor position // required parameters to make it draggable and non-editable are automatically added by the PluginAPI var element = document.createElement('div'); element.innerHTML = '

' + value + '

'; PluginAPI.Editor.insertElement(element); }); }); function getValue() { var value = document.querySelector('#textInput').value; if (value.trim() === '') { PluginAPI.showInfoMsg('I shall not insert an empty thing, that would just be silly'); return null; } return value; } ``` -------------------------------- ### Manage Article Published Datetime Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Provides functionality to get the current publication datetime and set a future datetime for scheduling article publication. Callbacks are used for handling the asynchronous results. ```javascript PluginAPI.Article.getPublishedDatetime(function(datetime) { console.log('Published:', datetime); }); PluginAPI.Article.setPublishedDatetime('2024-12-25 08:00:00', function(success) { console.log('Article scheduled for publication'); }); ``` -------------------------------- ### Get Article Tags Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/hello-world-plugin/index.html Retrieves the tags associated with the current article. If tags exist, they are returned as a JSON string; otherwise, a message indicating no tags is displayed. Dependencies: jQuery for DOM manipulation. ```javascript PluginAPI.Article.getTags(function (tags) { $('#getTags-result').val(tags.length > 0 ? JSON.stringify(tags) : 'article has no tags'); }); ``` -------------------------------- ### Initialize Plugin API Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Shows how to export and initialize the PluginAPI by passing it to a module's export function. ```javascript module.exports = function(PluginAPI) { // Plugin API initialization logic here }; ``` -------------------------------- ### GET AH5Communicator.getActiveEditor Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the name of the currently active editor. ```APIDOC ## GET AH5Communicator.getActiveEditor ### Description Get the name of the current active editor. ### Method GET ### Parameters #### Query Parameters - **callback** (function) - Required - function(String) receiving the editor name. ### Response #### Success Response (200) - **editorName** (String) - The name of the active editor. ``` -------------------------------- ### AH5Communicator.initMenu Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Initializes pre-registered menus with specified options. ```APIDOC ## AH5Communicator.initMenu ### Description Initialize pre registered menus. Available options are: simplePluginMenu, editContext, deleteButton, floatButtons. ### Method POST (assumed, as it modifies state) ### Endpoint /aptoma/drpublish-plugin-api/initMenu ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **menus** (Array) - Required - Array of menu names. - **callback** (Function) - Optional - Callback function that receives a boolean indicating success. ### Request Example ```json { "menus": ["simplePluginMenu", "editContext"], "callback": "function(success) { console.log(success); }" } ``` ### Response #### Success Response (200) - **success** (Boolean) - Indicates if the menus were initialized successfully. #### Response Example ```json { "success": true } ``` ``` -------------------------------- ### GET /PluginAPI/getEmbeddedObjectTypes Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves a list of available embedded object types. ```APIDOC ## GET /PluginAPI/getEmbeddedObjectTypes ### Description Get information about the available embedded object types. ### Method GET ### Endpoint PluginAPI.getEmbeddedObjectTypes(callback) ### Parameters #### Query Parameters - **callback** (Function) - Required - function([Object]) receives an array of objects describing types ### Response #### Success Response (200) - **types** (Array) - An array of objects containing {typeId, cssClass} ``` -------------------------------- ### Create Modal with jQuery UI Options Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Demonstrates how to create a modal dialog using PluginAPI.createModal, passing HTML content and jQuery UI options. It also shows how to update and close the modal. ```javascript PluginAPI.createModal('

This is a modal

', { buttons: { Ok: function () { alert('Ok!'); } } }); PluginAPI.updateModal('

This is the same modal

'); PluginAPI.createModal('

This is a brand new modal

', { buttons: { cancel: function() { PluginAPI.closeModal(true); } } }); ``` -------------------------------- ### Get Article ID Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/hello-world-plugin/index.html Retrieves the unique identifier for the current article. ```APIDOC ## Get Article ID ### Description Fetches the ID of the current article. The ID is provided to a callback function. ### Method N/A (JavaScript function) ### Endpoint N/A ### Parameters - **callback** (function) - Required - A function that receives the article ID as an argument. ### Request Example ```javascript PluginAPI.Article.getId(function (id) { $('#getId-result').val(id); }); ``` ### Response Provides the article ID to the callback function. ``` -------------------------------- ### PluginAPI.getConfiguration Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Fetches the current configuration information for the plugin. ```APIDOC ## PluginAPI.getConfiguration(callback) ### Description Get configuration information about the plugin. ### Method Not applicable (JavaScript function call) ### Endpoint Not applicable (JavaScript function call) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Parameters - **callback** (Function) - Required - function(Object) Function to call with the configuration object. ### Request Example ```javascript PluginAPI.getConfiguration(function(config) { console.log('Plugin Configuration:', config); }); ``` ### Response #### Success Response (200) - **Void** - The function does not return a value directly, results are passed via the callback. #### Response Example (Callback function receives the configuration object) ``` -------------------------------- ### ArticleCommunicator.getPackageId Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the package ID (GUID) of the currently edited article. ```APIDOC ## ArticleCommunicator.getPackageId(callback) ### Description Get the guid of the article package currently edited. ### Method Not specified (assumed to be a JavaScript function call) ### Endpoint N/A (Client-side JavaScript API) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **callback** (Function) - Required - function(Int), id of the current article ### Request Example ```javascript ArticleCommunicator.getPackageId(function(packageId) { console.log('Current package ID:', packageId); }); ``` ### Response #### Success Response (200) - **Void** - This method does not return a value directly, but invokes the callback. #### Response Example N/A ``` -------------------------------- ### PluginAPI.showNotifications Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Methods for displaying user feedback messages and loading states. ```APIDOC ## POST PluginAPI.showInfoMsg / showWarningMsg / showErrorMsg ### Description Displays feedback messages to the user within the DrPublish interface. ### Method POST ### Endpoint PluginAPI.showInfoMsg(msg), PluginAPI.showWarningMsg(msg), PluginAPI.showErrorMsg(msg) ### Parameters #### Request Body - **msg** (String) - Required - The message text to display. ``` -------------------------------- ### Get Custom Metadata Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/hello-world-plugin/index.html Retrieves custom metadata (also known as article properties) for the current article. ```APIDOC ## Get Custom Metadata ### Description Retrieves custom metadata (article properties) for the current article. If no specific metadata key is provided, all available custom metadata are fetched. The data is provided to a callback function. ### Method N/A (JavaScript function) ### Endpoint N/A ### Parameters - **key** (string) - Optional - The key of the custom metadata to retrieve. - **callback** (function) - Required - A function that receives the custom metadata as an argument. ### Request Example ```javascript // To get all custom metadata: PluginAPI.Article.getCustomMetadata(function (metadata) { console.log(metadata); }); // To get a specific metadata property: PluginAPI.Article.getCustomMetadata('propertyName', function (value) { console.log(value); }); ``` ### Response Provides the requested custom metadata to the callback function. ``` -------------------------------- ### Initialize Plugin and Fetch Article ID Dynamically Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/hello-world-plugin/index.html Initializes the plugin by setting its name and then fetches the article ID dynamically whenever a new article is loaded in the editor. It logs the ID and displays it in an input field. Dependencies: jQuery for DOM manipulation. ```javascript function initPlugin() { PluginAPI.setPluginName('helloworld'); fetchArticleIdDynamically(); } function fetchArticleIdDynamically() { PluginAPI.Article.getId(function(id) { console.log('stef:fetchedartid', id); $('#fetchArticleId-result').val(id); }); } ``` -------------------------------- ### POST /PluginAPI/createModal Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Creates a jQuery UI modal in the main editor window. ```APIDOC ## POST /PluginAPI/createModal ### Description Creates a jQuery UI modal in the main editor window. Modals are unique per plugin. ### Method POST ### Endpoint PluginAPI.createModal(content, options) ### Parameters #### Request Body - **content** (String) - Required - An HTML string for the modal body - **options** (Object) - Required - A standard jQuery UI options object ### Response #### Success Response (200) - **result** (Boolean) - Returns true if the modal was created successfully. ``` -------------------------------- ### Handle Article and Editor Events with PluginAPI.on Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Listens for various lifecycle and editor events provided by the Plugin API. Plugins can react to these events to perform actions, validate content, or update UI. Events prefixed with 'before' can be cancelled by returning false from their callback. ```javascript PluginAPI.on('beforeCreate', function(data) { /* Before new article */ }); PluginAPI.on('afterCreate', function(data) { /* After new article created */ }); PluginAPI.on('beforeLoad', function(data) { /* Before article loads */ }); PluginAPI.on('afterLoad', function(data) { /* After article loaded */ }); PluginAPI.on('beforeSave', function(data) { return validateArticle(); }); PluginAPI.on('afterSave', function(data) { syncExternal(); }); PluginAPI.on('beforePublish', function(data) { return checkPublishRules(); }); PluginAPI.on('afterPublish', function(data) { notifySubscribers(); }); PluginAPI.on('beforeDelete', function(data) { return confirmDelete(); }); PluginAPI.on('afterDelete', function(data) { cleanupResources(); }); // Editor events PluginAPI.on('editorReady', function(data) { /* Editor fully loaded */ }); PluginAPI.on('editorFocus', function(data) { /* Editor gained focus */ }); PluginAPI.on('editorUnfocus', function(data) { /* Editor lost focus */ }); PluginAPI.on('modifiedContent', function(data) { /* Content changed */ }); // Plugin element events PluginAPI.on('pluginElementClicked', function(data) { handleClick(data); }); PluginAPI.on('pluginElementSelected', function(data) { showToolbar(data); }); PluginAPI.on('pluginElementDeselected', function(data) { hideToolbar(); }); PluginAPI.on('elementRemoved', function(data) { cleanup(data.id); }); // Plugin window events PluginAPI.on('receivedFocus', function(data) { console.log('Focus from:', data.previousPluginName); }); PluginAPI.on('pluginWindowMaximized', function(data) { /* Window maximized */ }); PluginAPI.on('pluginWindowRestored', function(data) { /* Window restored */ }); // Metadata events PluginAPI.on('addTag', function(data) { /* Tag added */ }); PluginAPI.on('addCategory', function(data) { /* Category added */ }); PluginAPI.on('changedCustomMeta', function(data) { console.log('Meta changed:', data.name, '=', data.value); }); ``` -------------------------------- ### Get Article Geolocation Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the currently set geolocation for an article. The result is returned via a callback function containing the location object. ```javascript ArticleCommunicator.getGeolocations(function(location) { console.log("Current location: ", location); }); ``` -------------------------------- ### Get Article ID Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/hello-world-plugin/index.html Retrieves the unique identifier for the current article being edited. The ID is then displayed in an input field. Dependencies: jQuery for DOM manipulation. ```javascript PluginAPI.Article.getId(function (id) { $('#getId-result').val(id); }); ``` -------------------------------- ### Manage Plugin Configuration Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Methods to retrieve and save custom plugin settings. Configurations can be scoped to specific publications. ```javascript PluginAPI.getConfiguration(function(config) { console.log('Plugin configuration:', config); var apiEndpoint = config.apiEndpoint || 'https://default.api.com'; var maxResults = config.maxResults || 10; initializePluginWithConfig(apiEndpoint, maxResults); }); var newConfig = { apiEndpoint: 'https://custom.api.com', maxResults: 25, enableFeatureX: true }; PluginAPI.setConfiguration(newConfig, { onlyPublication: true, success: function() { console.log('Configuration saved successfully'); }, error: function(err) { console.error('Failed to save configuration:', err); } }); ``` -------------------------------- ### Manage Plugin Window Size Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Provides functions to maximize the plugin window for an enhanced user interface and to restore it to its normal size. Includes callbacks for window state changes. ```javascript PluginAPI.Article.maximizePluginWindow('Image Editor', function() { // Called when window is closed/minimized console.log('Plugin window restored'); cleanupFullscreenMode(); }, function() { console.log('Plugin window maximized'); initializeFullscreenMode(); }); PluginAPI.Article.restorePluginWindow(function() { console.log('Window restored to normal size'); }); ``` -------------------------------- ### Get JWT for Authentication - JavaScript Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the JSON Web Token (JWT) configured for the DrPublish publication. This token is essential for authenticating requests made by the plugin. ```javascript PluginAPI.getJWT(tag, callback) ``` -------------------------------- ### AH5Communicator: Initialize Menus Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Initializes pre-registered menus within the DrPublish interface. It accepts an array of menu names (e.g., 'simplePluginMenu', 'editContext') and a callback function that receives a boolean indicating success. ```javascript AH5Communicator.initMenu(menus, callback) ``` -------------------------------- ### Show Loader - JavaScript Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Displays a loading indicator to the user, optionally with a message. This is used to provide feedback during long-running operations. ```javascript PluginAPI.showLoader(msg) ``` -------------------------------- ### PluginAPI.getDrPublishConfiguration Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the DrPublish specific configuration settings. ```APIDOC ## PluginAPI.getDrPublishConfiguration(callback) ### Description Get DrPublish configuration. ### Method Not applicable (JavaScript function call) ### Endpoint Not applicable (JavaScript function call) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Parameters - **callback** (Function) - Required - function(Object) Function to call with the DrPublish configuration object. ### Request Example ```javascript PluginAPI.getDrPublishConfiguration(function(config) { console.log('DrPublish Configuration:', config); }); ``` ### Response #### Success Response (200) - **Void** - The function does not return a value directly, results are passed via the callback. #### Response Example (Callback function receives the DrPublish configuration object) ``` -------------------------------- ### Fetch Article ID Dynamically Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/examples/hello-world-plugin/index.html Initializes the plugin and fetches the article ID dynamically whenever a new article is loaded in the editor. ```APIDOC ## Fetch Article ID Dynamically ### Description Sets the plugin name and fetches the current article ID when the article is loaded in the editor. ### Method N/A (JavaScript functions) ### Endpoint N/A ### Parameters None ### Request Example ```javascript initPlugin(); fetchArticleIdDynamically(); ``` ### Response Logs the article ID to the console and updates a DOM element with the fetched article ID. ``` -------------------------------- ### AH5Communicator: Get Asset Data Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves all data options for a referenced embedded asset using its DrPublish article ID. It requires a callback function that will receive the asset data. ```javascript AH5Communicator.getAssetData(dpArticleId, callback) ``` -------------------------------- ### AH5Communicator: Get Total Character Count Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the total number of characters in the currently open article. It requires a callback function that will receive the character count as its single parameter. ```javascript AH5Communicator.getTotalCharCount(callback) ``` -------------------------------- ### ArticleCommunicator.focusPlugin Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Gives focus to the current plugin. ```APIDOC ## POST ArticleCommunicator.focusPlugin ### Description Requests focus for the plugin within the article interface. ### Method POST ### Parameters #### Path Parameters - **callback** (Function) - Required - function(Boolean), called as the plugin gets focus ### Response #### Success Response (200) - **Void** - Returns nothing ``` -------------------------------- ### AH5Communicator: Get Total Word Count Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the total number of words present in the currently open article. It takes a callback function that will receive the word count as its single parameter. ```javascript AH5Communicator.getTotalWordCount(callback) ``` -------------------------------- ### Handle Plugin Lifecycle Events Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Registers event listeners for article lifecycle events. Returning false from 'before' events allows for cancellation of actions like saving. ```javascript PluginAPI.on('afterCreate', function(data) { console.log('New article created'); PluginAPI.Article.setSource('My Plugin'); }); PluginAPI.on('beforeSave', function(data) { if (!isArticleValid()) { PluginAPI.showErrorMsg('Article validation failed'); return false; } return true; }); PluginAPI.on('afterSave', function(data) { console.log('Article saved successfully'); }); ``` -------------------------------- ### Manage Article Properties Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Methods for fetching, updating, and saving article properties. Supports bulk updates via setProperties or single property updates via setProperty. ```javascript PluginAPI.Article.setProperties({ fooProperty: "bar", barProperty: "foo" }, function(properties) { console.log("Updated properties: ", properties); }); ArticleCommunicator.setProperty("status", "published", function(properties) { console.log("Property updated, new list: ", properties); }); ``` -------------------------------- ### AH5Communicator: Update Asset Data Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Updates all data associated with a referenced embedded asset. This method takes an object containing the updated data and a callback function. An example demonstrates the structure of the data object. ```javascript var data = { internalId: assetDpArticleId, assetElementId: activeAssetId, assetType: 'picture', assetSource: PluginAPI.getPluginName(), resourceUri: fullsizeUrl, previewUri: fullsizeUrl, renditions: { highRes: {uri: fullsizeUrl}, thumbnail: {uri: thumbnailUrl} }, options: {} } PluginAPI.Editor.updateAssetData(data); ``` -------------------------------- ### ArticleCommunicator.setTags Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Sets the tags for the article, with an option to force save. ```APIDOC ## ArticleCommunicator.setTags(tags, save, callback) ### Description Set tags for the article. ### Method Not specified (assumed to be a JavaScript function call) ### Endpoint N/A (Client-side JavaScript API) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **tags** (Array) - Required - List of tags that should be set - **save** (Boolean) - Required - Set to true to force save once the tags are updated - **callback** (Function) - Required - function(Boolean), called when tags have been set ### Request Example ```javascript ArticleCommunicator.setTags(['news', 'technology'], true, function(success) { console.log('Tags set successfully:', success); }); ``` ### Response #### Success Response (200) - **Void** - This method does not return a value directly, but invokes the callback. #### Response Example N/A ``` -------------------------------- ### Migrate Event Listeners to PluginAPI.on Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/UPGRADE.md The addListeners method is deprecated in v3.0. Use the .on() method to register event listeners individually, which now ensures consistent data object delivery. ```javascript // Before (Deprecated) PluginAPI.addListeners({ pluginElementClicked: pluginElementSelected, pluginElementDeselected: pluginElementDeselected }); // After PluginAPI.on('pluginElementClicked', pluginElementSelected); PluginAPI.on('pluginElementDeselected', pluginElementDeselected); ``` -------------------------------- ### ArticleCommunicator Class for Article Interaction Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md The ArticleCommunicator class in JavaScript is designed for interacting with the article content and metadata. It provides methods to get and set values, and manage plugin focus within the DrPublish environment. This class is essential for plugins that need to read or modify article data. ```javascript class ArticleCommunicator { // Constructor and methods would be defined here } // Example usage (conceptual): // const communicator = new ArticleCommunicator(); // communicator.focusPlugin(callbackFunction); ``` -------------------------------- ### PluginAPI.setConfiguration Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Updates the configuration information for the plugin. Can be set globally or for the current publication only. ```APIDOC ## PluginAPI.setConfiguration(config, options, callback) ### Description Set configuration information about the plugin. ### Method Not applicable (JavaScript function call) ### Endpoint Not applicable (JavaScript function call) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Parameters - **config** (Object) - Required - The configuration object to save. - **options** (Object) - Optional - Object with options. Can have keys: 'onlyPublication' (boolean), 'success' (function), 'error' (function). - **callback** (Function) - Optional - function() Function to call once the configuration is set. ### Request Example ```javascript const newConfig = { setting1: 'value1', setting2: 123 }; const options = { onlyPublication: true, success: function() { console.log('Configuration saved successfully!'); }, error: function(err) { console.error('Error saving configuration:', err); } }; PluginAPI.setConfiguration(newConfig, options, function() { console.log('Configuration update initiated.'); }); ``` ### Response #### Success Response (200) - **Void** - The function does not return a value directly. Success/error callbacks handle outcomes. #### Response Example (Success or error callback is invoked) ``` -------------------------------- ### Create Modals with PluginAPI.createModal Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Creates jQuery UI modal dialogs in the main editor window for user interactions. Modals can contain custom HTML content, options like title and width, and define button actions. It also provides a way to retrieve input values from modal forms. ```javascript PluginAPI.createModal('

Confirm Action

Are you sure you want to proceed?

', { title: 'Confirmation', width: 400, buttons: { 'Confirm': function() { performAction(); PluginAPI.closeModal(true); }, 'Cancel': function() { PluginAPI.closeModal(true); } } }); PluginAPI.createModal(`
`, { title: 'Enter Details', buttons: { 'Submit': function() { PluginAPI.getModalInputs(function(inputs) { console.log('Name:', inputs.name); console.log('Type:', inputs.type); PluginAPI.closeModal(true); }); } } }); ``` -------------------------------- ### Manage CSS Classes using PluginAPI.Editor.addClasses and removeClasses Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Enables adding or removing CSS classes from elements in the editor. Specify the element by its ID and provide an array of class names to add or remove. The callback function indicates whether the operation was successful. ```javascript // Add classes to element PluginAPI.Editor.addClasses('image-123', ['highlighted', 'featured'], function(success) { console.log('Classes added:', success); }); // Remove classes from element PluginAPI.Editor.removeClasses('image-123', ['draft'], function(success) { console.log('Classes removed:', success); }); ``` -------------------------------- ### PluginAPI.on Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Listens for specific events emitted within DrPublish. Callbacks can potentially cancel event actions. ```APIDOC ## PluginAPI.on(name, callback) ### Description Listen for an event. If the callback returns false the event may cancel continued actions, e.g. beforeSave can cancel article save. Look at documentation for Listeners to learn more. ### Method Not applicable (JavaScript function call) ### Endpoint Not applicable (JavaScript function call) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Parameters - **name** (String) - Required - Name of the event to listen for. - **callback** (Function) - Required - function(Object) Function to call when the event is triggered. Receives one data object parameter of the form {source: , data: }. ### Request Example ```javascript PluginAPI.on('article.beforeSave', function(eventData) { console.log('Article before save event triggered:', eventData); // return false; // to cancel the save action }); ``` ### Response #### Success Response (200) - **Void** - This function does not return a value. #### Response Example None ``` -------------------------------- ### PluginAPI.Article.getTags / setTags / addTag / removeTag Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Manages tags associated with the article, allowing retrieval, setting (replacing), adding, and removing individual tags. ```APIDOC ## PluginAPI.Article.getTags ### Description Retrieves all tags currently associated with the article. ### Method `PluginAPI.Article.getTags(callback)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```javascript PluginAPI.Article.getTags(function(tags) { console.log('Current tags:', tags); tags.forEach(function(tag) { console.log('Tag:', tag.name, 'Type:', tag.tagTypeId); }); }); ``` ### Response #### Success Response (200) - **tags** (array) - An array of tag objects. - **name** (string) - The name of the tag. - **tagTypeId** (number) - The ID of the tag type. #### Response Example ```json [ { "name": "Breaking News", "tagTypeId": 1 }, { "name": "Politics", "tagTypeId": 1 } ] ``` ### Error Handling Errors may occur if the callback function is not provided or if tags cannot be retrieved. ``` ```APIDOC ## PluginAPI.Article.setTags ### Description Sets all tags for the article, replacing any existing tags. Optionally saves the changes immediately. ### Method `PluginAPI.Article.setTags(tags, save, callback)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **tags** (array) - Required - An array of tag objects to set for the article. - **name** (string) - Required - The name of the tag. - **tagTypeId** (number) - Required - The ID of the tag type. - **save** (boolean) - Required - If `true`, saves the changes immediately. If `false`, changes are staged. - **callback** (function) - Optional - A function to be called upon completion. ### Request Example ```javascript PluginAPI.Article.setTags([ { name: 'Politics', tagTypeId: 1 }, { name: 'Economy', tagTypeId: 1 }, { name: 'John Smith', tagTypeId: 2 } ], true, function(success) { // true = save immediately console.log('Tags updated and saved'); }); ``` ### Response #### Success Response (200) Indicates that the tags were successfully set. The callback function is invoked if provided. #### Response Example (Callback function is executed, no direct JSON response) ```javascript // Callback executed upon success function(success) { console.log('Tags updated and saved'); } ``` ### Error Handling Errors may occur if the `tags` array is malformed, the `save` parameter is invalid, or if the callback function throws an exception. ``` ```APIDOC ## PluginAPI.Article.addTag ### Description Adds a single tag to the article. ### Method `PluginAPI.Article.addTag(tag, errorFn, callback)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **tag** (object) - Required - The tag object to add. - **name** (string) - Required - The name of the tag. - **tagTypeId** (number) - Required - The ID of the tag type. - **errorFn** (function) - Optional - A function to handle errors during tag addition. - **callback** (function) - Required - A function to be called upon successful addition. ### Request Example ```javascript PluginAPI.Article.addTag( { name: 'Breaking News', tagTypeId: 1 }, function(error) { console.error('Failed to add tag:', error); }, function(success) { console.log('Tag added:', success); } ); ``` ### Response #### Success Response (200) Indicates that the tag was successfully added. The callback function is invoked. #### Response Example (Callback function is executed, no direct JSON response) ```javascript // Callback executed upon success function(success) { console.log('Tag added:', success); } ``` ### Error Handling Errors may occur if the `tag` object is malformed, the `callback` function is not provided, or if the `errorFn` is triggered. ``` ```APIDOC ## PluginAPI.Article.removeTag ### Description Removes a specific tag from the article. ### Method `PluginAPI.Article.removeTag(tag, callback)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **tag** (object) - Required - The tag object to remove. - **name** (string) - Required - The name of the tag. - **tagTypeId** (number) - Required - The ID of the tag type. - **callback** (function) - Required - A function to be called upon successful removal. ### Request Example ```javascript PluginAPI.Article.removeTag({ name: 'Old Tag', tagTypeId: 1 }, function(success) { console.log('Tag removed:', success); }); ``` ### Response #### Success Response (200) Indicates that the tag was successfully removed. The callback function is invoked. #### Response Example (Callback function is executed, no direct JSON response) ```javascript // Callback executed upon success function(success) { console.log('Tag removed:', success); } ``` ### Error Handling Errors may occur if the `tag` object is malformed, the `callback` function is not provided, or if the tag does not exist. ``` -------------------------------- ### Manage Article Tags Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Provides methods to read, add, update, and remove tags associated with an article. Supports batch updates and immediate saving. ```javascript PluginAPI.Article.getTags(function(tags) { console.log('Current tags:', tags); }); PluginAPI.Article.addTag({ name: 'Breaking News', tagTypeId: 1 }, function(error) { console.error('Failed to add tag:', error); }, function(success) { console.log('Tag added:', success); } ); PluginAPI.Article.setTags([{ name: 'Politics', tagTypeId: 1 }], true, function(success) { console.log('Tags updated and saved'); }); ``` -------------------------------- ### Search DrLib - JavaScript Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Sends a query to the DrLib service to search for articles or other content. Supports secure searching with an API key and provides success/error callbacks. ```javascript PluginAPI.searchDrLib({ query: 'articles.json?q=awesome', secure: true, success: function(data) { data.items.forEach(doStuffWithArticle); }, error: function(data) { console.warn('something went wrong'); } }) ``` -------------------------------- ### ArticleCommunicator.getProperties Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Fetches a list of all properties available to an article. A callback function is provided to receive the array of property objects. ```APIDOC ## ArticleCommunicator.getProperties ### Description Fetches a list of all properties available to an article. ### Method GET (assumed, as it retrieves state) ### Endpoint /aptoma/drpublish-plugin-api/article/properties ### Parameters #### Query Parameters - **callback** (Function) - Required - Callback called with an array of property objects. ``` -------------------------------- ### Manage Article Content Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Enables retrieval and modification of the main article content. Content can be set using HTML strings. Asynchronous operations are handled via callbacks. ```javascript PluginAPI.Article.getCurrentContent(function(content) { console.log('Article content:', content); }); PluginAPI.Article.setCurrentContent('

New article content here.

', function(success) { console.log('Content updated:', success); }); ``` -------------------------------- ### Register Context Menu Action for Plugin Elements Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Registers a new item in the context menu for plugin elements. It accepts an action object containing labels, icons, and a callback function to handle user interactions. ```javascript PluginAPI.Editor.registerMenuAction({ label: 'label in the menu', icon: '[Optional] url to possible icon image', trigger: '[Optional] css selector, only show menu element when this matches the element', callback: function(id, clickedElementId) { // callback function // first parameter is id of the plugin element // second paramter is id of closest element to the trigger element that has an id // in code: $(event.triggerElement).closest('[id]').attr('id'); } }) ``` -------------------------------- ### Retrieve and Use JWT for Authentication Source: https://context7.com/aptoma/drpublish-plugin-api/llms.txt Fetches the current JWT token from the publication configuration to authenticate requests against external backend services. ```javascript var jwt = PluginAPI.getJWT(); if (jwt !== '') { var base64Url = jwt.split('.')[1]; var base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/'); var payload = JSON.parse(atob(base64)); fetch('/api/data', { headers: { 'Authorization': 'Bearer ' + jwt } }); } ``` -------------------------------- ### PluginAPI.getJWT Source: https://github.com/aptoma/drpublish-plugin-api/blob/develop/DOCUMENTATION.md Retrieves the JWT token for authenticating requests based on publication configuration. ```APIDOC ## GET PluginAPI.getJWT ### Description Retrieves the JWT as defined on DrPublish publication config to authenticate requests. ### Method GET ### Endpoint PluginAPI.getJWT(tag, callback) ### Parameters #### Path Parameters - **tag** (String) - Required - The tag to create - **callback** (Function) - Required - function(Boolean) ### Response #### Success Response (200) - **token** (String) - The JWT token ```