Skip to content

Latest commit

 

History

History
122 lines (82 loc) · 4.55 KB

PLUGIN.md

File metadata and controls

122 lines (82 loc) · 4.55 KB
Raw
headingNumber
true

Plug-In Development Guide

English | 中文

[toc]{type: "ol"}

Preface

Yank Note is a open source, completely hackable note application.

My vision is to allow users to customize their own editor according to their own ideas, so that this editor can better assist users in their work and study. For example, for the scenario of Git Submit, users can write their own plug-ins to implement this function without waiting for developers to adapt.

At now, almost all functions inside Yank Note are implemented through a thin plug-in system (dozens of built-in plug-ins). The capabilities used by the built-in plug-ins are exactly the same as the plug-ins written by users, and you can even use some third-party libraries used by Yank Note in the plug-ins.

Write A Plug-In

  1. Right click the tray icon and click "Open Main Dir"
  2. Create a new file plugin-hello.js in <main directory>/plugins
  3. Edit the plugin-hello.js file and write the following content. 
    // register a plug-in
window.registerPlugin({
    name: 'plugin-hello',
    register: ctx => {
        // add menu on status bar
        ctx.statusBar.tapMenus(menus => {
            menus['plugin-hello'] = {
                id: 'plugin-hello',
                position: 'left',
                title: 'HELLO',
                onClick: () => {
                    ctx.ui.useToast().show('info', 'HELLO WORLD!');
                }
            }
        })
    }
});
  4. Right-click the tray icon and click "Develop > Reload"

Now you can see the "HELLO" menu in the status bar expectantly.

Core Concepts

Yank Note has some concepts that are the basis for supporting the entire plug-in system：

  1. Hook
  2. Action

Hook

When Yank Note performs some operations, it will trigger some hook calls.

Use ctx.registerHook to register a hook processing method.

Use ctx.triggerHook to trigger a hook.

The option { breakable: true } is appended when calling triggerHook, indicating that the hook call is breakable.

The following internal hook call is breakable:

  • ACTION_AFTER_RUN
  • ACTION_BEFORE_RUN
  • TREE_NODE_SELECT
  • VIEW_ELEMENT_CLICK
  • VIEW_ELEMENT_DBCLICK
  • VIEW_KEY_DOWN
  • EDITOR_PASTE_IMAGE

Breakable hook processing methods need to have a return value Promise<boolean> | boolean. When the hook processing method returns true, the subsequent hooks will no longer run。

For internal hook types, please refer to Api Document

Action

Yank Note has an Action Center ctx.action, which provides action management and operation。

For internal action, please refer to Api Document

Plug-In Capabilities

As you can see from the above, the functions of the plug-in are all implemented through the modules of ctx.

In addition to the above core modules, there are many other modules under ctx, which basically cover all aspects of the editor.

Run the following code, you can see which modules are available of ctx.

// --run-- --no-worker--
console.log(Object.keys(ctx).join('\n'))

Refer to Api Document to get more instructions.

Distribute Plugins

If you want to distribute your own plugins/themes to others, please refer to https://github.com/purocean/yank-note-extension#readme

More

In general, Yank Note encourages users to create their own work-learning tools that only need a few lines of code to help their work and study.

In addition, if you only need to create some handy tools, you don't need to write plug-ins, you can use RunCode function or write Widgets to achieve. The ability to run js code here is also completely open, and the global variable ctx also has all the above functions.

For example, run js code:

// --run-- --no-worker--
ctx.ui.useToast().show("info", "HELLOWORLD!")
console.log("hello world!")

Widgets

<!-- --applet-- -->
<button onclick="ctx.ui.useToast().show(`info`, `HELLOWORLD!`)">HELLO</button>