Class: FrameStepHandle
A StepHandle allows for managing the state of a specific step in a workflow. This class abstracts away the complexities of dealing with a step directly and allows for using high level concepts instead of dealing with the underlying data structures.
Extends
Constructors
Constructor
new FrameStepHandle(
manager,step,tags):FrameStepHandle
Parameters
manager
step
tags
string[]
Returns
FrameStepHandle
Overrides
Properties
frameService
frameService:
FrameService
Methods
canRemoveBackground()
canRemoveBackground():
Promise<boolean>
Returns true if the Background Remover is available for the current session and if the associated frame has a user-supplied raster image.
Returns
Promise<boolean>
canUseAdvancedImageManipulation()
canUseAdvancedImageManipulation():
Promise<boolean>
Returns true if the Advanced Image Manipulation addon is available for the current session.
Returns
Promise<boolean>
changeColors()
changeColors(
newFills):Promise<void>
Updates the colors on the currently displayed image. Only applicable to an SVG image with identifiable colors or a raster image with the color picker enabled.
Parameters
newFills
Map<string, ColorDefinition>
Returns
Promise<void>
A promise that resolves when the colors have been updated on the image.
enhanceWithAI()
enhanceWithAI(
asset?,options?):Promise<Asset>
Takes an asset and enhances it using AI, stores the new asset in the state, and returns the new asset.
Parameters
asset?
An optional asset to use for enhancement. If not supplied, the method will attempt to enhance the current image selection. If there is no current image selection, the method will throw an error.
options?
Optional enhancement options including quality, dimensions, and AI parameters.
additionalInstructions?
string
cfgScale?
number
negativePrompt?
string
quality?
string
seed?
number
targetHeight?
number
targetWidth?
number
Returns
Promise<Asset>
The newly enhanced asset.
executeAnimations()
executeAnimations(
immediate?):void
Fires any configured animations on the 3D preview for this step. This includes camera & model animations. If the preview is unavailable this function will do nothing.
Parameters
immediate?
boolean
Returns
void
Inherited from
getAllVariants()
getAllVariants():
Promise<Variant[]>
Returns
Promise<Variant[]>
A list of all variants for this step, including disabled ones.
Inherited from
getAvailableColors()
getAvailableColors():
Promise<ColorOption[]>
Returns
Promise<ColorOption[]>
A list of available colors for the current image selection, if the color picker is enabled. If the color picker is not enabled, returns an empty array.
getAvailableVariants()
getAvailableVariants():
Promise<Variant[]>
Returns
Promise<Variant[]>
A list of valid variants for this step. Does not include disabled variants.
Inherited from
StepHandle.getAvailableVariants
getBackgroundRemovedImageSelection()
getBackgroundRemovedImageSelection():
Promise<Asset|undefined>
Returns
Promise<Asset | undefined>
The asset representing the image with its background removed. If there is no such image, returns undefined.
getColorOption()
getColorOption():
Promise<OptionResource|undefined>
Returns
Promise<OptionResource | undefined>
The ColorOption associated with this step, which includes information about whether the color picker is enabled and any predefined colors. Returns undefined if there is no ColorOption associated with this step.
getCurrentFrameStep()
getCurrentFrameStep(
frameData,uploading?,imageUploadComplete?,variants?):FrameStep
Parameters
frameData
FrameData
uploading?
any
imageUploadComplete?
any
variants?
Returns
getCurrentImageState()
getCurrentImageState():
ImageState
Returns
The current image state being displayed (original, backgroundRemoved, or optimized).
getCurrentVariant()
getCurrentVariant():
Variant|undefined
Gets the currently selected variant, or undefined if no variant is selected.
Returns
Variant | undefined
Inherited from
getEnhancedImageSelection()
getEnhancedImageSelection():
Promise<Asset|undefined>
Returns
Promise<Asset | undefined>
The asset representing the AI-enhanced version of the image. If there is no such image, returns undefined.
getFrameService()
getFrameService():
FrameService|undefined
Returns
FrameService | undefined
getGlobalPropertyAspects()
getGlobalPropertyAspects(
configurationId):string[]
Retrieves the identifiers of all of the configured aspects for the specified Global Property Configuration.
Parameters
configurationId
string
The ID of the Global Property Configuration. You can usually find this with bundle.getGlobalPropertyConfiguration()?.id
Returns
string[]
An array of strings matching the keys of all the Global Property Aspects in the Configuration that this step is configured to use.
Inherited from
StepHandle.getGlobalPropertyAspects
getHelpText()
getHelpText():
string|undefined
Returns
string | undefined
A message that can accompany the step name in UI components. Used to describe the purpose of the step in more detail.
Inherited from
getId()
getId():
string
Returns
string
A unique identifier for this step within the workflow.
Inherited from
getImageData()
getImageData():
PatternImageData|undefined
Returns
PatternImageData | undefined
The PatternImageData for the current frame, which includes information about the image currently in the frame such as whether it's an SVG or raster image, its dimensions, and its colors (if applicable). Returns undefined if there is no image currently in the frame or if the frameService is not initialized.
getMandatory()
getMandatory():
boolean
Returns
boolean
True if the step is required to be filled by the customer. False otherwise.
Inherited from
getMaxAllowedColors()
getMaxAllowedColors():
number|undefined
Returns
number | undefined
The maximum number of colors allowed in the image selection.
getMinimumPixelThresholdForOptimization()
getMinimumPixelThresholdForOptimization():
number|undefined
Returns
number | undefined
The minimum number of pixels in either dimension of the image required for optimization pathway to be suggested.
getName()
getName():
string
Returns
string
The name of the step
Inherited from
getOriginalImageColors()
getOriginalImageColors():
Promise<{[key:string]:ColorDefinition; } |undefined>
Returns
Promise<{[key: string]: ColorDefinition; } | undefined>
A mapping of color identifiers to their corresponding ColorDefinition for the original image. Only applicable if the current image is an SVG with identifiable colors. Returns undefined if there is no image or if the image is not an SVG with identifiable colors.
getOriginalImageSelection()
getOriginalImageSelection():
Promise<Asset|undefined>
Returns
Promise<Asset | undefined>
getOverrideGlobalPropertyConfiguration()
getOverrideGlobalPropertyConfiguration(
type):boolean
Parameters
type
The AspectType to fetch the value for.
Returns
boolean
A boolean indicating whether this step should override Global Properties. Only relevant when the Workflow Experience is associated with a Bundle that is using Global Properties, and when this step is associated with one or more Global Property Aspects.
Inherited from
StepHandle.getOverrideGlobalPropertyConfiguration
getRaw()
getRaw():
Step<FrameStepData>
Returns
The underlying data for this step. Favor using the step handle methods instead of this.
Inherited from
getShouldVectorize()
getShouldVectorize():
boolean
Returns
boolean
True when vectorizing should be available to the user.
getTags()
getTags():
string[]
Returns
string[]
Returns all of the tags that are present on this step.
Inherited from
getType()
getType():
StepType
Returns
The type of the step handle.
Inherited from
getUniqueColorCount()
getUniqueColorCount():
number
Returns
number
The number of unique colors present in the image. Only applicable to SVG files.
getUseOriginalImageSelection()
getUseOriginalImageSelection():
boolean
Returns
boolean
Deprecated
Use getCurrentImageState() instead. Returns true if displaying original image, false otherwise.
getVectorizedImageSelection()
getVectorizedImageSelection():
Promise<Asset|undefined>
Returns
Promise<Asset | undefined>
The asset representing the vectorized version of the image. If there is no such image, returns undefined.
getVectorizeMaxColors()
getVectorizeMaxColors():
number|undefined
Returns
number | undefined
The maximum number of colors allowed when vectorizing an image. Only applicable if shouldVectorize is true. If not specified, a suitable default will be applied.
getWhitelistedExtensions()
getWhitelistedExtensions():
string[]
Returns
string[]
hasBackgroundRemovedImageSelection()
hasBackgroundRemovedImageSelection():
boolean
Returns
boolean
True when a background removed version of the original image exists in the state, regardless of whether it is currently applied as the image selection or not.
hasEnhancedImageSelection()
hasEnhancedImageSelection():
boolean
Returns
boolean
True when an AI-enhanced version of the original image exists in the state, regardless of whether it is currently applied as the image selection or not.
hasOriginalImageSelection()
hasOriginalImageSelection():
boolean
Returns
boolean
Returns true when an initial asset upload was received from the user.
hasOverlayImageKey()
hasOverlayImageKey():
string|undefined
Returns
string | undefined
hasOverlayImageUrl()
hasOverlayImageUrl():
any
Returns
any
hasTag()
hasTag(
tag):boolean
Parameters
tag
string
The tag to check for.
Returns
boolean
True if the step has the specified tag, false otherwise.
Inherited from
hasVectorizedImageSelection()
hasVectorizedImageSelection():
boolean
Returns
boolean
True when a vectorized version of the original image exists in the state, regardless of whether it is currently applied as the image selection or not.
isColorPickerEnabled()
isColorPickerEnabled():
boolean
Returns
boolean
True if the color picker is enabled for this step, otherwise false.
isVariantCategoriesEnabled()
isVariantCategoriesEnabled():
boolean
Returns
boolean
mergeColors()
mergeColors(
sourceClassIds,targetClassId,targetColor):Promise<void>
Merges multiple color class IDs into a single unified color. This is useful for consolidating near-identical colors in vectorized SVGs.
Parameters
sourceClassIds
string[]
Array of color class IDs to merge from (e.g., ["ff0000", "fe0101", "ff0a0a"])
targetClassId
string
The color class ID to merge into (e.g., "ff0000")
targetColor
The color definition for the merged result
Returns
Promise<void>
Throws
Error if the current image is not an SVG with colors
onFrameDataChanged()
onFrameDataChanged(
callback):void
Parameters
callback
(frameData) => void
Returns
void
removeBackgroundFromImageSelection()
removeBackgroundFromImageSelection(
applyNewAsset?):Promise<Asset>
Removes the background from an image, stores it in the state, and returns the new asset.
Parameters
applyNewAsset?
boolean = true
Optionally applies the new asset as the current image selection. Default: true.
Returns
Promise<Asset>
A promise that resolves with the newly generated Asset.
selectImage()
selectImage(
asset,storeAsOriginal?,recalculateOffsets?):Promise<void>
Updates the image selection inside the frame.
Parameters
asset
The asset to use.
storeAsOriginal?
boolean = true
Optional: Store this asset as the original, unmodified version of the image. Default: true.
recalculateOffsets?
boolean = true
Optional: Recalculates the offsets of the image inside the frame. Default: true.
Returns
Promise<void>
selectVariant()
selectVariant(
variant):Promise<void>
Most step types have a base option type that variants can be selected for. Selects a specific variant for this step. This will execute all required changes to the design and update the metadata to include the new selection. Any conditions that would be triggered will also be executed.
Parameters
variant
Returns
Promise<void>
Overrides
setImageState()
setImageState(
state):Promise<void>
Sets the current image state to display one of: original, backgroundRemoved, or optimized. This will switch between the available image versions without creating new ones.
Parameters
state
The image state to switch to.
Returns
Promise<void>
Throws
Error if the requested state is not available (e.g., trying to switch to backgroundRemoved when no background-removed version exists).
setOverrideGlobalPropertyConfiguration()
setOverrideGlobalPropertyConfiguration(
type,value):void
Sets whether or not this step should override Global Properties. Only relevant when the Workflow Experience is associated with a Bundle that is using Global Properties, and when this step is associated with one or more Global Property Aspects.
Parameters
type
The AspectType to override.
value
boolean
Returns
void
Inherited from
StepHandle.setOverrideGlobalPropertyConfiguration
setUseOriginalImageSelection()
setUseOriginalImageSelection(
value):Promise<void>
Parameters
value
boolean
Returns
Promise<void>
Deprecated
Use setImageState() instead. Sets whether to use original (true) or background-removed (false) image.
unmergeColors()
unmergeColors(
sourceClassIds,targetClassId,preMergeColors,preMergeSvg):Promise<void>
Unmerges colors by restoring the pre-merge color state and SVG
Parameters
sourceClassIds
string[]
Original class IDs that were merged
targetClassId
string
The class ID they were merged into
preMergeColors
{[key: string]: ColorDefinition; }
The color definitions before the merge
preMergeSvg
string
The SVG string before the merge
Returns
Promise<void>
Throws
Error if the current image is not an SVG with colors
vectorize()
vectorize(
asset?,maxColors?):Promise<Asset>
Takes an asset and vectorizes it, stores the new asset in the state, and returns the new asset.
Parameters
asset?
An optional asset to use for vectorization. If not supplied, the method will attempt to vectorize the current image selection. If there is no current image selection, the method will throw an error.
maxColors?
number | undefined = undefined
Returns
Promise<Asset>
The newly vectorized asset.