ExtensionsBeta

Topics

An interface for retrieving and managing topics.

Hooks

Hooks provide access to topics and related data from inside React components. Unlike data accessed using static methods, hooks will cause the component to rerender when the data changes.

useTopic

Returns a topic by ID or null if no topic was found.

useTopic(topicId: string): Topic | null

Argument	Type	Description
`topicId*`	`string`	The ID of the topic to retrieve.

useTopics

Returns a TopicMap of topics matching the provided IDs. Returned topics can be filtered by passing in TopicFilters.

useTopics(topicIds: string[], filters?: TopicFilters): TopicMap

Argument	Type	Description
`topicIds`	`string[]`	The IDs of the topics to retrieve.
`filters`	`TopicFilters`	Allows filtering of returned topics. See the TopicFilters section for more details.

useAllTopics

Returns a TopicMap map of all topics. Returned topics can be filtered by passing in TopicFilters.

useAllTopics(filters?: TopicFilters): TopicMap

Argument	Type	Description
`filters`	`TopicFilters`	Allows filtering of returned topics. See the TopicFilters section for more details.

useTopicParents

Returns an { [id]: Topic } map of a given topic's parents. The results can be filtered by passing in `TopicFilters``.

useTopicParents(topicId: string, filters?: TopicFilters): TopicMap

Argument	Type	Description
`topicId*`	`string`	The ID of the topic for which to retrieve the parents.
`filters`	`TopicFilters`	Allows filtering of returned topics. See the TopicFilters section for more details.

Retrieves topics by ID. If provided a single ID string, returns the topic. If provided an array of IDs, returns a TopicMap of the corresponding topics. Returned topics can be filtered by passing in TopicFilters. Filtering is not supported when getting a single topic.

Throws a TopicNotFoundError if one or more of the requested topics does not exist.

Topics.get(topicId: string | string[], filters?: TopicFilters): Topic | TopicMap

Argument	Type	Description
`topicId*`	`string \| string[]`	The ID(s) of the topic(s) to retrieve.
`filters`	`TopicFilters`	Allows filtering of returned topics. See the TopicFilters section for more details.

getAll

Retrieves all topics, returning a TopicMap. Returned topics can be filtered by passing in TopicFilters.

Topics.getAll(filters?: TopicFilters): Topic | TopicMap

Argument	Type	Description
`filters`	`TopicFilters`	Allows filtering of returned topics. See the TopicFilters section for more details.

getDropParentTopics

Retrieves a drop's parent topics returned as a TopicMap. Returned topics can be filtered by passing in TopicFilters.

Topics.getDropParentTopics(topicId: string, filters?: TopicFilters): TopicMap

Argument	Type	Description
`topicId*`	`string`	The ID of the drop for which to retrieve the parent topics.
`filters`	`TopicFilters`	Allows filtering of returned topics. See the TopicFilters section for more details.

filter

Filters topics according to provided filters.

Topics.filter(topics: TopicMap, filters: TopicFilters): TopicMap

Argument	Type	Description
`topics`	`TopicMap`	The topics to filter.
`filters`	`TopicFilters`	Filtering options. See the TopicFilters section for more details.

isDescendant

Checks whether a topic is a descendant of other topics. A descendant topic can be nested multiple levels deep inside the parent topic.

Topics.isDescendant(descendantTopicId: string, parentTopicIds: string[]): boolean

Argument	Type	Description
`descendantTopicId*`	`string`	The ID of the topic which may be a descendant.
`parentTopicIds*`	`string`	The IDs of the topics which may be a parent.

create

Creates a new topic and dispatches a topics:create event. Returns the new topic.

Topics.create(core: Core, data?: CreateTopicData): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`data`	`CreateTopicData`	The default topic property values. See below for details.

`CreateTopicData`

Property	Type	Description
`title`	`string`	The topic title.
`hidden`	`true`	If set, the topic will be created as a hidden topic.

update

Updates a topic and dispatches a topics:update event. Returns the updated topic.

Topics.update(core: Core, topicId: string, data: UpdateTopicData): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic to update.
`data*`	`UpdateTopicData`	The changes to apply to the topic. See below for details.

`UpdateTopicData`

Property	Type	Description
`title`	`string`	The topic title.

delete

Deletes a topic and dispatches a topics:delete event and a topics:update event. Returns the deleted topic.

Deleted topics are not removed from the store but instead marked as deleted using deleted: true and deletedAt: Date properties. Deleted topics can be restored using the Topics.restore method. To permanently delete a topic and remove it from the store, use Topics.deletePermanently.

Topics.delete(core: Core, topicId: string): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic to delete.

restore

Restores a deleted topic and dispatches a topics:restore event and a topics:update event. Returns the restored topic.

Topics.restore(core: Core, topicId: string): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic to restore.

deletePermanently

Permanently deletes a topic and all of its view instances and dispatches a topics:delete-permanently event. The topic is also removed as a parent from its drops and subtopics. Returns the deleted topic.

Permanently deleted topics cannot be restored.

Topics.deletePermanently(core: Core, topicId: string): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic to delete.

addSubtopics

Adds subtopics into a parent topic. Dispatches an topics:topic:add-subtopics event, as well as topics:topic:update event. Returns the updated topic.

Topics.addSubtopics(
  core: Core,
  topicId: string,
  subtopicIds: string[],
  position?: number,
): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the parent topic into which to add the subtopic.
`subtopicIds*`	`string[]`	The IDs of the subtopics.
`position`	`number`	The index at which to add the subtopics.

removeSubtopics

Removes subtopics from a topic. Dispatches a topics:remove-subtopics event as well as topics:update event. Returns the updated topic.

Topics.removeSubtopics(core: Core, parentId: string, subtopicIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`parentId*`	`string`	The ID of the parent topic from which to remove the subtopics.
`subtopicIds*`	`string[]`	The IDs of the subtopics to remove.

moveSubtopics

Moves subtopics from one topic to another and dispaches a topics:topic:move-subtopics event.

Topics.moveSubtopics(
  core: Core,
  fromTopicId: string,
  toTopicId: string,
  subtopicIds: string[],
  position?: number
): void

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`fromTopicId*`	`string`	The ID of the parent topic from which to remove the subtopics.
`toTopicId*`	`string`	The ID of the parent topic into which to add the subtopics.
`subtopicIds*`	`string[]`	The IDs of the subtopics to move.
`position`	`number`	The index at which to add the moved subtopics.

sortSubtopics

Sets a new sort order for a topic's subtopics. The provided subtopic IDs must contain the same IDs as the current value, only in a different order. Dispatches a topics:topic:sort-subtopics event. Returns the updated topic.

Throws a InvalidParameterError if the given subtopic IDs differ from the current subtopic IDs in anything but order.

Topics.sortSubtopics(core: Core, topicId: string, subtopicIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The IDs of the topic in which to sort the subtopics.
`subtopicIds*`	`string[]`	The IDs of the subtopics in their new sort order.

archiveSubtopics

Archives subtopics in a topic and dispatches a topics:archive-subtopics event as well as a topics:update event. Returns the updated topic.

Topics.archiveSubtopics(core: Core, topicId: string, subtopicIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic in which to archive the subtopics.
`subtopicIds*`	`string[]`	The IDs of the subtopics to archive.

unarchiveSubtopics

Unarchives subtopics in a topic and dispatches a topics:unarchive-subtopics event as well as a topics:update event. Returns the updated topic.

Topics.archiveSubtopics(core: Core, topicId: string, subtopicIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic in which to unarchive the subtopics.
`subtopicIds*`	`string[]`	The IDs of the subtopics to unarchive.

addDrops

Adds drops to a topic, dispaches an topics:add-drops event and a topics:update event. Returns the updated topic.

Topics.addDrops(core: Core, topicId: string, dropIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic to which to add the drop.
`dropIds*`	`string[]`	The IDs of the drops to add.
`metadata`	`AddDropsMetadata`	Optional metadata about the event added by the topic view instance that triggered the event. See the `TopicView` interface for details.

moveDrops

Moves drops from one topic to another by removing them from the source topic and adding them to the destination topic. Dispatches a topics:move-drops event.

Topics.moveDrops(core: Core, fromTopicId: string, toTopicId: string, dropIds: string[], metadata: AddDropsMetadata): void

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`fromTopicId*`	`string`	The ID of the source topic from which to move the drops.
`toTopicId*`	`string`	The ID of the target topic into which to move the drops.
`dropIds*`	`string[]`	The IDs of the drops to move.
`metadata`	`AddDropsMetadata`	Optional metadata about the event added by the topic view instance that triggered the move. See the `TopicView` interface for details.

archiveDrops

Archives drops in a topic and dispatches a topics:archive-drops event as well as a topics:update event. Returns the updated topic.

Topics.archiveDrops(core: Core, topicId: string, dropIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic in which to archive the drops.
`dropIds*`	`string[]`	The IDs of the drops to archive.

unarchiveDrops

Unarchives drops in a topic and dispatches a topics:unarchive-drops event as well as a topics:update event. Returns the updated topic.

Topics.archiveDrops(core: Core, topicId: string, dropIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic in which to unarchive the drops.
`dropIds*`	`string[]`	The IDs of the drops to unarchive.

removeDrops

Removes drops from a topic and dispatches a topics:remove-drops event as well as a topics:update event. Returns the updated topic.

Topics.removeDrops(core: Core, topicId: string, dropIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic from which to remove the drops.
`dropIds*`	`string[]`	The IDs of the drops to remove.

addParents

Adds parent references to a topic and dispatches a topics:add-parents event and a topics:update event. Returns the updated topic.

Topics.addParents(core: Core, topicId: string, parentReferences: TopicParentReference[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic to which to add the parents.
`parentReferences*`	`TopicParentReference[]`	The parent references to add to the topic. See the `TopicParentReference` interface for details.

removeParents

Remove parent references from a topic and dispatches a topics:remove-parents event and a topics:update event. Returns the updated topic.

Topics.removeParents(core: Core, topicId: string, parentReferences: TopicParentReference[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic from which to remove the parents.
`parentReferences*`	`TopicParentReference[]`	The parent references to remove from the topic. See the `TopicParentReference` interface for details.

getParents

Returns an { [id]: Topic } map of a given topic's parents. The results can be filtered by passing in `TopicFilters``.

Topics.getParents(topicId: string, filters?: TopicFilters): TopicMap

Argument	Type	Description
`topicId*`	`string`	The ID of the topic for which to retrieve the parents.
`filters`	`TopicFilters`	Allows filtering of returned topics. See the TopicFilters section for more details.

addTags

Adds tags to a topic, dispaches an topics:add-tags event and a topics:update event. Returns the updated topic.

Topics.addTags(core: Core, topicId: string, tagIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic to which to add the tags.
`tagIds*`	`string[]`	The IDs of the tags to add.

removeTags

Removes tags from a topic and dispatches a topics:remove-tags event as well as a topics:update event. Returns the updated topic.

Topics.removesTags(core: Core, topicId: string, tagIds: string[]): Topic

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic from which to remove the tags.
`tagIds*`	`string[]`	The IDs of the tags to remove.

registerView

Registers a TopicView and dispaches a topics:register-view event. Registering a topic view allows the user to create instances of the view within topics. This method registers the view with the Views API (using Views.register) internally, so you do not need to do so yourself.

Topics.registerView(core: Core, view: TopicViewConfig): void

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`view*`	`TopicViewConfig`	The view to register. See the `TopicViewConfig` interface for details.

unregisterView

Unregisters a TopicView and dispaches a topics:unregister-view event. This method unregisters the view with the Views API (using Views.unregister) internally, so you do not need to do so yourself.

Topics.unregisterView(core: Core, viewId: string): void;

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`viewId*`	`string`	The ID of the view to unregister.

getView

Returns a TopicView by ID. Throws a TopicViewNotRegisteredError if the topic view is not registered.

Topics.getView(topicViewId: string): TopicView

Argument	Type	Description
`topicViewId*`	`string`	The ID of the topic view to retrieve.

getViews

Returns a { [id]: TopicView } map of all registered topic views.

Topics.getView(): TopicViewMap

createViewInstance

Creates a new instance of a TopicView and adds it to the topic. The topic view must first be registered using Topics.registerView or else a TopicViewNotRegisteredError will be thrown. Returns the new view instance and dispatches a topics:create-view-instance event.

Topics.createViewInstance(core: Core, topicId: string, topicViewId: string): ViewInstance;

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicId*`	`string`	The ID of the topic into which to add the view.
`topicViewId*`	`string`	The ID of the topic view for which to create a new instance.

deleteViewInstance

Deletes a topic view instance and removes it from the topic. Returns the deleted view instance and dispatches a topics:delete-view-instance event.

Topics.deleteViewInstance(core: Core, topicViewId: string): ViewInstance

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topicViewId*`	`string`	The ID of the topic view to delete.

load

Loads topics into the store and dispatches a topics:load event.

Topics.load(core: Core, topics: Topic[]): void

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`topics*`	`Topic[]`	The topics to load into the store.

clear

Clears the topics store and dispatches a topics:clear event.

Topics.clear(core: Core): void

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.

addEventListener

Adds topic specific event listeners. Equivalent to calling addEventListener directly on core, but provides more advanced type definitions.

Topics.addEventListener(core: Core, event: TopicEvent, callback: EventListenerCallback): void

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`event*`	`TopicEvent`	The event type to listen for. See the topic events section below for available events.
`callback*`	`EventListenerCallback`	The callback fired when the event occurs. See the topic events section below for the data passed to the callback.

removeEventListener

Removes topic specific event listeners. Equivalent to calling removeEventListener directly on core, but provides more advanced type definitions.

Topics.removeEventListener(core: Core, event: TopicEvent, callback: EventListenerCallback): void

Argument	Type	Description
`core*`	`Core`	A MindDrop core instance.
`event*`	`TopicEvent`	The event type for which to remove the event listener.
`callback*`	`EventListenerCallback`	The callback of the event listener to remove.

Topic events

Topic events are prefixed with the namespace topics.

See below the table for more details on the data passed by topic related events.

Name	Data	Description
`topics:create`	`Topic`	Dispatched when a topic is created.
`topics:update`	`UpdateTopicEventData`	Dispatched when a topic is updated.
`topics:delete`	`Topic`	Dispatched when a topic is deleted.
`topics:restore`	`Topic`	Dispatched when a archived/deleted topic is restored.
`topics:delete-permanently`	`Topic`	Dispatched when a topic is permanently deleted.
`topics:add-subtopics`	`AddSubtopicsEventData`	Dispatched when subtopics are added to a topic.
`topics:remove-subtopics`	`RemoveSubtopicsEventData`	Dispatched when subtopics are removed from a topic.
`topics:move-subtopics`	`MoveSubtopicsEventData`	Dispatched when subtopics are moved from one topic to another.
`topics:archive-subtopics`	`ArchiveSubtopicsEventData`	Dispatched when subtopics are archived inside a topic.
`topics:unarchive-subtopics`	`UnarchiveSubtopicsEventData`	Dispatched when subtopics are unarchived inside a topic.
`topics:add-drops`	`AddDropsEventData`	Dispatched when drops are added to a topic.
`topics:remove-drops`	`RemoveDropsEventData`	Dispatched when drops are removed from a topic.
`topics:move-drops`	`MoveDropsEventData`	Dispatched when drops are moved from one topic to another.
`topics:archive-drops`	`ArchiveDropsEventData`	Dispatched when drops inside a topic are archived.
`topics:unarchive-drops`	`UnarchiveDropsEventData`	Dispatched when drops inside a topic are unarchived.
`topics:add-parents`	`AddParentsEventData`	Dispatched when parents are added to a topic.
`topics:remove-parents`	`RemoveParentsEventData`	Dispatched when parents are removed from a topic.
`topics:add-tags`	`AddTagsEventData`	Dispatched when tags are added to a topic.
`topics:remove-tags`	`RemoveTagsEventData`	Dispatched when tags are removed from a topic.
`topics:register-view`	`TopicView`	Dispatched when a topic view is registered.
`topics:unregister-view`	`TopicView`	Dispatched when a topic view is unregistered.
`topics:create-view-intance`	`TopicViewInstance`	Dispatched when a new topic view instance is created.
`topics:delete-view-intance`	`TopicViewInstance`	Dispatched when a topic view instance is deleted.
`topics:load`	`Topic[]`	Dispatched when topics are loaded into the store.
`topics:clear`	No data	Dispatched when the topics store is cleared.

Topic event data types

Topic events are dispatched with one of the following types of data.

Topic

See the Topic interface page.

UpdateTopicEventData

Property	Type	Description
`before*`	`Topic`	Topic data before it was changed.
`after*`	`Topic`	Updated topic data.
`changes*`	`TopicChanges`	The changes made to the topic. See below for details.

TopicChanges

Property	Type	Description
`updatedAt*`	`Date`	The timestamp at which the topic was updated.
`title`	`string`	The topic title.
`parents`	`\| TopicParentReference[] \| ArrayUnion \| ArrayFilter`	The references of the topic's parents.
`subtopics`	`string[]`	The IDs of the topics inside the topic.
`drops`	`string[]`	The IDs of the drops inside the topic.
`tags`	`string[]`	IDs of the tags belonging to the topic.
`deleted`	`boolean \| Delete`	If `true` the topic is deleted.
`deletedAt`	`Date \| Delete`	Timestamp at which the topic was deleted.
`hidden`	`true \| Delete`	If `true`, the topic is hidden.

AddSubtopicsEventData

Property	Type	Description
`topic*`	`Topic`	The topic to which the subtopics were added.
`subtopics*`	`TopicMap`	The subtopics added to the topic.

RemoveSubtopicsEventData

Property	Type	Description
`topic*`	`Topic`	The topic from which the subtopics were removed.
`subtopics*`	`TopicMap`	The subtopics which were removed from the topic.

MoveSubtopicsEventData

Property	Type	Description
`fromTopic*`	`Topic`	The topic from which the subtopics were removed.
`toTopic*`	`Topic`	The topic to which the subtopics were added.
`subtopics*`	`TopicMap`	The subtopics which were moved.

ArchiveSubtopicsEventData

Property	Type	Description
`topic*`	`Topic`	The topic inside which the subtopics were archived.
`subtopics*`	`TopicMap`	The archived subtopics.

UnarchiveSubtopicsEventData

Property	Type	Description
`topic*`	`Topic`	The topic inside which the subtopics were unarchived.
`subtopics*`	`TopicMap`	The unarchived subtopics.

AddDropsEventData

Property	Type	Description
`topic*`	`Topic`	The topic to which the drops were added.
`drops*`	`DropMap`	The drops which were added to the topic.

ArchiveDropsEventData

Property	Type	Description
`topic*`	`Topic`	The topic in which the drops were archived.
`drops*`	`DropMap`	The drops which were archived.

UnarchiveDropsEventData

Property	Type	Description
`topic*`	`Topic`	The topic in which the drops were unarchived.
`drops*`	`DropMap`	The drops which were unarchived.

RemoveDropsEventData

Property	Type	Description
`topic*`	`Topic`	The topic from which the drops were removed.
`drops*`	`DropMap`	The drops which were removed from the topic.

MoveDropsEventData

Property	Type	Description
`fromTopic*`	`Topic`	The topic from which the drops were removed.
`toTopic*`	`Topic`	The topic to which the drops were added.
`drops*`	`DropMap`	The drops which were moved.

AddParentsEventData

Property	Type	Description
`topic*`	`Topic`	The topic to which the parents were added.
`parents*`	`TopicParentReference[]`	The references of the parents which were added to the topic.

RemoveParentsEventData

Property	Type	Description
`topic*`	`Topic`	The topic from which the parents were removed.
`parents*`	`TopicParentReference[]`	The references of the parents which were removed from the topic.

AddTagsEventData

Property	Type	Description
`topic*`	`Topic`	The topic to which the tags were added.
`tags*`	`TagMap`	The tags which were added to the topic.

RemoveTagsEventData

Property	Type	Description
`topic*`	`Topic`	The topic from which the tags were removed.
`tags*`	`TagMap`	The tags which were removed from the topic.

TopicFilters

Topics can be filtered using one or more of the options below.

By default, deleted topics are filtered out. If deleted is set to true, active topics will be filtered out by default unless active is also set to true.

A topic is considered active if it is not deleted.

Prop	Type	Default
`active`	`boolean`	`true`
`deleted`	`boolean`	`false`

Theme

Utils

Edit this page on GitHub.

Getting Started

API

Types