mirror of
https://github.com/laurent22/joplin.git
synced 2024-12-24 10:27:10 +02:00
Docs: Clarifying how to get/test the hello world plugin via scaffolding (#4419)
This commit is contained in:
parent
7af1c9eaef
commit
f01fb8d66c
@ -7,41 +7,57 @@ In this article you will learn the basic steps to build and test a plugin in Jop
|
||||
First you need to setup your environment:
|
||||
|
||||
- Make sure you have [Node.js](https://nodejs.org/) and [git](https://git-scm.com) installed.
|
||||
- Install Joplin and run it in development mode.
|
||||
|
||||
You will also need to have Joplin installed and running in development mode, which we'll describe later.
|
||||
|
||||
But first install Yeoman and the Joplin Plugin Generator:
|
||||
- Install [Joplin](https://joplinapp.org/)
|
||||
|
||||
But first install [Yeoman](https://yeoman.io/) and the [Joplin Plugin Generator](https://github.com/laurent22/joplin/tree/dev/packages/generator-joplin):
|
||||
|
||||
npm install -g yo generator-joplin
|
||||
|
||||
Then to create the plugin, run:
|
||||
Then, in the directory where you plan to develop the plugin, run:
|
||||
|
||||
yo joplin
|
||||
|
||||
This will create the basic scafolding of the plugin. At the root of it, there is a number of configuration files which you normally won't need to change. Then the `src/` directory will contain your code. By default, the project uses TypeScript, but you are free to use plain JavaScript too - eventually the project is compiled to plain JS in any case.
|
||||
This will generate the basic scafolding of the plugin. At the root of it, there are a number of configuration files which you normally won't need to change. Then the `src/` directory will contain your code. By default, the project uses TypeScript, but you are free to use plain JavaScript too - eventually the project is compiled to plain JS in any case.
|
||||
|
||||
The `src/` directory also contains a [manifest.json](https://github.com/laurent22/joplin/blob/dev/readme/api/references/plugin_manifest/) file, which you can edit to set various information about the plugin, such as its name, homepage URL, etc.
|
||||
The `src/` directory also contains a [manifest.json](https://github.com/laurent22/joplin/blob/dev/readme/api/references/plugin_manifest.md) file, which contains the various information about the plugin that was set in the inital generation of the scaffolding, such as its name, homepage URL, etc. You can edit this at any time, but editing it after it has been published may cause users to have to download it again.
|
||||
|
||||
## Setup Source Control
|
||||
|
||||
In your plugin directory, run:
|
||||
|
||||
git init
|
||||
|
||||
This will setup source control.
|
||||
|
||||
|
||||
## Run Joplin in Development Mode
|
||||
|
||||
You should test your plugin in Development Mode. Doing so means that Joplin will run using a different profile, so you can experiment with the plugin without risking to accidentally change or delete your data.
|
||||
|
||||
## Building the plugin
|
||||
|
||||
The file `src/index.ts` already contain some basic code meant for testing the plugin. In particular it contains a call to [joplin.plugins.register](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html), which all plugins should call to register the plugin. And an `onStart()` event handler, which will be executed by Joplin when the plugin starts.
|
||||
From the scaffolding, `src/index.ts` now contains the basic code for a Hello World plugin.
|
||||
|
||||
Two things to note:
|
||||
1. It contains a call to [joplin.plugins.register](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#register). All plugins call this to register the plugin in the app.
|
||||
2. An `onStart()` event handler method, which is called when the plugin starts.
|
||||
|
||||
To try this basic plugin, compile the app by running the following from the root of the project:
|
||||
|
||||
npm run dist
|
||||
|
||||
Doing so should compile all the files into the `dist/` directory. This is from here that Joplin will load the plugin.
|
||||
Doing so should compile all the files into the `dist/` directory. This is where Joplin will load the plugin.
|
||||
|
||||
## Testing the plugin
|
||||
## Install the plugin
|
||||
Open Joplin **Configuration > Plugins** section. Under Advanced Settings, add the plugin path in the **Development plugins** text field.
|
||||
This should be the path to your main plugin directory, i.e. `path/to/your/root/plugin/directory`.
|
||||
|
||||
In order to test the plugin, you might want to run Joplin in [Development Mode](https://github.com/laurent22/joplin/blob/dev/readme/api/references/development_mode.md). Doing so means that Joplin will run using a different profile, so you can experiment with the plugin without risking to accidentally change or delete your data.
|
||||
|
||||
Finally, in order to test the plugin, open the Setting screen, then navigate the the **Plugins** section, and add the plugin path in the **Development plugins** text field. For example, if your plugin project path is `/home/user/src/joplin-plugin`, add this in the text field.
|
||||
|
||||
Restart the app, and Joplin should load the plugin and execute its `onStart` handler. If all went well you should see the test message in the plugin console: "Test plugin started!".
|
||||
## Test the Plugin, Hello World!
|
||||
Restart the Development app from the command line/terminal, and Joplin should load the plugin and execute its `onStart` handler. If all went well you should see the test message in the plugin console: "Hello world. Test plugin started!". You will also be able to see the information from the manifest in the **Settings > Plugins**
|
||||
|
||||
# Next steps
|
||||
Great, you now have the basics of a working plugin!
|
||||
|
||||
- You might want to check the [plugin tutorial](https://github.com/laurent22/joplin/blob/dev/readme/api/tutorials/toc_plugin.md) to get a good overview of how to create a complete plugin and how to use the plugin API.
|
||||
- For more information about the plugin API, check the [Plugin API reference](https://joplinapp.org/api/references/plugin_api/classes/joplin.html).
|
||||
- Start the [plugin tutorial](https://github.com/laurent22/joplin/blob/dev/readme/api/tutorials/toc_plugin.md) to learn how to use the plugin API.
|
||||
- See what the plugin API supports, [Plugin API reference](https://joplinapp.org/api/references/plugin_api/classes/joplin.html).
|
||||
- For plugin feature ideas, see this thread: https://discourse.joplinapp.org/t/any-suggestions-on-what-plugins-could-be-created/9479
|
||||
|
Loading…
Reference in New Issue
Block a user