wikiploy 1.8.1 → 1.8.2

package/README.building your project.md

@@ -17,20 +17,23 @@ bot.config.*
 Your `package.json` (crucial part being `scripts`):
 ```js
 {
-	"name": "wiki-gadget-yourgadetname",
+	"name": "wiki-gadget-yourgadgetname",
 	"type": "commonjs",
 	"scripts": {
 		"test": "mocha",
-		"build": "browserify src/main.js -o dist/yourGadetName.js",
+		"build-less": "lessc src/less/main.less dist/yourGadgetName.css",
+		"build-js": "browserify src/main.js -o dist/yourGadgetName.js",
+		"build": "npm run build-less && npm run build-js && node -e \"console.log('Build done');\" ",
 		"deploy-dev": "node wikiploy-dev.mjs",
 		"deploy": "node wikiploy.mjs",
-		"rollout-dev": "npm run build && npm run deploy-dev"
+		"rollout-dev": "npm run build && npm run deploy-dev",
 		"rollout": "npm run build && npm run deploy"
 	},
 	"devDependencies": {
 		"browserify": "17.x",
 		"chai": "4.x",
 		"eslint": "8.x",
+		"less": "4.x",
 		"mocha": "10.x"
 	},
 	"dependencies": {
@@ -64,6 +67,22 @@ function MyGadget() {
 module.exports = { MyGadget };
 ```
 
+Also should also create a starting point for your CSS `src/less/main.less`:
+```css
+@primary-color: darken(#3498db, 10%);
+@secondary-color: darken(#e74c3c, 20%);
+
+.yourGadgetName {
+    background-color: @primary-color;
+    color: white;
+
+	.header {
+		background-color: @secondary-color;
+		text-align: center;
+	}
+}
+```
+
 Remember to install tools after changing `package.json`:
 ```bash
 npm i
@@ -94,12 +113,13 @@ Add `.vscode/extensions.json` to help install a set of **extensions**:
 VSC **settings** `.vscode/settings.json`:
 ```js
 {
+    "editor.detectIndentation": false,
+    "editor.useTabStops": true,
+    "editor.insertSpaces": false,
 	"search.exclude": {
 		"package-lock.json": true,
+		"**/dist/": true,
 	},
-	"editor.detectIndentation": false,
-	"editor.useTabStops": true,
-	"editor.insertSpaces": false,
 }
 ```
 
@@ -238,37 +258,64 @@ export const username = 'Nux@Wikiploy';
 export const password = '0abc...fckgw';
 ```
 
+Your **common deployment script** `wikiploy-common.mjs`:
+```js
+import { DeployConfig, userPrompt } from 'wikiploy';
+
+/**
+ * Add config.
+ * @param {Array} configs DeployConfig array.
+ * @param {String} site Domian of a MW site.
+ */
+export function addConfig(configs, site) {
+	configs.push(new DeployConfig({
+		src: 'dist/yourGadgetName.js',
+		dst: '~/yourGadgetName.js',
+		site,
+		nowiki: true,
+	}));
+	configs.push(new DeployConfig({
+		src: 'dist/yourGadgetName.css',
+		dst: '~/yourGadgetName.css',
+		site,
+	}));
+}
+
+/**
+ * Read and setup summary.
+ * @param {WikiployLite} ployBot 
+ */
+export async function setupSummary(ployBot) {
+	const summary = await userPrompt('Summary of changes (empty for default summary):');
+	if (typeof summary === 'string' && summary.length) {
+		ployBot.summary = () => {
+			return summary;
+		};
+	}
+}
+```
+We use a separate file to define common functions, making changes to both release and dev Wikiploy scripts simpler.
+
+Note that `~` in `dst` properties will be replaced with `User:SomeName`, representing the user space of the currently logged-in user (your user space). For more details about this basic code and `DeployConfig` properties, refer to the [Wikiploy rollout example](https://github.com/Eccenux/wikiploy-rollout-example/).
+
 Your minimal **developer deployment script** `wikiploy-dev.mjs`:
 ```js
-import {DeployConfig, WikiployLite, userPrompt} from 'wikiploy';
+import { WikiployLite } from 'wikiploy';
 
-import * as botpass from './bot.config.js';
+import * as botpass from './bot.config.mjs';
 const ployBot = new WikiployLite(botpass);
 
-// default site for DeployConfig
-ployBot.site = "en.wikipedia.org";
+// common deploy function(s)
+import { addConfig, setupSummary } from './wikiploy-common.mjs';
 
 // run asynchronously to be able to wait for results
 (async () => {
 	// custom summary from a prompt
-	const summary = await userPrompt('Summary of changes (empty for default summary):');
-	if (typeof summary === 'string' && summary.length) {
-		ployBot.summary = () => {
-			return summary;
-		}
-	}
+	await setupSummary(ployBot);
 
 	// push out file(s) to wiki
 	const configs = [];
-	configs.push(new DeployConfig({
-		src: 'dist/yourGadetName.js',
-		dst: '~/yourGadetName.js',
-		nowiki: true,
-	}));
-	configs.push(new DeployConfig({
-		src: 'dist/yourGadetName.css',
-		dst: '~/yourGadetName.css',
-	}));
+	addConfig(configs, 'en.wikipedia.org');
 
 	await ployBot.deploy(configs);
 
@@ -278,35 +325,26 @@ ployBot.site = "en.wikipedia.org";
 });
 ```
 
-Note that `~` will be `User:SomeName` so the user space of a currently logged in user (you user space).
-You can omit `dst` and it will default to `dst: '~/${src}'`. More about this basic code and `dst` in the [Wikiploy rollout example](https://github.com/Eccenux/wikiploy-rollout-example/).
-
-Config for your **main deployment script** `wikiploy.mjs`:
+Your **main deployment script** `wikiploy.mjs`:
 ```js
-// [...] (same sa -dev)
+import { WikiployLite } from 'wikiploy';
+
+import * as botpass from './bot.config.mjs';
+const ployBot = new WikiployLite(botpass);
+
+// common deploy function(s)
+import { addConfig, setupSummary } from './wikiploy-common.mjs';
+
+// run asynchronously to be able to wait for results
+(async () => {
+	// custom summary from a prompt
+	await setupSummary(ployBot);
 
 	// push out file(s) to wiki
-	// dev version
 	const configs = [];
-	configs.push(new DeployConfig({
-		src: 'dist/yourGadetName.js',
-		dst: '~/yourGadetName.js',
-		nowiki: true,
-	}));
-	configs.push(new DeployConfig({
-		src: 'dist/yourGadetName.css',
-		dst: '~/yourGadetName.css',
-	}));
-	// gadget
-	configs.push(new DeployConfig({
-		src: 'dist/yourGadetName.js',
-		dst: 'MediaWiki:Gadget-yourGadetName.js',
-		nowiki: true,
-	}));
-	configs.push(new DeployConfig({
-		src: 'dist/yourGadetName.css',
-		dst: 'MediaWiki:Gadget-yourGadetName.css',
-	}));
+	addConfig(configs, 'pl.wikipedia.org');
+	addConfig(configs, 'en.wikipedia.org');
+	addConfig(configs, 'pl.wikisource.org');
 
 	await ployBot.deploy(configs);
 
@@ -316,31 +354,97 @@ Config for your **main deployment script** `wikiploy.mjs`:
 });
 ```
 
-Note: Above is only the config part of the script.
+## Appendix: Release vs dev release
+
+### Deploying as a gadget
+
+There are various ways you could develop gadgets. The most standard way would be to deploy to the `MediaWiki:Gadget-` namespace.
+
+In `wikiploy-common.mjs` add:
+```js
+export function addConfigRelease(configs, site) {
+	configs.push(new DeployConfig({
+		src: 'dist/yourGadgetName.js',
+		dst: 'MediaWiki:Gadget-yourGadgetName.js',
+		site,
+		nowiki: true,
+	}));
+	configs.push(new DeployConfig({
+		src: 'dist/yourGadgetName.css',
+		dst: 'MediaWiki:Gadget-yourGadgetName.css',
+		site,
+	}));
+}
+```
+
+In your main deployment script you could have something like (`wikiploy.mjs`):
+```js
+	// dev version
+	addConfig(configs, 'en.wikipedia.org');
+	// release versions
+	addConfigRelease(configs, 'pl.wikipedia.org');
+	addConfigRelease(configs, 'pl.wikisource.org');
+	addConfigRelease(configs, 'en.wikipedia.org');
+```
+The script doesn't have any limits. However, you do need interface-admin rights to deploy to the `MediaWiki:Gadget-` namespace. So, you might need to use `~/` to deploy to your user-space.
+
+### Release version in your user space
 
-We update both dev and release version above. This will make an empty edit in a dev script if you already deployed it.
+**If you do *not* have interface-admin rights**, the functions could look like this:
 
-Though we only deploy to `site = "en.wikipedia.org"` you could use other configs to deploy to many wikis:
 ```js
-function addConfig(configs, site) {
+export function addConfig(configs, site, isRelease) {
+	let deploymentName = isRelease ? '~/yourGadgetName' : '~/yourGadgetName-dev';
 	configs.push(new DeployConfig({
-		src: 'dist/yourGadetName.js',
-		dst: 'MediaWiki:Gadget-yourGadetName.js',
+		src: 'dist/yourGadgetName.js',
+		dst: `${deploymentName}.js`,
 		site,
 		nowiki: true,
 	}));
 	configs.push(new DeployConfig({
-		src: 'dist/yourGadetName.css',
-		dst: 'MediaWiki:Gadget-yourGadetName.css',
+		src: 'dist/yourGadgetName.css',
+		dst: `${deploymentName}.css`,
 		site,
 	}));
 }
-addConfig(configs, 'pl.wikipedia.org');
-addConfig(configs, 'pl.wikisource.org');
+export function addConfigRelease(configs, site) {
+	addConfig(configs, site, true);
+}
+```
+
+In this case, you have both dev and release versions in your user space. Frankly, this might be the best choice, even if you have admin rights, especially if you use the *loader pattern*.
+
+### Loader pattern for gadgets
+
+Even if you have all administrative rights on a wiki, you might still want to load the main script from a small loader. The **loader pattern** allows you to provide conditions for loading the main script from the gadget file.
+
+The loader pattern is most useful when you want to test specific capabilities of a device and only then load the script. This is how you could load popups (which don't work well on touch devices, i.e., devices that cannot hover).
+
+Example of what `MediaWiki:Gadget-Popups.js` could look like:
+```js
+// only on devices that can hover (not on touch-only, so not on smartphones)
+if (window.matchMedia && !window.matchMedia("(hover: none)").matches) {
+	importScript('User:Nux/Popups.js');
+}
+```
+
+You could also have a gadget that is default, but only works on specific pages:
+```js
+// load config
+var config = mw.config.get( [
+	'wgNamespaceNumber',
+	'wgTitle',
+] );
+// only on AfD subpages
+if ( config.wgNamespaceNumber == 4 && config.wgTitle.startsWith('Articles for deletion/') ) {
+	importScript('User:Nux/AfD-helper.js');
+}
 ```
-The script doesn't have any limits. You do need interface-admin rights to deploy to `MediaWiki:Gadget-` namespace. So you might need to use `~/` instead to deploy to your user-space.
+The loader pattern is beneficial because it improves website performance. In this pattern, the main gadget code is only loaded when it can be useful.
+
+Loading from the `User` namespace might also help make it clear who is responsible for the gadget. However, it might not work when there is no single user responsible, such as when the main author becomes inactive. The community can always decide to fork the script, so that should not be a problem in practice.
 
-## Exporting stuff 
+## Appendix: Exporting stuff 
 
 Note that *browserify* will wrap your code with a function automatically, so you don't have to worry about leaking variables to the global scope (you should still remember to define variables with `var`, `let`, or `const`).
 
@@ -353,14 +457,14 @@ Exposing things in `main.js` could look something like this:
 ```js
 var { MyGadget } = require("./MyGadget");
 
-// bot instance
+// instance
 var gadget = new MyGadget();
 
 // expose for external usage (*not* recommended)
-window.yourGadetName = gadget;
+window.yourGadgetName = gadget;
 
 // hook when object is ready
-mw.hook('userjs.yourGadetName.loaded').fire(gadget);
+mw.hook('userjs.yourGadgetName.loaded').fire(gadget);
 
 $(function(){
 	// load Mediwiki core dependency
@@ -369,7 +473,7 @@ $(function(){
 		gadget.init();
 
 		// hook when initial elements are ready 
-		mw.hook('userjs.yourGadetName.ready').fire(gadget);
+		mw.hook('userjs.yourGadgetName.ready').fire(gadget);
 	});
 });
 ```
@@ -378,20 +482,20 @@ As you can see, hooks are better because you can keep the name of the variable s
 
 User options:
 ```js
-mw.hook('userjs.yourGadetName.loaded').add(function (gadget) {
+mw.hook('userjs.yourGadgetName.loaded').add(function (gadget) {
 	gadget.options.createTool = false;
 });
-importScript('User:Nux/yourGadetName.js');
+importScript('User:Nux/yourGadgetName.js');
 ```
 A more advanced customization:
 ```js
-mw.hook('userjs.yourGadetName.ready').add(function (gadget) {
-	var $tool = $('#some-unique-gadet-tool a');
+mw.hook('userjs.yourGadgetName.ready').add(function (gadget) {
+	var $tool = $('#some-unique-gadget-tool a');
 	$tool.text($tool.text() + ' & plugin');
 });
 ```
 
-## Using classes
+## Appendix: Using classes
 
 JS has classes for a long time. They don't work in IE and you cannot use them in default gadgets on Wikipedia. If you are building a default gadget you might want to add [babeljs](https://babeljs.io/) as a build step.
 ```bash
@@ -404,12 +508,20 @@ browserify script.js -t babelify --outfile bundle.js
 If the gadget is intended for advanced users it is safe to assume they won't use IE. So for most scripts you can probably skip babelify. But as of 2023 you will need `requiresES6` option in the gadget definition.
 
 ```
-yourClassyGadetName [ResourceLoader | requiresES6 | dependencies = mediawiki.util] | yourGadetName.js | yourGadetName.css
+yourClassyGadgetName [ResourceLoader | requiresES6 | dependencies = mediawiki.util] | yourGadgetName.js | yourGadgetName.css
 ```
 
 
 Example `MyGadget.js` with a link in the toolbar:
 ```js
+/**
+ * Wikiploy gadget example.
+ * 
+ * History and docs:
+ * https://github.com/Eccenux/wikiploy-rollout-example
+ * 
+ * Deployed using: [[Wikipedia:Wikiploy]]
+ */
 class MyGadget {
 	constructor() {
 		this.options = {
@@ -425,9 +537,9 @@ class MyGadget {
 			var linkLabel = 'My gadget dialog';
 			var itemId = 'some-unique-gadget-tool';
 			var item = mw.util.addPortletLink(portletId, '#', linkLabel, itemId);
-			$(item).on('click', function (evt) {
+			$(item).on('click', (evt) => {
 				evt.preventDefault();
-				gadget.openDialog();
+				this.openDialog();
 			});
 		}
 	}

package/README.md

@@ -52,7 +52,7 @@ The `WikiployLite` class is using a bot API to deploy scripts. You can use stand
 Botpass configuration:
 * Setup on e.g.: https://test.wikipedia.org/wiki/Special:BotPasswords
 * Rights you should setup (if you can): `assets\Bot passwords - Test Wikipedia.png`.
-* Example config file in: `assets\bot.config.public.js`.
+* Example config file in: `assets\public--bot.config.mjs`.
 
 **Warning!** Never, ever publish your bot password. If you do spill your password, reset/remove the password ASAP (on Special:BotPasswords).
 

package/assets/test.css

@@ -5,4 +5,4 @@
 .tavern {
 	display: block;
 }
-/* puppeteer 21.6.1 xor mwn 2.0.2 */
+/* puppeteer 21.7.0 xor mwn 2.0.2 */

package/assets/test.js

@@ -7,4 +7,4 @@
  */
 // test.js
 console.log('test');
-/* puppeteer 21.6.1 xor mwn 2.0.2 */
+/* puppeteer 21.7.0 xor mwn 2.0.2 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wikiploy",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "User scripts and gadgets deployment for MediaWiki (Wikipedia).",
   "main": "src/index.js",
   "type": "module",
@@ -27,7 +27,7 @@
   "homepage": "https://github.com/Eccenux/Wikiploy#readme",
   "dependencies": {
     "mwn": "2.0.x",
-    "puppeteer": "21.6.x"
+    "puppeteer": "21.7.x"
   },
   "devDependencies": {
     "bump-version": "0.5.0",

package/src/ploy_test_botapi.js

@@ -7,7 +7,7 @@ import * as ver from './version.js';
 
 // https://test.wikipedia.org/wiki/Special:BotPasswords
 // Note that username should contain `@`.
-import * as botpass from './bot.config.js';
+import * as botpass from './bot.config.mjs';
 
 const version = await ver.readVersion('./package.json');
 

package/src/ploy_test_lite.js

@@ -3,7 +3,7 @@ import WikiployLite from './WikiployLite.js';
 
 // https://test.wikipedia.org/wiki/Special:BotPasswords
 // Note that username should contain `@`.
-import * as botpass from './bot.config.js';
+import * as botpass from './bot.config.mjs';
 
 const ployBot = new WikiployLite(botpass);
 // mock