Editor

DSHDLib.Editors.insert("parent_container_id", { project_id: "abc" }, function(err, e){
    var editor = e;
});

Methods

addElement(elementnon-null, callbackopt)

Description:

• Add a new element to a page/scene in the loaded project

Source:

• lib.js, line 1506

Examples

editor.addElement({
    element_name: "unique_id",
    element_classes: ["header"],
    type: "text",
    default_style: "header",
    color: "#1eefc9",
    text: "Lorem ipsum...",
    top: 100,
    left: 100,
    width: 200
}, function(err, element){
    console.log("New Element ID:", element.element_id);
});

editor.addElement({
    page_id: "abc",
    element_classes: ["image"],
    type: "image",
    placement: "foreground",
    url: "https://publicorsignedurl.com/file.jpg",
    top: 100,
    selected: false
}, function(err, element){
    console.log("New Element Width:", element.width);
});

editor.addElement({
    type: "vector",
    vector_type: "svg",
    url: "data:image/svg+xml;base64, ... ",
    color_map: {
        "#1ccfc9": 'spot("Pantone Jade",84,2,33,1)',
        "#eeffee": "cmyk(5,10,15,20)",
        "#012639": "transparent"
    },
    width: 500
});

editor.addElement({
    type: "video",
    placement: "background",
    asset: { store: "library", asset_code: "abc" },
    top: 100,
    trim_end: 8.5,
    expand_scene: true
});

editor.addElement({
    element_classes: ["music"],
    type: "audio",
    context: "global",
    url: "https://publicorsignedurl.com/track.mp3",
    track_name: "BG Track"
});

editor.addElement({
    element_classes: ["logo_placeholder"],
    type: "zone",
    zone_type: "fit",
    enforce_boundary: true,
    width: 500,
    height: 500,
    top: 100,
    left: 100
}, function(err, element){
    console.log("New Element ID:", element.element_id);
});

Parameters:

addPage(optionsopt, callbackopt)

Description:

• Add a new page to the current project

Source:

• lib.js, line 1242

Examples

editor.addPage();

editor.addPage({
    clone_of_page_id: "abc",
    position: "beginnning",
    page_name: "Altered Name"
}, function(err, page){
    console.log("New Page ID:", page.page_id);
});

Parameters:

addScene(optionsopt, callbackopt)

Description:

• Add a new scene to the current video project

Source:

• lib.js, line 1210

Examples

editor.addScene();

editor.addScene({
    clone_of_scene_id: "abc",
    position: "after_selection",
    scene_name: "Altered Name",
    duration: 3
}, function(err, scene){
    console.log("New Scene ID:", scene.scene_id);
});

Parameters:

cancelPendingReview()

Description:

• Cancel the pending review request for a project with an approval_status of "pending_review" (exposed via getProjectData)

Source:

• lib.js, line 3194

Example

editor.cancelPendingReview();

changeElements(objectnon-null)

Description:

• Make one or more changes to the current project

Source:

• lib.js, line 1678

Deprecated:

• Renamed to updateElements for naming consistency

Parameters:

changeGalleryID(idnon-null, galleryopt)

Description:

• Change the value used to filter a third party media gallery

Source:

• lib.js, line 1883

Example

editor.changeGalleryID("abc");

Parameters:

changePage(optionsnon-null)

Description:

• Change the page currently visible in the editor (for projects with a digital or print media type)

Source:

• lib.js, line 1836

Example

editor.changePage({ page_id: "abc" });

Parameters:

changeProductImage(optionsnon-null)

Description:

• Change the currently displayed product image background. Read full documentation here

Source:

• lib.js, line 1852

Example

editor.changeProductImage({ product_image_url: "https://publicorsignedurl.com/image.jpg" });

Parameters:

changeProject(project_idnon-null)

Description:

• Load a different project into the editor

Source:

• lib.js, line 1038

Example

editor.changeProject("abc");

Parameters:

changeScene(optionsnon-null)

Description:

• Change the scene currently visible in the editor (for projects with a video media type)

Source:

• lib.js, line 1825

Example

editor.changeScene({ scene_id: "abc" });

Parameters:

changeTemporaryBackground(optionsnon-null)

Description:

• Change the temporary background image or color. Great for simulating paper color/material on print projects. Will be masked inside the canvas (unlike images set via changeProductImage), and visible behind the actual (saved) project background, so make that transparent in the template/project to use this feature.

Source:

• lib.js, line 1866

Examples

editor.changeTemporaryBackground({ color: "#FF0000" });

editor.changeTemporaryBackground({ image_url: "https://publicorsignedurl.com/image.jpg" });

Parameters:

cloneElements(element_idsnon-null, callbackopt)

Description:

• Clone one or more elements within a page/scene in the loaded project

Source:

• lib.js, line 1721

Example

editor.cloneElements(["abc","def"], function(err, elements){
    console.log("New Element IDs:", elements.map(el => el.element_id).join(", "));
});

Parameters:

convertToZone(element_idnon-null, optionsopt)

Description:

• Wrap a zone around an existing element to make it easily replaceable, maintaining its exact size and position

Source:

• lib.js, line 1759

Example

editor.convertToZone("abc");

Parameters:

getElementData(element_id, callbacknon-null)

Description:

• Request and receive the properties of a specific element on any page/scene in the project

Source:

• lib.js, line 2766

Example

editor.getElementData("abc", function(err, element){
    console.log("Element Type:", element.type);
});

Parameters:

getPageData(page_id, callbacknon-null)

Description:

• Request and receive the properties of a specific page in the project and all of its elements

Source:

• lib.js, line 2848

Example

editor.getPageData("abc", function(err, page){
    console.log("Width:", page.dimensions.width);
});

Parameters:

getProjectData(optionsopt, callbacknon-null)

Description:

• Request and receive the properties of a project and all of its elements

Source:

• lib.js, line 2898

Example

editor.getProjectData({}, function(err, project){
    console.log("Project Title:", project.project_title);
});

Parameters:

getRender(optionsopt, callbacknon-null)

Description:

• Request and receive a rendered image of a page/scene from the editor

Source:

• lib.js, line 3018

Example

var options = {
    max_width: 500,
    max_height: 500,
    customizations: {
        elements: {
           "full_name": {
               text: "John Doe",
               auto_fit: true
           }
        }
    }
};
editor.getRender(options, function(err, data){
    if (!err) {
        var width = data.width;
        var height = data.height;
        var data_url = data.url;
        var img = new Image();
        img.src = data_url;
    }
});

Parameters:

getSceneData(scene_id, callbacknon-null)

Description:

• Request and receive the properties of a specific scene in a video project and all of its elements

Source:

• lib.js, line 2824

Example

editor.getSceneData("abc", function(err, scene){
    console.log("Width:", scene.dimensions.width);
});

Parameters:

handleApprovalStatusChange(callbacknon-null)

Description:

• Receive notification after the project approval status changes via showSubmitForReview, showSubmitRevision, cancelPendingReview or project data changes that require re-submission

Source:

• lib.js, line 2729

Example

editor.handleApprovalStatusChange(function(e, data){
    console.log("New Status:", data.approval_status);
});

Parameters:

handleColorSelection(callbacknon-null)

Description:

• Receive notification when the user clicks into a color swatch in one of the editor menus and suppress the built in color menu. Intended to override the default color controls with your own UI (e.g. with specific Pantone color swatch support) and then update the selected element(s) colors property via updateElements

Source:

• lib.js, line 2613

Example

editor.handleColorSelection(function(e, data){
    var rgb_to_display = data.selected_color[0].rgb.hex;
});

Parameters:

handleElementData(callbacknon-null)

Description:

• Receive information from every element data request

Source:

• lib.js, line 2326

Example

editor.handleElementData(function(e, element){
    console.log("Element Type:", element.type);
});

Parameters:

handleElementSelection(callbacknon-null)

Description:

• Receive notification when the user selects one or more elements inside the editor. Useful to show custom menus that update the selected elements via updateElements

Source:

• lib.js, line 2524

Deprecated:

• Replaced with handleSelectionChange to support firing when all elements are deselected as well

Example

editor.handleElementSelection(function(e, elements){
    var element_ids = Object.keys(elements);
    console.log("Selected Element(s): ", element_ids);
});

Parameters:

handleError(callbacknon-null)

Description:

• Receive a notification upon any network connection issues or other unresolvable errors that render the Editor unusable

Source:

• lib.js, line 1900

Example

editor.handleError(function(e){
    console.log("Error occurred");
});

Parameters:

handleMediaUploadRequest(callbacknon-null)

Description:

• Receive notification when the user clicks any Upload button in the editor. Intended to override the default file upload process with your own (e.g. custom file pre-processing) and then reference the file in adding a new element (addElement) or updating the selected element (updateElements). Note that this event is usually paired with the setting to disable media drag/drop functionality within the editor.

Source:

• lib.js, line 2642

Example

editor.handleMediaUploadRequest(function(e, data){
    var e = document.createElement("input");
    e.setAttribute("type", "file");
    e.setAttribute("style", "display:none");
    e.setAttribute("accept", "." + data.allowed_file_types.join(", ."));
    document.body.appendChild(e);
    e.click();
});

Parameters:

handleNavigateTemplateManagement(callbacknon-null)

Description:

• Receive notification when the user clicks to view all templates after publising a template via showPublishTemplate

Source:

• lib.js, line 2668

Example

editor.handleNavigateTemplateManagement(function(e){
    location.href = '/templates';
});

Parameters:

handlePageChange(callbacknon-null)

Description:

• Receive a notification when the page is changed in the editor. Useful for displaying page-specific contextual info outside the editor

Source:

• lib.js, line 1964

Example

editor.handlePageChange(function(e, data){
    console.log("New Page ID:", data.page_id);
});

Parameters:

handlePageData(callbacknon-null)

Description:

• Receive information from every page data request

Source:

• lib.js, line 2372

Example

editor.handlePageData(function(e, page){
    console.log("Width:", page.dimensions.width);
});

Parameters:

handleProjectChange(callbacknon-null)

Description:

• Override the default behavior when the project context is changed based on an action taken within the editor (e.g. clone to new size/media type)

Source:

• lib.js, line 2017

Example

editor.handleProjectChange(function(e, data){
    console.log("New Project ID:", data.project_id);
    e.changeProject(data.project_id);
});

Parameters:

handleProjectData(callbacknon-null)

Description:

• Receive information from every project data request

Source:

• lib.js, line 2395

Example

editor.handleProjectData(function(e, project){
    console.log("Project Title:", project.project_title);
});

Parameters:

handleProjectDataChange(callbacknon-null, optionsopt)

Description:

• Receive notification when any change to the project data occurs within the editor. Useful to trigger getProjectData for validation routines

Source:

• lib.js, line 2445

Deprecated:

• Renamed to handleProjectDataModification for naming consistency

Parameters:

handleProjectDataModification(callbacknon-null, optionsopt)

Description:

• Receive notification when any change to the project data occurs within the editor. Useful to trigger getProjectData for validation routines

Source:

• lib.js, line 2459

Example

editor.handleProjectDataModification(function(e, updates){
    console.log("Pages/Scenes Altered:", Object.keys(updates.pages || updates.scenes).length);
});

Parameters:

handleProjectTitleChange(callbacknon-null)

Description:

• Receive notification after the user changes the project title via showChangeTitle

Source:

• lib.js, line 2692

Deprecated:

• Renamed to handleProjectTitleUpdate for naming consistency

Parameters:

handleProjectTitleUpdate(callbacknon-null)

Description:

• Receive notification after the user changes the project title via showUpdateTitle

Source:

• lib.js, line 2704

Example

editor.handleProjectTitleUpdate(function(e, data){
    console.log("New Title:", data.project_title);
});

Parameters:

handleReload(callbacknon-null)

Description:

• Override the default behavior when the editor needs to reload

Source:

• lib.js, line 1939

Example

editor.handleReload(function(e, cfg){
    console.log("Editor Reloading");
    e.reload(cfg);
});

Parameters:

handleRender(callbacknon-null)

Description:

• Receive information from every render request. To be used along with requestRender

Source:

• lib.js, line 2494

Example

editor.handleRender(function(e, data){
    var width = data.width;
    var height = data.height;
    var data_url = data.url;
    var img = new Image();
    img.src = data_url;
});

Parameters:

handleSceneChange(callbacknon-null)

Description:

• Receive a notification when the scene is changed in the editor. Useful for displaying scene-specific contextual info outside the editor

Source:

• lib.js, line 1988

Example

editor.handleSceneChange(function(e, data){
    console.log("New Scene ID:", data.scene_id);
});

Parameters:

handleSceneData(callbacknon-null)

Description:

• Receive information from every scene data request on a video project

Source:

• lib.js, line 2349

Example

editor.handleSceneData(function(e, scene){
    console.log("Width:", scene.dimensions.width);
});

Parameters:

handleSelectionChange(callbacknon-null)

Description:

• Receive notification when the user selects one or more elements inside the editor or when all elements are deselected. Useful to show custom menus that update the selected elements via updateElements

Source:

• lib.js, line 2554

Example

editor.handleSelectionChange(function(e, elements){
    var element_ids = Object.keys(elements);
    console.log("Selected Element(s): ", element_ids);
});

Parameters:

handleUnauthenticated(callbacknon-null)

Description:

• Receive a notification when the access token being used has expired. You may then request a new access token and update the editor

Source:

• lib.js, line 1915

Example

editor.handleUnauthenticated(function(e){
    //retrieve new access token
    e.refreshAccessToken("new_token");
});

Parameters:

highlightElements(element_idsnon-null, optionsopt)

Description:

• Highlight specific elements on the currently open page/scene in the editor

Source:

• lib.js, line 3071

Examples

editor.highlightElements([element_id1, element_id2]);

editor.highlightElements([element_id1, element_id2], { duration: 2000, fill_color: "#FF0000" });

Parameters:

importPages(options)

Description:

• Import pages from a different project into the current project

Source:

• lib.js, line 1296

Example

editor.importPages({
    project_id: "abc",
    page_ids: ["def"],
    position: "end"
});

Parameters:

importScenes(options)

Description:

• Import scenes from a different project into the current project

Source:

• lib.js, line 1279

Example

editor.importScenes({
    project_id: "abc",
    scene_ids: ["def"],
    position: "end"
});

Parameters:

onInitialized(callbacknon-null)

Description:

• Wait for editor initialization before running other code

Source:

• lib.js, line 1054

Example

editor.onInitialized(function(e){
    console.log('Editor Initialized');
});

Parameters:

playAll(optionsopt)

Description:

• For video projects, open the Play All popup and start playing the entire video

Source:

• lib.js, line 3105

Example

editor.playAll();

Parameters:

playScene(optionsopt)

Description:

• For video projects, play the currently visible scene on the canvas

Source:

• lib.js, line 3091

Example

editor.playScene();

Parameters:

refreshAccessToken(access_tokenopt, callbackopt)

Description:

• Request a new guest token or update the explicitly-provided access token when approaching expiration or upon notification of authorization failure

Source:

• lib.js, line 1071

Example

editor.refreshAccessToken("abc");

Parameters:

reload(optionsopt)

Description:

• Reload the editor. Useful if making external project state changes

Source:

• lib.js, line 1111

Examples

editor.reload();

editor.reload({ page_number: 2 });

editor.reload({ scene_number: 3 });

Parameters:

remove()

Description:

• Remove the editor iframe from the DOM and clean up state. This is required before initializing another editor with the same project

Source:

• lib.js, line 1142

Example

editor.remove();

removeElements(element_idsnon-null)

Description:

• Remove elements from the current project

Source:

• lib.js, line 1746

Example

editor.removeElements(["abc"]);

Parameters:

removePages(page_idsnon-null)

Description:

• Remove pages/layouts from the current project

Source:

• lib.js, line 1368

Example

editor.removePages(["abc"]);

Parameters:

removeScenes(scene_idsnon-null)

Description:

• Remove scenes/layouts from the current video project

Source:

• lib.js, line 1358

Example

editor.removeScenes(["abc"]);

Parameters:

requestElementData(element_idnon-null)

Description:

• Request the properties of a specific element on any page/scene in the project. To be used along with handleElementData

Source:

• lib.js, line 2744

Example

editor.requestElementData("abc");

Parameters:

requestPageData(page_idnon-null)

Description:

• Request the properties of one page in a project and all of its elements. To be used along with handlePageData

Source:

• lib.js, line 2802

Example

editor.requestPageData("abc");

Parameters:

requestProjectData(optionsopt)

Description:

• Request the properties of a project and all of its elements. To be used along with handleProjectData

Source:

• lib.js, line 2871

Example

editor.requestProjectData();

Parameters:

requestRender(optionsopt)

Description:

• Request a rendered image of a page/scene from the editor. To be used along with handleRender

Source:

• lib.js, line 2980

Example

var options = {
    max_width: 500,
    max_height: 500
};
editor.requestRender(options);

Parameters:

requestSceneData(scene_idnon-null)

Description:

• Request the properties of one scene in a video project and all of its elements. To be used along with handleSceneData

Source:

• lib.js, line 2789

Example

editor.requestSceneData("abc");

Parameters:

resizePage(options)

Description:

• Resize pages in the current project

Source:

• lib.js, line 1338

Example

editor.resizePage({
    width: 50,
    height: 50,
    page_id: "abc"
});

Parameters:

resizeScenes(options)

Description:

• Resize all scenes in the current project

Source:

• lib.js, line 1323

Example

editor.resizeScenes({
    width: 1920,
    height: 1080
});

Parameters:

saveLockingConfig()

Description:

• Save any unsaved locking configuration changes (exposed via unsaved_locking_config in getProjectData)

Source:

• lib.js, line 3206

Example

editor.saveLockingConfig();

selectElements(element_idsnon-null, optionsopt)

Description:

• Select one or more elements on the currently visible page/scene

Source:

• lib.js, line 1808

Examples

editor.selectElements(["abc"]);

editor.selectElements(["abc","def"], { deselect: true });

Parameters:

showChangeTitle()

Description:

• Open the built-in Set Title popup within the editor to allow the user to easily change the project title without building a custom title change workflow via the Update Project API endpoint

Source:

• lib.js, line 3119

Deprecated:

• Renamed to showUpdateTitle for naming consistency

showExport(optionsopt)

Description:

• Open the built-in Export popup within the editor to allow the user to easily export an image/pdf/video without building a custom export workflow via the Export API endpoint

Source:

• lib.js, line 3142

Example

editor.showExport();

Parameters:

showPublishTemplate()

Description:

• Open the built-in Publish Template popup within the editor to allow an admin to easily publish a template from the open project without building a custom template publishing workflow via the Publish Template API endpoint

Source:

• lib.js, line 3158

Example

editor.showPublishTemplate();

showSubmitForReview()

Description:

• Open the built-in Submit For Approval popup within the editor to allow a user to easily submit this project for approval, for projects without an approval_status or those that have been previously "approved" (exposed via getProjectData)

Source:

• lib.js, line 3170

Example

editor.showSubmitForReview();

showSubmitRevision()

Description:

• Open the built-in Submit Revision popup within the editor to allow a user to easily re-submit this project for approval, for projects with an approval_status of "awaiting_revisions" or "denied" (exposed via getProjectData)

Source:

• lib.js, line 3182

Example

editor.showSubmitRevision();

showUpdateTitle()

Description:

• Open the built-in Set Title popup within the editor to allow the user to easily update the project title without building a custom title change workflow via the Update Project API endpoint

Source:

• lib.js, line 3130

Example

editor.showUpdateTitle();

updateBackgroundColor(optionsnon-null)

Description:

• Update the background color of one or more pages/scenes. Note that addElement with "background" placement can be used to set a background image/video instead

Source:

• lib.js, line 1774

Example

editor.updateBackgroundColor({ color: "#ffffff" });

Parameters:

updateCanvasBorder(optionsnon-null)

Description:

• Set a die cut border for stickers. Must be using a custom canvas shape on a Print project. Applied as an outer stroke

Source:

• lib.js, line 1792

Example

editor.updateCanvasBorder({ width: 0.25, color: "cmyk(0,0,0,0)" });

Parameters:

updateElements(objectnon-null)

Description:

• Make one or more updates to elements in the current project

Source:

• lib.js, line 1690

Example

editor.updateElements({
    elements: {
        "abc": {
            text: "My New Text"
        },
        "def": {
            top: 300,
            colors: ["#efefef"]
        }
    }
});

Parameters:

Type Definitions

ModifiedElement

Description:

• Properties specific to modified elements referenced in handleProjectDataModificationCallback

Source:

• lib.js, line 2410

Properties:

ModifiedPage

Description:

• Properties specific to modified pages referenced in handleProjectDataModificationCallback

Source:

• lib.js, line 2417

Properties:

ModifiedScene

Description:

• Properties specific to modified scenes referenced in handleProjectDataModificationCallback

Source:

• lib.js, line 2425

Properties:

addElementCallback(erroropt, elementopt)

Description:

• Callback supplying an error or the new element properties

Source:

• lib.js, line 1498

Parameters:

addPageCallback(erroropt, pageopt)

Description:

• Callback supplying an error or the new page properties

Source:

• lib.js, line 1234

Parameters:

addSceneCallback(erroropt, sceneopt)

Description:

• Callback supplying an error or the new scene properties

Source:

• lib.js, line 1202

Parameters:

cloneElementsCallback(erroropt, elementsopt)

Description:

• Callback supplying an error or an array of the newly created elements

Source:

• lib.js, line 1713

Parameters:

editorCallback(editor)

Description:

• Callback supplying the editor instance a listener was triggered on

Source:

• lib.js, line 862

Parameters:

getElementDataCallback(erroropt, elementopt)

Description:

• Callback supplying an error or the requested element

Source:

• lib.js, line 2758

Parameters:

getPageDataCallback(erroropt, pageopt)

Description:

• Callback supplying an error or the requested page

Source:

• lib.js, line 2840

Parameters:

getProjectDataCallback(erroropt, projectopt)

Description:

• Callback supplying an error or the requested project properties

Source:

• lib.js, line 2890

Parameters:

getRenderCallback(erroropt, dataopt)

Description:

• Callback supplying an error or the rendered image data

Source:

• lib.js, line 3007

Parameters:

getSceneDataCallback(erroropt, sceneopt)

Description:

• Callback supplying an error or the requested scene on a video project

Source:

• lib.js, line 2816

Parameters:

handleApprovalStatusChangeCallback(editor, data)

Description:

• Callback supplying the editor instance the project approval status change was triggered on and the new approval status

Source:

• lib.js, line 2719

Parameters:

handleColorSelectionCallback(editor, data)

Description:

• Callback supplying the editor instance the color swatch click was triggered on, the current details of the color clicked, and information about the selected element(s)

Source:

• lib.js, line 2581

Tutorials:

• Colors

Parameters:

handleElementDataCallback(editor, element)

Description:

• Callback supplying the editor instance the element data request was triggered on and the element properties

Source:

• lib.js, line 2318

Parameters:

handleMediaUploadRequestCallback(editor, data)

Description:

• Callback supplying the editor instance the Upload button click was triggered on and context about the upload request

Source:

• lib.js, line 2631

Parameters:

handlePageChangeCallback(editor, data)

Description:

• Callback supplying the editor instance the page change was triggered on and the id of the newly open page

Source:

• lib.js, line 1955

Parameters:

handlePageDataCallback(editor, page)

Description:

• Callback supplying the editor instance the page data request was triggered on and the page properties

Source:

• lib.js, line 2364

Parameters:

handleProjectChangeCallback(editor, data)

Description:

• Callback supplying the editor instance the project change was triggered on and the id of the new project

Source:

• lib.js, line 2008

Parameters:

handleProjectDataCallback(editor, project)

Description:

• Callback supplying the editor instance the element data request was triggered on and the project properties

Source:

• lib.js, line 2387

Parameters:

handleProjectDataModificationCallback(editor, updates)

Description:

• Callback supplying the editor instance the update occurred on and the specifics of the update

Source:

• lib.js, line 2433

Parameters:

handleProjectTitleUpdateCallback(editor, data)

Description:

• Callback supplying the editor instance the project title update was triggered on and the new project title

Source:

• lib.js, line 2683

Parameters:

handleReloadCallback(editor, data)

Description:

• Callback supplying the editor instance a reload was triggered on and the reload config

Source:

• lib.js, line 1931

Parameters:

handleRenderCallback(editor, data)

Description:

• Callback supplying the editor instance the render request was triggered on and the rendered image data

Source:

• lib.js, line 2483

Parameters:

handleSceneChangeCallback(editor, data)

Description:

• Callback supplying the editor instance the scene change was triggered on and the id of the newly open scene

Source:

• lib.js, line 1979

Parameters:

handleSceneDataCallback(editor, scene)

Description:

• Callback supplying the editor instance the scene data request was triggered on and the scene properties

Source:

• lib.js, line 2341

Parameters:

handleSelectionCallback(editor, elements, pointeropt)

Description:

• Callback supplying the editor instance the element selection was triggered on and information about the selected element(s)

Source:

• lib.js, line 2513

Parameters: