ElementUpdates

DSHDLib.Editors.ProjectData. Namespace

ElementUpdates

Source:

Type Definitions

ElementUpdate

Description:
  • An object containing data to update a matched element.
Source:
Tutorials:
Properties:
Name Type Attributes Description
element_name string <optional>
 An optional unique identifier to assign/update on a matched element. Useful for subsequent updateElements requests that can now reference an element by name. Note that element_name must be unique per element across all elements in a project.
element_classes Array.<string> <optional>
 An optional list of classes to associate with each matched element
colors Array.<string> <optional>
 An array of colors to update on a matched text, shape or line element. Match the array order of colors retrieved via getProjectData or handleColorSelection
text string <optional>
 The replacement text to fully overwrite a matched text element. Note that this will remove any existing character specific style overrides
text_markup string <optional>
 The replacement text to fully overwrite a matched text element, optionally including some html tags
text_insert Object <optional>
 The text and position of new data to insert/replace in a matched text element. Note that this will preserve existing style overrides with the exception of range replacements that span multiple styles. Useful in conjunction with the cursor information returned from getElementData on selected text elements
Properties
Name Type Description
text string The new text to insert within the existing text string
position number | Array.<number> The 0-based position to insert the new text. Can optionally be supplied as an array containing a start and end index which will overwrite the existing text in that range with the newly supplied text
width number <optional>
 The width to resize a matched element to in the unit type of the project. Auto calculates height to preserve aspect ratio if explicit height is not provided on image and svg vector types
height number <optional>
 The height to resize a matched image/vector element to in the unit type of the project. Auto calculates width to preserve aspect ratio if explicit width is not provided on image and svg vector types
angle number <optional>
 The rotation degrees to set on a matched element
left number <optional>
 The x coordinate to move the top of the matched element to in the unit type of the project
top number <optional>
 The y coordinate to move the left side of the matched element to in the unit type of the project
flip_horizontal bool <optional>
 A value indicating whether to flip/unflip a matched image element horizontally
flip_vertical bool <optional>
 A value indicating whether to flip/unflip a matched image element vertically
constrain_proportions bool <optional>
 A value indicating whether to lock the aspect ratio of a matched vector/zone element when resizing
opacity number <optional>
 The opacity percentage to set on a matched element, between 0 and 1
url string <optional>
 A public or signed url reference or a data url for a svg, pdf, png, jpg, webp, heic, gif or tiff file. This will either be placed in a matched zone or replace a placeholder shape element
url_file_type string <optional>
 One of: "pdf", "svg". Only necessary for svg/pdf url's if no file extension is present
blob Blob <optional>
 A Blob of a raster image or video file. This will either be placed in a matched zone or replace a placeholder shape element
blob_file_type string <optional>
 For non-browser supported files, provide the source file extension (without the ".") of the supplied blob
position_relative_to_original Object <optional>
 Override the default position (relative to the matching zone/shape) for images placed via the "url" property
Properties
Name Type Attributes Description
horizontal_align string <optional>
 A horizontal position of "left", "center" or "top"
vertical_align string <optional>
 A vertical position of "top", "center" or "bottom"
masked_media Object <optional>
 Set or update a masked image in a matched shape element
Properties
Name Type Attributes Description
url string <optional>
 A public or signed url reference or a data url for a png, jpg, webp, heic, gif or tiff file that will be masked in a matched shape element
blob Blob <optional>
 A Blob of a video file that will be masked in a matched shape element
blob_file_type string <optional>
 For non-browser supported files, provide the source file extension (without the ".") of the supplied blob
asset DSHDLib.Editors.ProjectData.ElementUpdates.ElementUpdateAsset <optional>
 Data reference to a image/video asset to mask in a matched shape element
color_overlay Object <optional>
 A color overlay to apply to a matched masked image
Properties
Name Type Attributes Description
color string <optional>
 The color to apply (RGB/CMYK/SPOT)
percentage number <optional>
 A number between 0 and 1 representing the intensity of the color overlay
asset DSHDLib.Editors.ProjectData.ElementUpdates.ElementUpdateAsset <optional>
 Data reference to an asset to place in a matched zone or replace a placeholder shape element
color_overlay Object <optional>
 A color overlay to apply to a matched image element
Properties
Name Type Attributes Description
color string <optional>
 The color to apply (RGB/CMYK/SPOT)
percentage number <optional>
 A number between 0 and 1 representing the intensity of the color overlay
remove_background bool <optional>
 If AI-based image background removal is enabled in your account, this will remove the background of a matched image element when true or re-place the background when false
layers Object.<string, DSHDLib.Editors.ProjectData.ElementUpdates.LottieLayerUpdate> <optional>
 A collection of layer specific text/color/image data, keyed off the layer name used in the lottie, to update in a matched lottie element
trim_start number <optional>
 The position in seconds to start a matched video element
trim_end number <optional>
 The position in seconds to end a matched video element
font_file_id number <optional>
 The font to set on a matched text element. Will overwrite any existing partial fonts (e.g. bold/italic)
font_size number <optional>
 The font size to set on a matched text element in pt for print projects or px for all other media types. Will override Auto Fit if enabled
align string <optional>
 The horizontal alignment on text elements within their textbox. One of: "left", "center", "right", "justify"
vertical_anchor string <optional>
 The anchor on text elements as line wrapping occurs. One of: "top", "middle", "bottom"
rtl bool <optional>
 Used to switch a textbox between left-to-right (ltr) entry mode false and right-to-left (rtl) entry mode true
auto_fit DSHDLib.Editors.ProjectData.ElementUpdates.TextAutoFitProperties <optional>
 The Auto Fit configuration to apply to a matched text element
text_token_map Object.<string, string> <optional>
 A map of tokens that may be present in the text and their respective default replacement values
pattern Object <optional>
 Update the pattern settings on an image/vector in a pattern type zone
Properties
Name Type Attributes Description
size number <optional>
 A number between 0 and 1 representing the desired size of each tile in the pattern relative to its zone's dimensions
margin number <optional>
 A number between 0 and 1 representing the size of the desired margin between tiles relative to the dimensions of each tile
angle number <optional>
 A number between 0 and 359 representing the desired angle of the pattern relative to its zone
blend_mode string <optional>
 The blend mode to apply to the element. One of: "none", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity"
ignore_low_dpi bool <optional>
 A value indicating whether the Poor Image Quality warning should trigger for this image when its pixel density is too low for the project's DPI (when the AI Upscale feature is enabled)
An object containing data to update a matched element.
Type:
  • Object

ElementUpdateAsset

Description:
  • Video asset reference to populate a matched placeholder element
Source:
Properties:
Name Type Attributes Description
asset_type string One of: "image", "vector", "video"
store string Must be "library"
asset_id number <optional>
 The internal asset_id of the asset to place. Must be provided without asset_code
asset_code string <optional>
 The id of the asset to place from the originating repository. Must be provided without asset_id
Video asset reference to populate a matched placeholder element
Type:
  • Object

LottieLayerUpdate

Description:
  • Layer specific data to update in a matched lottie element
Source:
Properties:
Name Type Attributes Description
text string <optional>
 The replacement text to fully overwrite the existing text in this layer of the matched lottie element
color string <optional>
 The RGB color to apply to this layer of the matched lottie element
url string <optional>
 A public or signed url reference or a data url for a svg, png, jpg, webp, heic, gif or tiff file. This will replace the image in this layer of the matched lottie element
asset DSHDLib.Editors.ProjectData.ElementUpdates.ElementUpdateAsset <optional>
 Data reference to an image/vector asset to replace the image in this layer of the matched lottie element
Layer specific data to update in a matched lottie element
Type:
  • Object

ProjectUpdateObject

Description:
  • An object containing data to populate into the loaded project
Source:
Properties:
Name Type Attributes Default Description
elements Object.<string, DSHDLib.Editors.ProjectData.ElementUpdates.ElementUpdate> A map of data to populate based on element_id/element_name matches. element_id can be retrieved via getProjectData (e.g. finding all elements with a matching class name)
debounce bool <optional>
 true A value indicating whether any contained text changes should be debounced before save. When implementing real-time text updates via a complementary form controls (sending text changes "onkeyup"), leverage debouncing automatically to avoid queued up save operations. For single updates disable debounce to save more quickly
skip_user_interaction bool <optional>
 false For changes that might traditionally prompt the user for more input (e.g. positioning a new image masked in a selected vector element or determining whether to trim a newly added video vs expand the scene to match it), supply true here to skip these user interactions
auto_sync_scene_duration bool <optional>
 true When the user is not prompted on newly added videos to either trim or expand the scene (e.g. by using the skip_user_interaction property), if necessary the scene duration will be extended to fully contain the new video. Supply false here to instead retain the scene duration as is
An object containing data to populate into the loaded project
Type:
  • Object

TextAutoFitProperties

Description:
  • Properties for Auto Fit configuration to apply to matched text elements
Source:
Properties:
Name Type Attributes Description
max_font_size number <optional>
 The maximum font size (in pt on print projects and px otherwise) the text should grow to given the max_lines and/or max_height values. If not supplied, will use the existing text's font size prior to the update
min_font_size number <optional>
 The minimum font size (in pt on print projects and px otherwise) the text should strink to given the max_lines and/or max_height values. Note that truncation may occur if/when the minimum is hit and the max_lines and/or max_height have been reached
max_lines number <optional>
 The maximum number of lines the text should wrap to. If not supplied and no max_height supplied, will use the existing text's line count prior to this update
max_height number <optional>
 The maximum height the text should grow to in the unit type of the project. Supply -1 to use the height of the existing text prior to this update
truncation_suffix string <optional>
 If/when truncation of the text occurs, this text is appended to the end of the rendered text (in place of the last characters that would have otherwise shown). Commonly supplied as "..."
Properties for Auto Fit configuration to apply to matched text elements
Type:
  • Object