From 797544b227c5242639ad33a3e6baaedbc94f7cac Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sat, 6 Jul 2019 12:38:51 +0200 Subject: [PATCH 01/10] Add command guide --- .idea/.gitignore | 2 + .idea/misc.xml | 6 +++ .idea/modules.xml | 8 ++++ .idea/thelounge.github.io.iml | 12 ++++++ .idea/vcs.xml | 6 +++ _guides/command-creation.md | 40 ++++++++++++++++++++ _guides/plugin-creation.md | 71 +++++++++++++++++++++++++++++++++++ 7 files changed, 145 insertions(+) create mode 100644 .idea/.gitignore create mode 100644 .idea/misc.xml create mode 100644 .idea/modules.xml create mode 100644 .idea/thelounge.github.io.iml create mode 100644 .idea/vcs.xml create mode 100644 _guides/command-creation.md create mode 100644 _guides/plugin-creation.md diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 00000000..5c98b428 --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,2 @@ +# Default ignored files +/workspace.xml \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100644 index 00000000..28a804d8 --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 00000000..87cd7e37 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/thelounge.github.io.iml b/.idea/thelounge.github.io.iml new file mode 100644 index 00000000..24643cc3 --- /dev/null +++ b/.idea/thelounge.github.io.iml @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 00000000..94a25f7f --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/_guides/command-creation.md b/_guides/command-creation.md new file mode 100644 index 00000000..9c3b840a --- /dev/null +++ b/_guides/command-creation.md @@ -0,0 +1,40 @@ +--- +layout: documentation +title: Create a custom command +description: Customize The Lounge using built-in custom command support +--- + +This guide assumes you have setup your own plugin already. If you don't know how to do that, check out [this guide](/docs/plugin-creation) + +The Lounge exposes an easy way to register your own commands, all you need to do is call the api in your `onServerStart` method like this: + +```js +module.exports = { + onServerStart: thelounge => { + thelounge.Commands.add("testcommand", testCommand); + }, +}; +``` + +where `testCommand` is an object that defines an input field with the command function: +```js +const testCommand = { + input: function (client, target, command, args) { + // command logic + } +}; +``` +- `client` is the public client api of The Lounge +- `target` is an object that wraps the channel and the network the command was enteres in, access them via `target.chan` or `target.network` +- `command` is the command string that was entered +- and `args` is an array of strings that followed the command string + +Optionally, you can add `allowDisconnected: true` to your command to be able to run the command while not being connected to an irc network: +```js +const testCommand = { + input: function (client, target, command, args) { + // command logic + }, + allowDisconnected: true +}; +``` diff --git a/_guides/plugin-creation.md b/_guides/plugin-creation.md new file mode 100644 index 00000000..4eb4da19 --- /dev/null +++ b/_guides/plugin-creation.md @@ -0,0 +1,71 @@ +--- +layout: documentation +title: Create a custom plugin +description: Customize The Lounge using built-in plugin support, and share plugins with others +--- + +Plugins for The Lounge are npm packages hosted on [the npm registry](https://www.npmjs.com). +The work similarly to themes. A theme is a plugin but not every plugin is a theme. + +In a directory named after your new plugin (for example, `thelounge-plugin-foo`), start by creating a new package with the following command: + +``` +yarn init -y +``` + +This will create a `package.json` file that you must edit as such: + +- Make sure `"name"` is the name of your package, `"thelounge-plugin-foo"` +- Change the value of `"main"` to be `"package.json"` +- Add a `"keywords"` to make sure your plugin is discoverable: + ```json + "keywords": [ + "thelounge", + "thelounge-plugin" + ] + ``` +- Add a `"thelounge"` section with required metadata. `"name"` is the display name that will appear in the client settings: + ```json + "thelounge": { + "name": "Plugin Name", + "type": "plugin" + }, + ``` +- Reference your main javascript file: + ```json + "main": "index.js", + ``` +- Add a dependency on `"thelounge"` + ```json + "dependencies": { + "thelounge": "3.0.1" + } + ``` +Although it is not required, we strongly recommend you also fill in the `"homepage"`, `"repository"`, and `"bugs"` sections. + +You can then place all your plugin code in your `index.js`. + +The Lounge defines an entry point for plugins, you can use it like this: +```js +module.exports = { + onServerStart: api => { + // do stuff with api + }, +}; +``` +Refer to [the API reference](/docs/api) to learn what you can do or start implementing your own custom command with +[the custom command guide](/guides/command-creation). + +## Helpful things for plugin developers + +Here follows a helpful list of things that might be of use to plugin developers: + +* You can import and use methods from The Lounge via node's `require` like this `const Msg = require("thelounge/src/models/msg");` +* You can send a message to a channel like this: + ```js + chan.pushMessage(client.client, new Msg({ + type: Msg.Type.ERROR, //TODO send "normal" message + text: "Hello World", + })); + ``` + where `chan` is the channel (`target.chan` if you are in a command) and `client` the public client. \ No newline at end of file From 1448f02b4378a655fd7b3a53ff61f2ed3b3cbd1f Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sat, 6 Jul 2019 12:41:56 +0200 Subject: [PATCH 02/10] Remove idea files --- .idea/.gitignore | 2 -- .idea/misc.xml | 6 ------ .idea/modules.xml | 8 -------- .idea/thelounge.github.io.iml | 12 ------------ .idea/vcs.xml | 6 ------ 5 files changed, 34 deletions(-) delete mode 100644 .idea/.gitignore delete mode 100644 .idea/misc.xml delete mode 100644 .idea/modules.xml delete mode 100644 .idea/thelounge.github.io.iml delete mode 100644 .idea/vcs.xml diff --git a/.idea/.gitignore b/.idea/.gitignore deleted file mode 100644 index 5c98b428..00000000 --- a/.idea/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -# Default ignored files -/workspace.xml \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml deleted file mode 100644 index 28a804d8..00000000 --- a/.idea/misc.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml deleted file mode 100644 index 87cd7e37..00000000 --- a/.idea/modules.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/thelounge.github.io.iml b/.idea/thelounge.github.io.iml deleted file mode 100644 index 24643cc3..00000000 --- a/.idea/thelounge.github.io.iml +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - - - - - - \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml deleted file mode 100644 index 94a25f7f..00000000 --- a/.idea/vcs.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file From de14ee9eac5c091ccf1a60f5a84a862e633f43a7 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sat, 6 Jul 2019 12:47:49 +0200 Subject: [PATCH 03/10] Add note about installing plugins locally --- _guides/plugin-creation.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/_guides/plugin-creation.md b/_guides/plugin-creation.md index 4eb4da19..9fbfcaa7 100644 --- a/_guides/plugin-creation.md +++ b/_guides/plugin-creation.md @@ -68,4 +68,33 @@ Here follows a helpful list of things that might be of use to plugin developers: text: "Hello World", })); ``` - where `chan` is the channel (`target.chan` if you are in a command) and `client` the public client. \ No newline at end of file + where `chan` is the channel (`target.chan` if you are in a command) and `client` the public client. + +## Installing a plugin locally + +The Lounge currently doesn't allow you to install a plugin from source, thats why we have to do it manually. + +For that we have to add our plugin as a new package in the THELOUNGE_HOME/packages dir. +For that you need to have a package.json in that packages dir that looks kinda like this: +```json +{ + "private": true, + "description": "Packages for The Lounge. All packages in node_modules directory will be automatically loaded.", + "dependencies": { + "thelounge-plugin-foo": "1.0.1" + } +} +``` +the important thing is the name here. + +You then need to create a folder with that name in the `node_modules` sub dir. +We then need to place our index.js and package.json in that dir. +You can do that manually by just copy pasting it, but that would involve copy pasting it for every change. +I would recommend symlinking the files from the project into the packages folder, kinda like this: +``` +ln package.json thelounge-home/packages/node_modules/thelounge-plugin-foo/package.json +ln index.js thelounge-home/packages/node_modules/thelounge-plugin-foo/index.js +``` +You can then just edit and commit the files in the project dir and restart The Lounge + on every change you do and the changes will be picked up. + \ No newline at end of file From 86984eec7f4fa7da0682c2f7e976a73b605a3af6 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sat, 6 Jul 2019 12:50:55 +0200 Subject: [PATCH 04/10] Add note about being able to execute commands on behalf of the user --- _guides/command-creation.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_guides/command-creation.md b/_guides/command-creation.md index 9c3b840a..28b52740 100644 --- a/_guides/command-creation.md +++ b/_guides/command-creation.md @@ -38,3 +38,9 @@ const testCommand = { allowDisconnected: true }; ``` + +You can make the client run commands or send messages via the `runAsUser` method like this: +```js +client.runAsUser("/whois MiniDigger", target.chan.id); +client.runAsUser("Hello world!", target.chan.id); +``` From d30b50ff445aff095993991bafe2cfe3e040fb7e Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sat, 6 Jul 2019 12:53:14 +0200 Subject: [PATCH 05/10] Remove copy pasted TODO tag --- _guides/plugin-creation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_guides/plugin-creation.md b/_guides/plugin-creation.md index 9fbfcaa7..29e1bfbf 100644 --- a/_guides/plugin-creation.md +++ b/_guides/plugin-creation.md @@ -64,7 +64,7 @@ Here follows a helpful list of things that might be of use to plugin developers: * You can send a message to a channel like this: ```js chan.pushMessage(client.client, new Msg({ - type: Msg.Type.ERROR, //TODO send "normal" message + type: Msg.Type.ERROR, text: "Hello World", })); ``` From d1048a31713d1cf4b34862929ad1655e66ab86c7 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sat, 6 Jul 2019 13:36:15 +0200 Subject: [PATCH 06/10] Add plugins link to navbar --- _layouts/default.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/_layouts/default.html b/_layouts/default.html index 70d929ae..2bc83172 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -37,6 +37,9 @@ + @@ -79,6 +82,7 @@
  • Home
    • {% include menu.html %}
  • Themes
    • +
  • Plugins
  • Community
    • From 1cd8cdd0c7a728a89f85013f57445a227d632353 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Sat, 6 Jul 2019 13:56:07 +0200 Subject: [PATCH 07/10] Fix typo --- _layouts/default.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_layouts/default.html b/_layouts/default.html index 2bc83172..98d8d2a5 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -38,7 +38,7 @@ Themes - @@ -82,7 +79,6 @@
  • Home
    • {% include menu.html %}
  • Themes
    • -
  • Plugins
  • Community
    • From c9de53ce4122bf7e24fb67e24a0720c1c5115e73 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Mon, 8 Jul 2019 20:38:08 +0200 Subject: [PATCH 09/10] Fix typo Co-Authored-By: Al McKinlay --- _guides/plugin-creation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_guides/plugin-creation.md b/_guides/plugin-creation.md index 29e1bfbf..7a9dc5a2 100644 --- a/_guides/plugin-creation.md +++ b/_guides/plugin-creation.md @@ -5,7 +5,7 @@ description: Customize The Lounge using built-in plugin support, and share plugi --- Plugins for The Lounge are npm packages hosted on [the npm registry](https://www.npmjs.com). -The work similarly to themes. A theme is a plugin but not every plugin is a theme. +This works similarly to themes. A theme is a plugin but not every plugin is a theme. In a directory named after your new plugin (for example, `thelounge-plugin-foo`), start by creating a new package with the following command: @@ -97,4 +97,4 @@ ln index.js thelounge-home/packages/node_modules/thelounge-plugin-foo/index.js ``` You can then just edit and commit the files in the project dir and restart The Lounge on every change you do and the changes will be picked up. - \ No newline at end of file + From 1bbbebdef33fc8a9b3080680511f3c8323347191 Mon Sep 17 00:00:00 2001 From: MiniDigger Date: Mon, 8 Jul 2019 20:40:13 +0200 Subject: [PATCH 10/10] Update _guides/plugin-creation.md Co-Authored-By: Al McKinlay --- _guides/plugin-creation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_guides/plugin-creation.md b/_guides/plugin-creation.md index 7a9dc5a2..9f8982b8 100644 --- a/_guides/plugin-creation.md +++ b/_guides/plugin-creation.md @@ -74,7 +74,7 @@ Here follows a helpful list of things that might be of use to plugin developers: The Lounge currently doesn't allow you to install a plugin from source, thats why we have to do it manually. -For that we have to add our plugin as a new package in the THELOUNGE_HOME/packages dir. +For that we have to add our plugin as a new package in the `THELOUNGE_HOME/packages` dir. For that you need to have a package.json in that packages dir that looks kinda like this: ```json {