Skip to content

Commit 25a392e

Browse files
McBenMcBen
committed
docs: rephrase part 2
1 parent 19d50a7 commit 25a392e

4 files changed

Lines changed: 54 additions & 97 deletions

File tree

‎docs/6-hooks.md‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
# 6. Hooks
22

3-
So far our plugin only reacts on dialog open.
4-
"Hooks" are the way IITC will send event messages.
3+
So far our plugin only reacts when the dialog is opened. "Hooks" are how IITC broadcasts event messages to plugins.
54

6-
Before we start we have to change the way our dialog is filled with data.
5+
Before we add hooks, we first change how the dialog is populated with data.
76
```typescript {4,13-24,27-49,56}
87
class CountPortals implements Plugin.Class {
98

@@ -66,10 +65,10 @@ class CountPortals implements Plugin.Class {
6665
}
6766
```
6867

69-
We store the "dialog" handle and clear it on close. The function `updateDialog` will replace the contents of our table with a freshly generated snapshot.
68+
We keep a reference to the dialog so we can update or clear it when needed. The `updateDialog` method rebuilds the table contents from the latest data.
7069

7170

72-
Now let's subscribe to the message that drawTools sends:
71+
Next we'll subscribe to the message sent by drawTools:
7372
```typescript {11,14-18,27}
7473
class CountPortals implements Plugin.Class {
7574

@@ -103,9 +102,9 @@ class CountPortals implements Plugin.Class {
103102
}
104103
```
105104

106-
Wait. What's that crazy function definition? `onDrawingChanged = (): void => {`
107-
Usually you'll use `addhook` like any other event handler and would use something like `window.addHook("pluginDrawTools", () => this.onDrawingChanged());`
108-
This is the regular way. Our "addHook" call is done when we create the dialog. So we also have to remove it again on dialog close.
109-
For such a thing we need a variable were we store the function pointer.
105+
You may notice the handler is defined as an arrow function assigned to a class property: `onDrawingChanged = (): void => { ... }`. Assigning the callback this way ensures it keeps the correct `this` binding and lets us pass the function directly to `addHook` as `window.addHook("pluginDrawTools", this.onDrawingChanged)`.
106+
(if you're familar with javascript this is just a different way of "bind")
110107

111-
Note IITC.me: "addHook" will check if the string is a valid message string. If you created your own events or try to use other 3rd-party plugins messages, call `window.pluginCreateHook("pluginDrawTools")` before using them.
108+
Because we register the hook when the dialog is created, we must remove it when the dialog is closed. Storing the function reference makes it possible to call `window.removeHook("pluginDrawTools", this.onDrawingChanged)` later.
109+
110+
Note: `addHook` validates the message name. If you define your own messages or use hooks provided by other third-party plugins, call `window.pluginCreateHook("pluginDrawTools")` before registering the hook.

‎docs/7-release.md‎

Lines changed: 11 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# 7. Release
22

3-
The final step when creating an addon is publishing it to other people.
3+
The final step in creating an add-on is publishing it so others can install and use it.
44

55
## Versioning
66

7-
You can manually set a version number in plugin.json:
7+
You can set a version number manually in `plugin.json`:
88

99
::: code-group
1010
```json{4} [plugin.json]
@@ -20,33 +20,23 @@ You can manually set a version number in plugin.json:
2020
```
2121
:::
2222

23-
A better way is using GIT TAGs. Remove the 'version' line and create a TAG like `v1.0`
23+
A better approach is to use Git tags. Omit the `version` field from `plugin.json` and create a Git tag such as `v1.0` for releases.
2424

25-
Q: "What is GIT?"
26-
27-
A: It's a source code management system. If you don't know it you can skip it.
28-
If you're a developer or want to become one: grab a tutorial.
29-
I highly recommend using it, but it is not required.
25+
If you are new to Git, it's a version control system worth learning—especially if you plan to publish and maintain code—but it's not strictly required for releasing a plugin.
3026

3127
## Building
3228

33-
`yarn build:prod` creates a release version for end-users.
34-
A release version will strip off some stuff and adds some optimizations.
29+
Running `yarn build:prod` creates a production-ready build for end users. The build process applies optimizations and strips development-only code.
3530

36-
If you like to minimize your code add a `minimize: true` to your `plugin.json` config file.
37-
This will reduce the size and remove debug stuff like console.log. But it makes it hard to read and review your code without access to your sources.
38-
The benefit of a minimized vs. a normal version is not a big deal. IITC is still a project that live of open and shared code.
31+
If you want to further reduce the output size, add `"minimize": true` to your `plugin.json`. This removes debug statements (for example, `console.log`) and minifies the code, which makes it harder to inspect without the original sources. For most plugins, minimizing offers only modest benefits—IITC values open, reviewable code.
3932

40-
After the script has finished, you'll find the files in your `/dist` folder.
41-
A `myplugin.user.js` with the code and a `myplugin.meta.js` which is used for version checking.
33+
When the build completes, the generated files appear in the `dist/` folder: a `myplugin.user.js` containing the compiled plugin and a `myplugin.meta.js` used for update/version checking.
4234

4335
### GitHub action
4436

45-
If you want to automate things, you could add a [GitHub action](https://github.com/features/actions), so every time you push a tag that starts with a `v`, you will create
46-
a production build, a new release on GitHub, and then add the created `user.js` script to your release so fellow agents can download it.
47-
Automagically ;)
37+
You can automate releases with a GitHub Action: when you push a tag that starts with `v`, the workflow can build a production release, create a GitHub Release, and upload the generated `user.js` and other assets automatically.
4838

49-
Here is an example:
39+
Here is an example workflow:
5040

5141
::: details deploy-gh-pages.yml
5242
```yaml
@@ -92,10 +82,8 @@ jobs:
9282
9383
## Distribute
9484
95-
There are multiple ways how to distribute your code. And even every faction has its own distribution channels.
96-
One of the best methods is to create a public git repository including the /dist/ folder.
97-
This way everybody can check your sources and everybody has easy access to your compiled file.
85+
There are several ways to distribute your plugin. A common approach is to publish a public Git repository that includes the `dist/` folder. This lets users review your source and easily download the compiled script.
9886

9987
----
10088

101-
While this chapter was really short, you should grab a coffee for the next one.
89+
This chapter was short—take a coffee break, then continue with the next chapter.

‎docs/8-debugging.md‎

Lines changed: 24 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,53 @@
11
# 8. Debugging
22

3-
Nobody is perfect, and we all make mistakes.
4-
Some of them are easy to spot and can easily caught by our editor, Typescript or ESLint. Some bugs are real evil and hard to find.
3+
Bugs happen — some are simple and can be caught by your editor, TypeScript, or ESLint; others are trickier. The browser developer tools are your best friend for tracking them down. Press `F12` to open the tools; they may look intimidating at first, but you'll get comfortable quickly.
54

6-
Our browser will help us: hit `F12` to open the developer tools.
7-
If you see it the first time it might look overwhelming. Don't be afraid you'll soon master it.
5+
The `Elements` (Firefox: `Inspector`) panel helps when the problem is layout or HTML. Here we focus on the `Console` and `Sources` (Firefox: `Debugger`) tabs for debugging code.
86

9-
'Elements' (FF:'inspector') is helpful if something is wrong in your html-code/design or if you want playing with styles.
10-
Here we will focus on the tabs 'console' and 'sources' (FF:'debugger') because that's for code.
7+
## Console
118

12-
## Tab - Console
9+
We already used the console in the examples: `console.log("CountPortals " + VERSION);`. IITC produces a bunch of Log-Lines but you should find our message `CountPortals v0.0.0`, quite at the beginning.
1310

14-
We already made use of it: `console.log("CountPortals " + VERSION);`
15-
If you scroll through the console messages (when the iitc-page and our tutorial plugin is loaded)
16-
there should be a line "CountPortals v0.0.0". This was generated by that command.
11+
The console supports different message levels: `debug`, `info`, `log`, `warn`, and `error`. Which to use is up to you, but `log` is usually sufficient for general-purpose messages. Use `console.warn(...)` and `console.error(...)` for important issues — they are highlighted in the console.
1712

18-
Not an amazing message, but it tells use: plugin is loaded and 'init' was called.
19-
20-
There are different 'level' of messages you can generate: `debug`, `info`, `log`, `warn`, `error`
21-
Where to use debug, info or log is upto you. Usually you can stay with 'log' and ignore the others.
22-
23-
Keep `console.warn("data is missing");` and `console.error("this should never happen");` for terrible cases. They are also displayed in different colors to draw your attention.
24-
There is another one I like to use: `console.assert( t > 0, "t must be greater then 0");` a conditional error message.
25-
26-
Instead of pure text you can output objects too.
13+
You can also log objects to inspect them:
2714

2815
```typescript
2916
doCount(): void {
30-
console.log("Current portal:");
31-
console.log(window.portals[selectedPortal]);
17+
console.log("Current portal:", window.portals[selectedPortal]);
3218
[...]
3319
```
34-
When you now open our dialog you'll see the data of current selected portal. If one is selected else you'll only get an "undefined".
35-
36-
In the last line of this tab you can directly run javascript commands.
37-
All iitc-plugins are stored in the object plugin, so for calling our dialog we can run:
38-
`> plugin.CountPortals.doCount(); `
20+
Opening the dialog after logging the portal object will show its data in the console (or `undefined` if nothing is selected).
3921
40-
When searching for a bug: put `console.log` commands on every line that could provide a hint.
41-
Watch the log while the script is running and check if everything is like expected.
22+
You can also execute JavaScript directly from the console prompt. For example, plugins are exposed on the global `plugin` object, so you can call:
23+
`> plugin.CountPortals.doCount();`
4224
43-
## Tab-Source
25+
When hunting bugs, sprinkle `console.log` statements in places that might reveal the problem and watch the output as the code runs.
4426
45-
While logging is easy it can still be hard to understand why something went wrong.
27+
## Sources
4628
47-
The 'Source' (or 'Debugger') Tab let us investigate our code directly.
48-
Search our code in the tree view on the left side: iitc_plugin_CountPortals/main.ts (in firefox:webpack/iitc_plugin_CountPortals/main.ts)
29+
Logging helps, but stepping through code with a debugger often reveals the root cause faster. The `Sources` (or `Debugger` in Firefox) tab lets you browse your source files.
4930
50-
When selecting it you'll see our code appearing in the middle window. Okay, we know our source. That doesn't help much BUT we can set breakpoints.
51-
Scroll to our 'doCount' function and click on the line number of the first line in that function (or press ctrl-b).
31+
Find `iitc_plugin_CountPortals/main.ts` (in Firefox look under `webpack/iitc_plugin_CountPortals/main.ts`) and open it. You can set breakpoints by clicking the line numbers (or using your browser's shortcut to toggle a breakpoint).
5232
53-
Now hit our "count" link in IITC to trigger that function and the debugger should stop executing at our breakpoint.
54-
On the lower right side you'll see the "callstack" (= which function calls were done till reaching that point) and "watches".
55-
There you can add variables of interest (or just hover the mouse over your code).
56-
Above that are shortcuts for stepping through your code (f8->run; f10->execute one line; f11->follow deeper into the next function)
33+
Trigger the action (e.g., click the plugin's count link) and execution will pause at the breakpoint. The debugger shows the call stack and lets you inspect variables — add watches or hover variables to view values. Use the step controls to run, step over, or step into functions (browser shortcuts vary: e.g., F8 to resume, F10 to step over, F11 to step into).
5734
5835
## Mobile
5936
60-
Sometimes bugs only appear on mobile devices.
37+
Some bugs only surface on mobile devices. IITCm provides a built-in console you can enable once via `Settings -> Advanced Settings -> Configure IITCm menu -> check 'debug'`.
6138
62-
Here we got a console too! How to make it visible:
63-
enable it once: settings -> adv. settings -> Configure IITCm menu -> check 'debug'
39+
The `debug` menu item opens a compact console that shows logs and provides a prompt to run JavaScript.
6440
65-
The `debug` in your IITC Menu will open a small version of the console you know from your desktop browser. On the bottom line is a button to minimize the log and a line to execute js-commands.
41+
For a more powerful setup, use remote debugging.
6642
67-
This helps a little bit, but wait, we do it even better:
43+
### Remote debugging
6844
69-
### Remote debug
45+
To debug a live mobile session, connect your phone via USB and enable USB debugging (on Android: tap the build number several times to enable Developer Options, then enable USB debugging).
7046
71-
Connect your phone via USB to your PC.
72-
- Enable USB debugging (settings->about-> click "build-number" multiple times; then system->adv->Dev.Options->USB-Debug)
73-
- start 'chrome' and open the page: "chrome://inspect/#devices"
74-
- on your phone an "allow connection?" dialog should pop up -> allow
75-
- if you now run IITC on your phone it should appear under your device in chrome
76-
(if you got connection problems check if other USB-debuggers are running or switch USB port)
77-
- hit "inspect" and enjoy
47+
Open Chrome on your desktop and go to `chrome://inspect/#devices`. Approve the connection on your phone when prompted. Your running IITC page should appear under the device; click `inspect` to open the remote DevTools for the mobile page.
7848

79-
The view is a little bit different, but you've all debug possibility as it would run on your desktop.
49+
The remote tools provide the same debugging capabilities as on desktop. If the device doesn't appear try another USB port.
8050

81-
Getting your plugin to the mobile device can be tricky sometimes.
82-
I prefer the adb way (once installed) -> `adb push dist/myplugin.dev.user.js /mnt/sdcard/IITC_Mobile/plugins`
51+
The Android-SDK has a tool (ADB) that can help copy your plugin to the device:
52+
`adb push dist/myplugin.dev.user.js /mnt/sdcard/IITC_Mobile/plugins`
8353

‎docs/index.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11

2-
# Tutorial - CountPortals
2+
# Tutorial — CountPortals
33

4-
This is a tutorial for the [IITC Plugin Kit](https://github.com/McBen/IITCPluginKit).
4+
This tutorial walks you through building a plugin with the [IITC Plugin Kit](https://github.com/McBen/IITCPluginKit).
55

6-
What we'll get when it's done: a plugin that counts portals in hackrange of a DrawTools polyline.
6+
By the end you'll have a plugin that counts portals within the hack range of a DrawTools polyline.
77

88
![Screenshot](/images/final.png)
99

10-
## What you need to start:
10+
## Prerequisites
1111

12-
- [node](https://nodejs.org)
13-
- [yarn](https://yarnpkg.com)
14-
- a text editor - everyone will do. I recommend: [vs-code](https://code.visualstudio.com)
15-
- an [Ingress](https://ingress.com/) account, [IITC](https://iitc.app/), a browser,... if you don't know what I'm talking about, you're in the wrong place anyway
16-
- for adv. users: [git](https://git-scm.com/) for source code management
12+
- [Node.js](https://nodejs.org)
13+
- [Yarn](https://yarnpkg.com)
14+
- A text editor (any will do); I recommend [VS Code](https://code.visualstudio.com)
15+
- An [Ingress](https://ingress.com/) account and [IITC](https://iitc.app/) installed in your browser
16+
- (Optional, for advanced users) [Git](https://git-scm.com/) for source control
1717

18-
Not required but helpful: knowledge of HTML, CSS/postCSS, JQuery, Leaflet, Typescript or Javascript.
18+
Helpful but not required: familiarity with HTML, CSS/postCSS, jQuery, Leaflet, TypeScript, or JavaScript.

0 commit comments

Comments
 (0)