|
| 1 | +--- |
| 2 | +layout: docs-api |
| 3 | +toc: toc-api-library.html |
| 4 | +title: Library Store API |
| 5 | +slug: library |
| 6 | +--- |
| 7 | + |
| 8 | +**Since 1.3.0** |
| 9 | + |
| 10 | +The Import/Export dialog within the Node-RED editor provides a way to save flows |
| 11 | +and nodes to a local library. |
| 12 | + |
| 13 | +This local library is managed by the [Storage API](../storage). The default being |
| 14 | +to store in under `~/.node-red/lib`. |
| 15 | + |
| 16 | +The Library Store API is a plugin mechanism that can be used to provide libraries |
| 17 | +that store their contents in other locations - not just in local files. |
| 18 | + |
| 19 | +Node-RED provides a [File Store plugin](https://github.com/node-red/node-red-library-file-store) |
| 20 | +that can be used to add libraries stored on the local file-system. This could be used, |
| 21 | +for example, to create a library on a shared file-system via a tool like Dropbox, to make |
| 22 | +it easier to share flows with other developers you are working with. |
| 23 | + |
| 24 | +### Adding a File Store library |
| 25 | + |
| 26 | +1. Edit your Node-RED settings file - typically `~/.node-red/settings.js` |
| 27 | +2. Find the `editorTheme` section and add a `library` section if one does not |
| 28 | + already exist. |
| 29 | +3. Under that section add a `sources` array. Within that array you can add |
| 30 | + as many new file store sources as you want. |
| 31 | + |
| 32 | + ```javascript |
| 33 | + editorTheme: { |
| 34 | + library: { |
| 35 | + sources: [ |
| 36 | + { |
| 37 | + id: "team-collaboration-library", |
| 38 | + type: "node-red-library-file-store", |
| 39 | + path: "/Users/tom/work/team-library/", |
| 40 | + label: "Team collaboration", |
| 41 | + icon: "font-awesome/fa-users" |
| 42 | + } |
| 43 | + ] |
| 44 | + }, |
| 45 | + } |
| 46 | + ``` |
| 47 | + |
| 48 | +The configuration object can have the following properties: |
| 49 | + |
| 50 | + |
| 51 | +Property | Description |
| 52 | +---------|-------------- |
| 53 | +`id` | **Required** <br> A unique, url-safe, identifier for the library. Should contain only letters, numbers and the symbols `- _`. |
| 54 | +`type` | **Required** <br> Must be set to `node-red-library-file-store` |
| 55 | +`path` | **Required** <br> The absolute path to the where the library should be stored |
| 56 | +`label` | An optional label to use in the editor, otherwise the `id` will be used. |
| 57 | +`icon` | An optional icon from [FontAwesome 4.7](https://fontawesome.com/v4.7.0/icons/). |
| 58 | +`types` | By default the library will be used to store all types of object. It can be restricted to certain types by setting this property to an array of the acceptable types. <br> For example, to restrict it to just flows, set this property to `["flows"]`. |
| 59 | +`readOnly` | To make this a read-only library so it can only be used to import from, set this property to `true`. |
| 60 | + |
| 61 | + |
| 62 | +### Creating a new Store plugin |
| 63 | + |
| 64 | +To create a store backed by a different type of storage, you will need to create a new plugin. |
| 65 | + |
| 66 | +The plugin is packaged as an npm module, with a `package.json` file. |
| 67 | + |
| 68 | +The following code can be used as the starting point for the plugin. You should also |
| 69 | +refer to the [File Store plugin](https://github.com/node-red/node-red-library-file-store). |
| 70 | + |
| 71 | +#### package.json |
| 72 | + |
| 73 | +```json |
| 74 | +{ |
| 75 | + "name": "your-custom-library-store", |
| 76 | + "version": "1.0.0", |
| 77 | + "description": "A Custom Library plugin for Node-RED", |
| 78 | + "keywords": [ |
| 79 | + "node-red" |
| 80 | + ], |
| 81 | + "node-red": { |
| 82 | + "plugins": { |
| 83 | + "customstore": "store.js" |
| 84 | + } |
| 85 | + } |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +#### store.js |
| 90 | + |
| 91 | +```javascript |
| 92 | +module.exports = function(RED) { |
| 93 | + |
| 94 | + // This must be a unique identifier for the library store type |
| 95 | + const PLUGIN_TYPE_ID = "node-red-library-custom-store"; |
| 96 | + |
| 97 | + class CustomStorePlugin { |
| 98 | + |
| 99 | + /** |
| 100 | + * @param {object} config an object containing the configuration for an |
| 101 | + * instance of the store |
| 102 | + */ |
| 103 | + constructor(config) { |
| 104 | + // Required properties |
| 105 | + this.type = PLUGIN_TYPE_ID; |
| 106 | + this.id = config.id; |
| 107 | + this.label = config.label; |
| 108 | + } |
| 109 | + |
| 110 | + /** |
| 111 | + * Initialise the store. |
| 112 | + */ |
| 113 | + async init() { |
| 114 | + } |
| 115 | + |
| 116 | + /** |
| 117 | + * Get an entry from the store |
| 118 | + * @param {string} type The type of entry, for example, "flow" |
| 119 | + * @param {string} path The path to the library entry |
| 120 | + * @return if 'path' resolves to a single entry, it returns the contents |
| 121 | + * of that entry. |
| 122 | + * if 'path' resolves to a 'directory', it returns a listing of |
| 123 | + * the contents of the directory |
| 124 | + * if 'path' is not valid, it should throw a suitable error |
| 125 | + */ |
| 126 | + async getEntry(type,path) { |
| 127 | + throw new Error("Not implemented") |
| 128 | + } |
| 129 | + |
| 130 | + /** |
| 131 | + * Save an entry to the library |
| 132 | + * @param {string} type The type of entry, for example, "flow" |
| 133 | + * @param {string} path The path to the library entry |
| 134 | + * @param {object} meta An object of key/value meta data about the entry |
| 135 | + * @param {string} body The entry contents |
| 136 | + */ |
| 137 | + async saveEntry(type,path,meta,body) { |
| 138 | + throw new Error("Not implemented") |
| 139 | + } |
| 140 | + } |
| 141 | + |
| 142 | + // Register the plugin. |
| 143 | + RED.plugins.registerPlugin(PLUGIN_TYPE_ID, { |
| 144 | + // This tells Node-RED the plugin is a library source plugin |
| 145 | + type: "node-red-library-source", |
| 146 | + class: CustomStorePlugin |
| 147 | + }) |
| 148 | +} |
| 149 | +``` |
0 commit comments