Merge pull request #41 from Flow-Launcher/add_nodejs_guide

Add Node.js plugin guide

Author: jjw24

_sidebar.md

@@ -12,6 +12,11 @@
       - [**Write the code**](/py-write-code.md)
       - [**Add your plugin to Flow**](/py-release-project.md)
       - [**Plugin references**](/py-plugin-references.md)
+	- JavaScript/TypeScript Plugins
+      - [**Before you start**](/nodejs-develop-plugins.md) 
+      - [**Set up your project**](/nodejs-setup-project.md)
+      - [**Write the code**](/nodejs-write-code.md)
+      - [**Add your plugin to Flow**](/nodejs-release-project.md)
     - JSONRPC
       - [**JSON RPC Introduction**](/json-rpc.md)
     - [**Porting Plugins**](/port-plugins.md)

nodejs-develop-plugins.md

@@ -0,0 +1,17 @@
+### About Flow's TypeScript/JavaScript plugins
+
+Plugins written in TypeScript/JavaScript use the [JSON-RPC](https://flow-launcher.github.io/docs/#/json-rpc) protocol to communicate with Flow via JSON structured calls.
+
+Although not a hard requirement, this guide will use Node.js to run the TypeScript/JavaScript. We will refere to TypeScript/JavaScript plugin as Node.js plugin from here on.
+
+When building a Node.js plugins there are several things to be mindful of:
+
+* The most important thing is we do not expect users to have to manually install the dependencies via npm because we aim to provide a seamless experience for them. This can be achieved by adding the following three things to your project:
+    1. Add a GitHub workflow- use a GitHub workflow that will install all your plugin's depedencies including the modules inside a folder called 'node_modules'.
+    2. Publish all as a zip- zip up your project including a lib directory that contains the modules and publish it to GitHub Releases page.
+    3. Point your module path to the node_modules directory- reference all the modules to that directory.
+
+* Currently we will require users to install Node.js on the computer in order to use the plugin, so you will need to explain how to do so in your plugin readme.
+
+### Simple Example
+Have a look at this simple example plugin [here](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS), notice it has a folder called '.github/workflows' and a file called 'Publish Release.yml'. This is the workflow file that GitHub Workflow uses to run the CICD for the project. Moving out of that folder you can go into the [main.js](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS/blob/main/main.js) file, this is the entry file for your plugin.

nodejs-release-project.md

@@ -0,0 +1,2 @@
+### Release your plugin to Flow's Plugin Store 
+When you are ready to release your plugin for people to enjoy, simply head over to Flow's [plugin repo](https://github.com/Flow-Launcher/Flow.Launcher.PluginsManifest) and follow the instructions there in the readme.

nodejs-setup-project.md

@@ -0,0 +1,62 @@
+### 1. Add GitHub workflow
+The workflow [file](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS/blob/main/.github/workflows/Publish%20Release.yml) will help build and deploy your project, it does the following things:
+1. `workflow_dispatch:` gives you the option to manually run your workflow from the Actions section of your project
+
+2. On pushes to main, it will kick off the workflow but ignore the push if it's only changes made to the workflow file.
+
+```yml
+push:
+    branches: [ main ]
+    paths-ignore: 
+      - .github/workflows/*
+```
+
+3. It specifies the Node.js version that will be used for building your project:
+
+```yml
+- name: Set up Node.Js
+  uses: actions/setup-node@v2
+  with:
+    node-version: '17.3.0'
+```
+
+4. The project's release version is obtained from your plugin.json automatically by the ci, so when built it will be appended to the zip file later:
+
+```yml
+- name: get version
+  id: version
+  uses: notiz-dev/github-action-json-property@release
+  with: 
+    path: 'plugin.json'
+    prop_path: 'Version'
+```
+
+5. The 'Install dependencies' section is where you will do most of your CI work. It will run `npm install`, which will output all the dependencies specified in package.json into the 'node_modules' directory. The workflow will then zip them up along with your project using `zip -r Flow.Launcher.Plugin.HelloWorldNodeJS.zip . -x '*.git*'`, where you replace this `Flow.Launcher.Plugin.HelloWorldNodeJS` with the name of your plugin.
+
+```yml
+- name: Install dependencies
+  run: |
+    npm install
+    zip -r Flow.Launcher.Plugin.HelloWorldNodeJS.zip . -x '*.git*'
+```
+
+### 2. Publish as zip
+The final step to the workflow file is this publish section, which will publish the zip file you generated, upload to GitHub Releases page and tag with the version generated from the previous step from your plugin.json file. Remember again to replace `Flow.Launcher.Plugin.HelloWorldNodeJS` with the name of your plugin.
+
+```yml
+- name: Publish
+  uses: softprops/action-gh-release@v1
+  with:
+    files: 'Flow.Launcher.Plugin.HelloWorldNodeJS.zip'
+    tag_name: "v${{steps.version.outputs.prop}}"
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Feel free to also have a read of this [blog post](https://blog.ipswitch.com/how-to-build-your-first-github-actions-workflow) which does a simple explaination of how to use GitHub Actions Workflow.
+
+### 3. Use node_modules directory
+Once the 'node_modules' folder is included in your zip release, it can then be used without needing the user to manually npm install the plugin's dependencies. You just have to tell the plugin during runtime to find those modules in your local node_modules directory. Do this by using this exact copy of the following block of code in your [main.js](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS/blob/main/main.js):
+```javascript
+const open = require('./node_modules/open')
+```

nodejs-write-code.md

@@ -0,0 +1,65 @@
+### 1. Start with a branch
+Since we have created a CI for your plugin in the [previous step](https://flow-launcher.github.io/docs/#/py-setup-project), which includes creating a release when you push/merge to the 'main' branch, it is then neccessary to create another git branch separate to your 'main' branch so you can continue to work on your plugin with git commits and pushes without creating a new release each time.
+
+It is a good practice that you create a branch for each of the new feature/fixes you are releasing for your plugin, if you are not sure how to do so then follow this [video tutorial](https://www.gitkraken.com/learn/git/problems/create-git-branch). Once you have fully finished developing your plugin with your new branch, then you can merge it into the 'main' branch, which will consequently create a new release for your plugin with a version from your `plugin.json`.
+
+### 2. main.py
+your main.js should look something like below:
+```
+const open = require('./node_modules/open')
+
+const { method, parameters } = JSON.parse(process.argv[2])
+
+if (method === "query") {
+	console.log(JSON.stringify(
+		{
+			"result": [{
+				"Title": "Hello World Typescript",
+				"Subtitle": "Showing your query parameters: " + parameters + ". Click to open Flow's website",
+				"JsonRPCAction": {
+                    "method": "do_something_for_query",
+                    "parameters": ["https://github.com/Flow-Launcher/Flow.Launcher"]
+                },
+				"IcoPath": "Images\\app.png"
+			}]
+		}
+	));
+}
+
+if (method === "do_something_for_query") {
+	url = parameters[0]
+	do_something_for_query(url)
+}
+
+function do_something_for_query(url) {
+	open(url);
+}
+```
+
+<br/>
+
+### 3. Query entry point 
+**if (method === "query")**
+
+This if statement captures the args passed viar JsonRPC defined as `const { method, parameters } = JSON.parse(process.argv[2])`, so if 'method' is 'query' then the console.log's code block will be run. As result is an array, you can also specify a single or multiple results.  
+
+### 4. Assigning an action to your results  
+**JsonRPCAction**
+
+This is where you specify the method that will be executed when the user selects on the result.
+In this example, if the user selects the result, the `do_something_for_query` method will be called with the url parameter which opens the Flow Launcher GitHub repo.
+
+### 5. node.bat
+The [node.bat](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS/blob/main/node.bat) file is the entry Flow uses to call main.js, it will set the working directory to the plugin's own location before calling main.js with node.
+```
+@echo off
+SET plugin_dir=%~dp0%
+node %plugin_dir%/main.js %*
+```
+
+### 6. Your plugin.json
+You will also need to if not yet already, create a plugin.json file that will instruct Flow on how to load your plugin.
+
+This file should be placed in the top level folder.
+
+To revisit what to include in your plugin.json, visit [here](https://flow-launcher.github.io/docs/#/plugin.json)

py-setup-project.md

@@ -1,19 +1,25 @@
 ### 1. Add GitHub workflow
 The workflow [file](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython/blob/main/.github/workflows/Publish%20Release.yml) will help build and deploy your project, it does the following things:
 1. `workflow_dispatch:` gives you the option to manually run your workflow from the Actions section of your project
+
 2. On pushes to main, it will kick off the workflow but ignore the push if it's only changes made to the workflow file.
+
 ```yml
 push:
     branches: [ main ]
     paths-ignore: 
       - .github/workflows/*
 ```
+
 3. It specifies the python version that will be used for building your project:
+
 ```yml
     env:
       python_ver: 3.8
 ```
+
 4. The project's release version is obtained from your plugin.json automatically by the ci, so when built it will be appended to the zip file later:
+
 ```yml
 - name: get version
   id: version
@@ -22,9 +28,11 @@ push:
     path: 'plugin.json'
     prop_path: 'Version'
 ```
+
 5. The 'Install dependencies' section is where you will do most of your CI work. Notice it installs the requirements.txt and outputs it with the `-t` parameter to the `./lib` folder. This tells pip to dump all the installed modules to the local lib folder which you will zip up along with your project using the `zip -r Flow.Launcher.Plugin.HelloWorldPython.zip . -x '*.git*'`, where you replace this `Flow.Launcher.Plugin.HelloWorldPython` with the name of your plugin.
 
     You can also add additional steps here to unpack/install any additional depedencies your plugin requires, for example compiling additional translation files like [this](https://github.com/deefrawley/Flow.Launcher.Plugin.Currency/blob/23770ee929af059b1b1b7f9b5f3327b692ac9587/.github/workflows/Publish%20Release.yml#L34)
+
 ```yml
 - name: Install dependencies
   run: |