Skip to main content

useActions

useActions()#

Use 🔧#

A React hook that provides a set of actions that are dispatched to the Builder state.

Signature 🖋️#

const actions: Object = useActions();

Example Usage 🔍#

const ComponentView = ({
id,
...props
}) => {
const editor = useEditor({
id: id,
})
const actions = useActions();
const handleSelect = () => {
actions.timeBatched.triggerListIndexAdd({
id: id,
name: 'selected',
});
editor.handlePanel(event);
}
return <DnDBuilder
onDrop = {editor.handleDrop}
onClick = {handleSelect}
>
<Component {...props} />
</DnDBuilder>
}

Parameters 📥#

This hooks receives no parameters

Return Value 📤#

  • history: Object

An object with history action triggers. (See below for list of history action triggers).

note

Before mentioning the rest of return values we'll take a look at how actions can be performed regarding the builder history.

Let's propose a particular scenario: suppose you have a Text Component an you want to update the text displayed through an input. Depending on your use case, you might want one of the following behaviors regarding the builder history and how undo/redo will work:

  • Letter changes should be batched according to a time limit. So say, every 3 seconds, the action will be batched to history and undoing/redoing will be done in batches. In Build UI we call this a time batched action.

  • Letter changes should be batched as long as the text input is focused. So we will commit whenever the text input is blurred and the undoing/redoing of the change will be done in a single batch. In Build UI we call this an batched action.

  • Every single letter change should be recorded as an individual history batch, so undoing/redoing will be done for every single letter we typed in. In Build UI we call this an unbatched action.

  • The change should not be recorded in history, so it will not be undoable/redoable. In Build UI we call this an unrecorded action.

  • timeBatched: Object

An object with with function properties to execute time batched actions. (See below for list of action triggers).

tip

You can configure time batching behavior through Builder Component's props.

Important Note

By default, all actions supplied by Build UI, such as handlePanel to set the panel, handleDrop to create nodes are time batched.

  • batched: Object

An object with with function properties to execute batched actions. (See below for list of action triggers).

note

You will need to manually flush all batched actions or they will stay in the batch queue until they are committed. Commit with history.triggerCommit().

note

If there is any time batched action timer running, it will be stopped.

  • unbatched: Object

An object with with function properties to execute unbatched actions. (See below for list of action triggers).

note

If there is any time batched timer running, it will be stopped and the batch will be committed along with the batch generated by the action.

  • unrecorded: Object

An object with with function properties to execute unrecorded actions. (See below for list of action triggers).

Be Very Careful!

Only use unrecorded actions when you are certain that no other future actions will depend on the unrecorded action. Example: creating a group of nodes with unrecorded.triggerCreate() and then updating their props. While this may work at first, undoing and redoing will cause errors.

History Actions 🧰#

  • triggerCommit: () => void

Function to commit pending history batches.

note

If there is any time batched action timer running, it will be stopped.

Actions 🧰#

  • triggerCreate: (data: Object) => void
    • data: (targetId: String, node: Tree | Object, position?: int)

Creates a new tree that will be a child of node with id equal to targetId. The tree root id will be added to the child ids array at the specified position, or at the last position if not specified. Position can also be negative to indicate reverse indexes, counted from last position, such as in Array.splice()

note

Click Here for more information on Tree and how to instantiate one.

  • Example Usage:
// Lets suppose we're inside
// a Form View Component.
const handleInsertField = () => {
const field = item({
type: 'TextField'
});
const tree = branch(field);
actions.timeBatched.triggerCreate({
targetId: id,
node: tree,
});
}

  • triggerDelete: (data: Object) => void

    • data: (id: String)

  • Example Usage:

...
// Lets suppose we're inside
// a View Component.
const handleDelete = () => {
actions.timeBatched.triggerDelete({
id: id,
});
}
...

Deletes the node (and all of its children) with the specified id from builder state. It also deletes metadata for node with the specified id and removes all indexes set to id.

  • triggerMove: (data: Object) => void
    • data: (id: String, targetId: String, position?: int)

Moves the node with specified id so that it will be added to the child ids array of targetId. It will be added at the specified position, or at the last position if not specified. Position can also be negative to indicate reverse indexes, counted from last position, such as in Array.splice()

  • Example Usage:
// Lets suppose we're inside
// a View Component.
const handleMove = () => {
actions.timeBatched.triggerMove({
id: id,
targetId: targetId,
// Insert as first
position: 0,
});
}
  • triggerShift: (data: Object) => void
    • data: (id: String, absolute?: int, relative?: int)

Moves the node with specified id among its siblings. If an absolute position is specified, it will shift to that position. If a relative position is specified, it will shift relative to current position. If both are specified, absolute position takes priority. If none are specified, it will shift to last position.

  • Example Usage:
// Lets suppose we're inside
// a View Component.
const handleMoveToBack = () => {
actions.timeBatched.triggerShift({
id: id,
// Send to last position
});
}
const handleMoveOneBack = () => {
actions.timeBatched.triggerShift({
id: id,
// Send to one position
// before
relative: -1,
});
}
  • triggerUpdate: (data: Object) => void
    • data: (id: String, props: Object)

Updates props for node with specified id. Props object will be deep-merged with current props value for node, overriding values if they are found in both objects.

  • Example Usage:
// Lets suppose we're inside
// a View Component.
const handleUpdate = () => {
const props: {
nest_1: {
nest_2: {
nest_3: 10
}
}
};
actions.timeBatched.triggerUpdate({
id: id,
props: props,
});
}
  • triggerRewrite: (data: Object) => void
    • data: (id: String, props: Object)

Rewrites props for node with specified id, so previous value will be overwritten. Props will be deep-set.

  • Example Usage:
// Lets suppose we're inside
// a View Component.
const handleRewrite = () => {
const props: {
nest_1: {
nest_2: {
nest_3: 10
}
}
};
actions.timeBatched.triggerRewrite({
id: id,
props: props,
});
}
Definition
  • Metadata:#
    An object with properties related to a particular node with a given id (similar to props), but that should not be forwarded to the end component. It will be part of the builder state context. It should be used only when some data is used across components related to a particular node. Notice that you should follow React good practices and modularize state.
  • triggerMetaUpdate: (data: Object) => void
    • data: (id: String, meta: Object)

Updates metadata for node with specified id. Meta object will be deep-merged with current metadata for node, overriding values if they are found in both objects.

  • Example Usage:
// Lets suppose we're inside
// a Layer Component.
const handleFix = () => {
const meta = {
fixed: true
};
actions.timeBatched.triggerMetaUpdate({
id: id,
meta: meta,
});
}
Definitions
  • Index: a one-to-one relationship between some named index and a node id.
    • Common use case: Panel.
  • Index List: a one-to-many relationship between some named index and many node ids.
    • Common use case: Multi-Select.
  • triggerIndexAdd: (data: Object) => void
    • data: (id: String, name: String)

Sets the given id as the given named index.

Fun Fact

Remember our handlePanel function from the useEditor hook? It uses index add internally.

  • Example Usage:
// Lets suppose we're inside
// a View Component.
const handlePanel = event => {
actions.timeBatched.triggerIndexAdd({
id: id,
name: 'panel'
});
event.stopPropagation();
}
  • triggerIndexRemove: (data: Object) => void
    • data: (id: String, name: String)

Removes the given id as the given named index, in case it is the current established index relationship.

  • Example Usage:
// Lets suppose we're inside
// a View Component.
const handleRemovePanel = event => {
actions.timeBatched.triggerIndexRemove({
id: id,
name: 'panel'
});
event.stopPropagation();
}
  • triggerIndexToggle: (data: Object) => void
    • data: (id: String, name: String)

Toggles the index value relationship, i.e. if the index is currently related to the passed id, removes it; if it is not, adds it.

  • Example Usage:
// Lets suppose we're inside
// a View Component.
const handleTogglePanel = event => {
actions.timeBatched.triggerIndexToggle({
id: id,
name: 'panel'
});
event.stopPropagation();
}
  • triggerIndexClear: (data: Object) => void
    • data: (name: String)

Clears the index relationship, so no id will be related to that named index after the call.

  • Example Usage:
// Lets suppose we're inside
// a View Component.
const handleClearPanel = event => {
actions.timeBatched.triggerIndexClear({
name: 'panel'
});
event.stopPropagation();
}
  • triggerListIndexAdd: (data: Object) => void
    • data: (id: String, name: String)

Adds the given id to the given named list index.

(See triggerIndexAdd() for analogue example usage)

  • triggerListIndexRemove: (data: Object) => void
    • data: (id: String, name: String)

Removes the given id from the given named list index.

(See triggerIndexRemove() for analogue example usage)

  • triggerListIndexToggle: (data: Object) => void
    • data: (id: String, name: String)

Toggles the list index value relationship, i.e. if the list index contains the passed id, it removes it; if it is not, it adds it.

(See triggerIndexToggle() for analogue example usage)

  • triggerListIndexClear: (data: Object) => void
    • data: (name: String)

Clears thelist index relationship, so no id will be related to that named list index after the call.

(See triggerIndexClear() for analogue example usage)

Edit this page