https://github.com/xmindltd/xmind-sdk-js
This is a lightweight official software development kit to help people who wants to build the mapping file without the UI client and It's also supported to run in Browser or Node.js.
https://github.com/xmindltd/xmind-sdk-js
mindmap mindmapping sdk xmind xmind-sdk xmind-sdk-js xmind-sdk-ts
Last synced: 27 days ago
JSON representation
This is a lightweight official software development kit to help people who wants to build the mapping file without the UI client and It's also supported to run in Browser or Node.js.
- Host: GitHub
- URL: https://github.com/xmindltd/xmind-sdk-js
- Owner: xmindltd
- License: mit
- Created: 2019-05-29T02:16:03.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-10-11T18:33:45.000Z (7 months ago)
- Last Synced: 2024-10-28T21:42:19.387Z (7 months ago)
- Topics: mindmap, mindmapping, sdk, xmind, xmind-sdk, xmind-sdk-js, xmind-sdk-ts
- Language: TypeScript
- Homepage: https://xmind.app
- Size: 1.49 MB
- Stars: 444
- Watchers: 15
- Forks: 61
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📦 📦 📦 
[](https://github.com/xmindltd/xmind-sdk-js/actions/workflows/codeql.yml)
[](https://ci.appveyor.com/project/danielsss/xmind-sdk-js/branch/master)
[](https://www.codacy.com/gh/xmindltd/xmind-sdk-js/dashboard?utm_source=github.com&utm_medium=referral&utm_content=xmindltd/xmind-sdk-js&utm_campaign=Badge_Grade)
[](https://xmind.app)
This project is a lightweight official software development kit for JavaScript/Typescript which is available for browsers and Node.js.
This library implements various functions which are similar to our UI applications, and You might know the basic concepts of this library if you've used the application before.
In order to use it conveniently, an essential concept you should know is that everything is a component and each one of them has a unique component ID. You can add a child node under the components, however, the Markers and Notes can only be attached to the components.
Eventually, Our UI apps could be used to open the `*.xmind` file generated by this tool.
## Recommendations
* [Xmind AI](https://xmind.works) - It's a lightweight online `Mind-Map` tool comes with AI features which helps you to build everything you wanted.
* [Xmind-generator](https://github.com/xmindltd/xmind-generator) — If you are looking for a tool specifically designed for `Mind-Map` generation, `Xmind Generator` is an official package that prioritizes this functionality, featuring a modern and lightweight API.
## Supported Platforms
* Linux
* Win32
* Browser (Not Fully Supported)
## Usage and Getting Started
### Node.js
```shell
$ npm i --save xmind
```
> NOTICE: The `xmind-sdk` is renamed to `xmind` from the version: 2.0.0
>
> Please, use `npm i --save xmind` to replace with it if you were using the `xmind-sdk`.
```js
const { Workbook, Topic, Marker } = require('xmind');
```
### Browser or Vue.js
```jsx harmony
import { Workbook, Topic, Marker } from 'xmind';
```
```html
// HTML
// Latest version
// Specify version
const { Workbook, Topic, Marker } = window;
```
### More Examples
See [example directory](./example).
```js
const { Workbook, Topic, Marker, Zipper } = require('xmind');
const [ workbook, marker ] = [new Workbook(), new Marker()];
const topic = new Topic({sheet: workbook.createSheet('sheet title', 'Central Topic')});
const zipper = new Zipper({path: '/tmp', workbook, filename: 'MyFirstMap'});
// topic.on() default: `central topic`
topic.add({title: 'main topic 1'});
topic
.on(topic.cid(/*In default, the componentId is last element*/))
// add subtopics under `main topic 1`
.add({title: 'subtopic 1'})
.add({title: 'subtopic 2'})
// attach text note to `main topic 1`
.note('This is a note attached on main topic 1')
// attach a marker flag to `subtopic 1`
.on(topic.cid('subtopic 1'))
.marker(marker.week('fri'))
// add a component of the summary that contains two sub topics
.summary({title: 'subtopic summary', edge: topic.cid('subtopic 2')})
zipper.save().then(status => status && console.log('Saved /tmp/MyFirstMap.xmind'));
```
## Workbook
The workbook is a temporary storage where all the data are written.
### Methods
#### .createSheet(sheetTitle, topicTitle?) => `Sheet`
Once the workbook is created, then there's a way to build a sheet containing a `root topic`.
In addition, you can customize their titles by parameters.
| Name | Type | Default | Required |
|:---- |:----:|:-------:|:--------:|
| sheetTitle | String | `-` | Y |
| topicTitle | String | `Central Topic` | N |
#### .createSheets(options: Object[]) => `Object[]`
You can use this method to create sheets in bulk.
| Name | Type | Default | Required |
|:---- |:----:|:-------:|:--------:|
| sheetTitle | String | `-` | Y |
| topicTitle | String | `Central Topic` | N |
It returns an object of sheet identifier([Click here to check how it uses](./example/example.fully.js)).
```typescript
const sheets = workbook.createSheets([
{s: 'SheetTitle1', t: 'RootTopicTitle1'},
{s: 'SheetTitle2', t: 'RootTopicTitle2'}
]);
console.info(sheets);
// [
// { id: string, title: string },
// { id: string, title: string }
// ...
// ]
```
#### .getSheets() => `Object[]`
It allows you to get back the identifier of the sheet anytime and anywhere.
#### .getSheet(id: string) => `Sheet`
You can get an instance of the sheet with an existed sheet ID.
#### .theme(sheetTitle, themeName) => Boolean
The `UI client` has many theme styles and this library also offers some of them, such as `robust / snowbrush / business`.
| Name | Type | Default | Required |
|:---- |:----:|:-------:|:--------:|
| sheetTitle | String | null | Y |
| themeName | String | null | Y |
#### .toJSON()
Get component's data from the workbook in the form of `JSON`.
#### .toString()
Get component's data from the workbook in the form of `STRING`.
#### .validate() => `{status: Boolean, errors: Array | null}`
This is the way to prove that all data are available and complete.
The `status` indicates the result of validation which is `true` if it's correct, otherwise `false` returns.
## Topic
The `Topic` is an important constructor function that implements most of the methods.
And you're going to depend on it during most operations.
### Topic Options
* options.sheet <= `workbook.createSheet(...)`
You may wonder why we need to offer the `options.sheet` manually? The reason is that `Topic` is implemented independently and most of the methods depend on the instance of the sheet.
In the UI client, you also need to draw the mind map on the sheet.
> usage:
>
> ```js
> const {Topic, Workbook} = require('xmind');
> const wb = new Workbook();
>
> new Topic({sheet: wb.createSheet('Sheet-1', 'topic-1')});
> ```
### Methods
#### .on(componentId?) => Topic
Set the component to be parent node. If there isn't component ID, the `Central Topic` will become as parent node.
#### .cid(title?, options?: { customId?: string, parentId?: string }) => String
Use this method to get componentId.
> You should use `customId` or `parentId` for getting the `componentId` if there are some duplicated topic titles.
If you don't specify the title in the period of calling `.cid()`,
the last `componentId` that you've added would be returned.
#### .cids() => {$cid: $title}
It will return all the `key/value`s in once.
#### .add(options) => Topic
Add a topic component under parent node.
| Name | Type | Default | Required |
|:----:|:----:|:---------------------------------------------------:|:--------:|
| options.title | String | null | Y |
| options.parentId | String | The previous topic that you've operated on | N |
| options.customId | String | It would be useful if you have the same topic title | N |
#### .note(text, del?) => Topic
Attach a text to parent node.
| Name | Type | Default | Required | Description |
|:----:|:----:|:-------:|:--------:|:------------|
| text | String | null | Y | text message |
| del | Boolean | false | N | detach the note from current parent node if the `del` is true |
#### .addLabel(text) => Topic
Add label text to the component, also you can add label to the same component many times.
| Name | Type | Default | Required | Description |
|:----:|:----:|:-------:|:--------:|:------------|
| text | String | null | Y | label text string |
#### .removeLabels(componentId?) => Topic
Remove all the labels from the component.
> If you don't give the componentId, then remove labels from the currently component.
| Name | Type | Default | Required | Description |
|:----:|:----:|:-------:|:--------:|:------------|
| componentId | String | null | N | - |
#### .marker(object) => Topic
Attach a marker flag to the parent node.
Moreover, you can detach a marker flag from the parent node by setting `object.del` as `true`.
Default: `false`
Example:
```js
const {Marker} = require('xmind');
const marker = new Marker();
// add
topic.marker(marker.smiley('cry'));
// del
topic.marker(Object.assign({}, marker.smiley('cry'), {del: true}));
```
> [Use `Marker Object` to generate the object](#marker-flags)
#### .image() => key
You can use `.image()` to get `image key` back.
However, you need to write image into manifest by `zip.updateManifestMetadata()` or `dumper.updateManifestMetadata()`.
> [See image example](./example/example.image.js)
> [See image in browser example](./example/example.image.browser.html)
#### .summary(options) => Topic
Attach a summary component to parent node including all children. In the meantime, the `edge` can be used to set the scope of summary component.
> **Important**
>
> The summary doesn't allow to be added under `Central Topic`
>
> The `edge` must parallel to parent node
| Name | Type | Default | Required |
|:---- |:----:|:-------:|:--------:|
| options.title | String | null | Y |
| options.edge | String | null | N |
> [About `edge`](./docs/edge.graphic.txt)
#### .destroy(componentId) => Topic
Destroy a component from the map tree.
> **Important**
>
> All children would be destroyed along with it
## Marker flags
We provide an instance of `Marker` that includes all the markers. Such as:
###### .priority(name: `string`)
###### .smiley(name: `string`)
###### .task(name: `string`)
###### .flag(name: `string`)
###### .star(name: `string`)
###### .people(name: `string`)
###### .arrow(name: `string`)
###### .symbol(name: `string`)
###### .month(name: `string`)
###### .week(name: `string`)
###### .half(name: `string`)
###### .other(name: `string`)
> **The `name` of marker is available [!here](./docs/icons.md)**
>
> You can also use the **Marker.groups** and **Marker.names** to find out available names of Marker.
### Static methods
#### Marker.groups() => Array\
List available group names.
#### Marker.names(groupName) => Array\
* Get the flag names by `groupName`.
## Zipper
The module of `Zipper` only works under backend.
> [!See `Dumper` in browser environment](#dumper)
### Zipper Options
| Name | Type | Default | Required | Description |
|:---- |:----:|:-------:|:--------:|:------------|
| options.path | String | `-` | Y | The path is where to save the `.xmind` file |
| options.workbook | Workbook | `-` | Y | The instance of Workbook |
| options.filename | String | default | N | `default.xmind` |
#### .updateManifestMetadata(key, content) => Zipper
Update manifest for image insertion.
| Name | Type | Default | Required | Description |
|:---- |:----:|:-------:|:--------:|:------------|
| key | String | null | Y | The key only can get by topic.image() |
| content | Buffer | null | Y | The buffer data of image |
#### .removeManifestMetadata(key) => Zipper
Remove a pair of key / value from manifest.
#### .save() => Promise\
Save components to the logic disk in the form of zip.
## Dumper
The module of `Dumper` only works under browser.
### Dumper methods
#### .dumping() => Array<{filename: string, value: string}>
Return an array of objects composed of file content.
In order to open it in the official software,
you need to compress these files in the form of zip with the suffix `.xmind`.
> **Important**
>
> Don't include top level folders, otherwise the software can't extract files
#### .updateManifestMetadata(key, content, creator) => Promise\
Update manifest for image insertion.
| Name | Type | Default | Required | Description |
|:---- |:----:|:-------:|:--------:|:------------|
| key | string | null | Y | The key only can get by topic.image() |
| content | File \| Blob \| ArrayBuffer | null | Y | The data of image |
| creator | FileCreator | | Y | To specify how to save the file |
where `FileCreator` is
```typescript
interface FileCreator {
/**
* Hint that should create a folder-like structure, enter the folder if exists
* @param name - Folder name
*/
folder(name: string): Promise
/**
* Hint that should create a file-like object with `content`, update the file if exists
* @param name Filename
*/
file(name: string, content: File | Blob | ArrayBuffer): Promise
}
```
## Contributing
Thank you for being interested in the SDK.
If you have any problems or suggestions, please let's know. 🙂
We also welcome you to submit a pull request for any big or small issues.
## License
See the [MIT License](LICENSE).