nodebb-plugin-fab-cards 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 NodeBB Inc. <sales@nodebb.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,52 +1,17 @@
-# nodebb-plugin-fab-cards
+# Quickstart Plugin for NodeBB
 
-A NodeBB plugin that automatically detects mentions of Flesh and Blood card names in posts, converts them into links to the official FAB card database, and shows a card image preview on hover/touch.
+A starter kit for quickly creating NodeBB plugins. Comes with a pre-setup SCSS file, server side JS script with an `static:app.load` hook, and a client-side script. Most plugins need at least one of the above, so this ought to save you some time. For a full list of hooks have a look at our [wiki page](https://github.com/NodeBB/NodeBB/wiki/Hooks), and for more information about creating plugins please visit our [documentation portal](https://docs.nodebb.org/).
 
-## Features
+Fork this or copy it, and using your favourite text editor find and replace all instances of `nodebb-plugin-fab-cards` with `nodebb-plugin-your-plugins-name`. Change the author's name in the LICENSE and package.json files.
 
-- Detects known card names in parsed post content
-- Converts matches to links such as `https://cards.fabtcg.com/card/command-and-conquer-1/`
-- Opens links in a new tab
-- Shows preview image on hover (desktop) and first touch (mobile)
-- Uses a static generated card index (`data/cards-index.json`) for fast runtime lookups
+## Hello World
 
-## Card data generation
+Really simple, just edit `public/lib/main.js` and paste in `console.log('hello world');`, and that's it!
 
-The plugin uses:
+## Installation
 
-- API endpoint: `https://cards.fabtcg.com/api/search/v1/cards/?`
-- Build script: `scripts/build-card-index.js`
+    npm install nodebb-plugin-fab-cards
 
-Generate/update the card index:
+## Screenshots
 
-```bash
-npm install
-npm run build:cards
-```
-
-## Installation in NodeBB
-
-In your plugin folder:
-
-```bash
-npm link
-```
-
-In your NodeBB folder:
-
-```bash
-npm link nodebb-plugin-fab-cards
-./nodebb build
-```
-
-Then activate `FAB Cards Auto-Link` in ACP (`/admin/extend/plugins`).
-
-## Local development NodeBB setup
-
-A local setup guide is included in [dev/README.md](dev/README.md).
-
-## Notes
-
-- The parser only transforms posts for `type=default` rendering.
-- Existing links/code blocks are ignored to avoid corrupting content.
-- Re-run `npm run build:cards` periodically to refresh card data.
+Don't forget to add screenshots!

package/commitlint.config.js

@@ -0,0 +1,26 @@
+'use strict';
+
+module.exports = {
+	extends: ['@commitlint/config-angular'],
+	rules: {
+		'header-max-length': [1, 'always', 72],
+		'type-enum': [
+			2,
+			'always',
+			[
+				'breaking',
+				'build',
+				'chore',
+				'ci',
+				'docs',
+				'feat',
+				'fix',
+				'perf',
+				'refactor',
+				'revert',
+				'style',
+				'test',
+			],
+		],
+	},
+};

package/eslint.config.mjs

@@ -0,0 +1,10 @@
+'use strict';
+
+import serverConfig from 'eslint-config-nodebb';
+import publicConfig from 'eslint-config-nodebb/public';
+
+export default [
+	...publicConfig,
+	...serverConfig,
+];
+

package/languages/de/quickstart.json

@@ -0,0 +1,3 @@
+{
+	"info": "Dies ist eine Übersetzungszeichenkette, sie wird in die Sprache des Benutzers übersetzt. Siehe den Ordner 'languages' im Stammverzeichnis dieses Plugins."
+}

package/languages/en-GB/quickstart.json

@@ -0,0 +1,3 @@
+{
+	"info": "This is a translation string, it gets translated to the users language. See the languages folder in the root of this plugin."
+}

package/languages/en-US/quickstart.json

@@ -0,0 +1,3 @@
+{
+	"info": "This is a translation string, it gets translated to the users language. See the languages folder in the root of this plugin."
+}

package/lib/controllers.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const Controllers = module.exports;
+
+Controllers.renderAdminPage = function (req, res/* , next */) {
+	/*
+		Make sure the route matches your path to template exactly.
+
+		If your route was:
+			myforum.com/some/complex/route
+		your template should be:
+			templates/some/complex/route.tpl
+		and you would render it like so:
+			res.render('some/complex/route');
+	*/
+
+	res.render('admin/plugins/quickstart', {
+		title: 'Quick Start',
+	});
+};

package/library.js

@@ -1,135 +1,88 @@
 'use strict';
 
-const path = require('path');
-const cheerio = require('cheerio');
+const nconf = require.main.require('nconf');
+const winston = require.main.require('winston');
 
-const CARD_INDEX_PATH = path.join(__dirname, 'data', 'cards-index.json');
-const CARD_HOST = 'https://cards.fabtcg.com';
+const meta = require.main.require('./src/meta');
 
-let cardData = null;
-let cardMatcher = null;
+const controllers = require('./lib/controllers');
 
-function loadCardData() {
-  if (cardData) {
-    return cardData;
-  }
-
-  cardData = require(CARD_INDEX_PATH);
-  const cardNames = Object.keys(cardData.cards || {});
-
-  if (!cardNames.length) {
-    cardMatcher = null;
-    return cardData;
-  }
-
-  const escaped = cardNames
-    .sort((first, second) => second.length - first.length)
-    .map(escapeRegExp);
-
-  cardMatcher = new RegExp(`(^|[^\\p{L}\\p{N}])(${escaped.join('|')})(?=$|[^\\p{L}\\p{N}])`, 'giu');
-  return cardData;
-}
-
-function normalize(input) {
-  return String(input || '')
-    .normalize('NFKC')
-    .toLowerCase()
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function escapeHtml(value) {
-  return String(value)
-    .replace(/&/g, '&')
-    .replace(/"/g, '"')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
-}
-
-function shouldSkipNode(node) {
-  const parentTag = node.parent && node.parent.tagName ? node.parent.tagName.toLowerCase() : '';
-  return ['a', 'code', 'pre', 'script', 'style', 'textarea'].includes(parentTag);
-}
-
-export function linkifyText(text, cards) {
-if (!cardMatcher || !text || !text.trim()) {
-    return text;
-  }
-
-  cardMatcher.lastIndex = 0;
-  return text.replace(cardMatcher, (fullMatch, prefix, cardName) => {
-    const normalized = normalize(cardName);
-    const card = cards[normalized];
-
-    if (!card) {
-      return fullMatch;
-    }
-
-    const href = `${CARD_HOST}${card.url}`;
-    const safeName = escapeHtml(card.name || cardName);
-    const safeImage = escapeHtml(card.image || '');
-    const safeHref = escapeHtml(href);
-
-    return `${prefix}<a class="fab-card-link" href="${safeHref}" target="_blank" rel="noopener noreferrer" data-fab-card-name="${safeName}" data-fab-card-image="${safeImage}">${cardName}</a>`;
-  });
-}
-
-function processNode($, node, cards) {
-  if (!node) {
-    return;
-  }
-
-  if (node.type === 'text' && !shouldSkipNode(node)) {
-    const original = node.data || '';
-    const replaced = linkifyText(original, cards);
-    if (replaced !== original) {
-      $(node).replaceWith(replaced);
-    }
-    return;
-  }
-
-  if (node.children && node.children.length) {
-    node.children.slice().forEach((child) => processNode($, child, cards));
-  }
-}
+const routeHelpers = require.main.require('./src/routes/helpers');
 
 const plugin = {};
 
-plugin.parsePost = async function (payload) {
-  const data = payload || {};
-  const carrier = data.postData && typeof data.postData.content === 'string'
-    ? data.postData
-    : (typeof data.content === 'string' ? data : null);
-
-  if (!carrier || !carrier.content) {
-    return payload;
-  }
-
-  const type = data.type || data.postData?.type || 'default';
-  if (type !== 'default') {
-    return payload;
-  }
-
-  const loaded = loadCardData();
-  if (!loaded || !loaded.cards || !cardMatcher) {
-    return payload;
-  }
+plugin.init = async (params) => {
+	const { router /* , middleware , controllers */ } = params;
+
+	// Settings saved in the plugin settings can be retrieved via settings methods
+	const { setting1, setting2 } = await meta.settings.get('quickstart');
+	if (setting1) {
+		console.log(setting2);
+	}
+
+	/**
+	 * We create two routes for every view. One API call, and the actual route itself.
+	 * Use the `setupPageRoute` helper and NodeBB will take care of everything for you.
+	 *
+	 * Other helpers include `setupAdminPageRoute` and `setupAPIRoute`
+	 * */
+	routeHelpers.setupPageRoute(router, '/quickstart', [(req, res, next) => {
+		winston.info(`[plugins/quickstart] In middleware. This argument can be either a single middleware or an array of middlewares`);
+		setImmediate(next);
+	}], (req, res) => {
+		winston.info(`[plugins/quickstart] Navigated to ${nconf.get('relative_path')}/quickstart`);
+		res.render('quickstart', { uid: req.uid });
+	});
+
+	routeHelpers.setupAdminPageRoute(router, '/admin/plugins/quickstart', controllers.renderAdminPage);
+};
 
-  const $ = cheerio.load(carrier.content, {
-    decodeEntities: false,
-  }, false);
+/**
+ * If you wish to add routes to NodeBB's RESTful API, listen to the `static:api.routes` hook.
+ * Define your routes similarly to above, and allow core to handle the response via the
+ * built-in helpers.formatApiResponse() method.
+ *
+ * In this example route, the `ensureLoggedIn` middleware is added, which means a valid login
+ * session or bearer token (which you can create via ACP > Settings > API Access) needs to be
+ * passed in.
+ *
+ * To call this example route:
+ *   curl -X GET \
+ *     http://example.org/api/v3/plugins/quickstart/test \
+ *     -H "Authorization: Bearer some_valid_bearer_token"
+ *
+ * Will yield the following response JSON:
+ * {
+ *  "status": {
+ *    "code": "ok",
+ *    "message": "OK"
+ *  },
+ *  "response": {
+ *    "foobar": "test"
+ *  }
+ * }
+ */
+plugin.addRoutes = async ({ router, middleware, helpers }) => {
+	const middlewares = [
+		middleware.ensureLoggedIn, // use this if you want only registered users to call this route
+		// middleware.admin.checkPrivileges, // use this to restrict the route to administrators
+	];
+
+	routeHelpers.setupApiRoute(router, 'get', '/quickstart/:param1', middlewares, (req, res) => {
+		helpers.formatApiResponse(200, res, {
+			foobar: req.params.param1,
+		});
+	});
+};
 
-  const root = $.root().get(0);
-  if (root && root.children) {
-    root.children.slice().forEach((child) => processNode($, child, loaded.cards));
-  }
+plugin.addAdminNavigation = (header) => {
+	header.plugins.push({
+		route: '/plugins/quickstart',
+		icon: 'fa-tint',
+		name: 'Quickstart',
+	});
 
-  carrier.content = $.root().html() || carrier.content;
-  return payload;
+	return header;
 };
 
 module.exports = plugin;

package/package.json

@@ -1,32 +1,49 @@
 {
   "name": "nodebb-plugin-fab-cards",
-  "version": "0.1.0",
-  "description": "Auto-link Flesh and Blood card names in NodeBB posts with hover/touch previews.",
+  "version": "0.1.2",
+  "description": "A starter kit for quickly creating NodeBB plugins",
   "main": "library.js",
-  "scripts": {
-    "build:cards": "node scripts/build-card-index.js"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodebb/nodebb-plugin-fab-cards"
   },
   "keywords": [
     "nodebb",
-    "nodebb-plugin",
-    "flesh-and-blood",
-    "fab"
+    "plugin",
+    "quickstart",
+    "shell"
   ],
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged",
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+    }
+  },
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix",
+      "git add"
+    ]
+  },
   "license": "MIT",
-  "dependencies": {
-    "cheerio": "^1.0.0"
+  "bugs": {
+    "url": "https://github.com/nodebb/nodebb-plugin-fab-cards/issues"
   },
+  "readmeFilename": "README.md",
   "nbbpm": {
-    "compatibility": "^4.0.0"
-  },
-  "devDependencies": {},
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/braaar/nodebb-plugin-fab-cards.git"
+    "compatibility": "^3.2.0"
   },
   "author": "braaar",
-  "bugs": {
-    "url": "https://github.com/braaar/nodebb-plugin-fab-cards/issues"
+  "homepage": "https://github.com/braaar/nodebb-plugin-fab-cards#readme",
+  "devDependencies": {
+    "@commitlint/cli": "20.4.2",
+    "@commitlint/config-angular": "20.4.2",
+    "eslint": "10.0.1",
+    "eslint-config-nodebb": "2.0.1",
+    "husky": "9.1.7",
+    "lint-staged": "16.2.7"
   },
-  "homepage": "https://github.com/braaar/nodebb-plugin-fab-cards#readme"
-}
+  "scripts": {
+    "lint": "eslint ."
+  }
+}

package/plugin.json

@@ -1,18 +1,22 @@
 {
   "id": "nodebb-plugin-fab-cards",
-  "name": "FAB Cards Auto-Link",
-  "description": "Automatically links Flesh and Blood card names and shows card previews.",
-  "url": "https://github.com/fabtcg/nodebb-plugin-fab-cards",
+  "url": "https://github.com/NodeBB/nodebb-plugin-fab-cards",
   "library": "./library.js",
   "hooks": [
-    {
-      "hook": "filter:parse.post",
-      "method": "parsePost"
-    }
+    { "hook": "static:app.load", "method": "init" },
+    { "hook": "static:api.routes", "method": "addRoutes" },
+    { "hook": "filter:admin.header.build", "method": "addAdminNavigation" }
   ],
   "staticDirs": {
-    "public": "public"
+    "static": "./static"
   },
-  "scripts": ["public/lib/client.js"],
-  "css": ["public/css/style.css"]
+  "scss": ["scss/quickstart.scss"],
+  "scripts": ["public/lib/main.js"],
+  "acpScripts": ["public/lib/acp-main.js"],
+  "modules": {
+    "../client/quickstart.js": "./public/lib/quickstart.js",
+    "../admin/plugins/quickstart.js": "./public/lib/admin.js"
+  },
+  "templates": "templates",
+  "languages": "languages"
 }

package/public/lib/acp-main.js

@@ -0,0 +1,18 @@
+'use strict';
+
+$(document).ready(function () {
+	/*
+		This file shows how admin page client-side javascript can be included via a plugin.
+		If you check `plugin.json`, you'll see that this file is listed under "acpScripts".
+		That array tells NodeBB which files to bundle into the minified javascript
+		that is served to the end user.
+
+		Some events you can elect to listen for:
+
+		$(document).ready(); Fired when the DOM is ready
+		$(window).on('action:ajaxify.end', function(data) { ... }); "data" contains "url"
+	*/
+
+	console.log('nodebb-plugin-fab-cards: acp-loaded');
+	// Note how this is shown in the console on the first load of every page in the ACP
+});

package/public/lib/admin.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/*
+	This file is located in the "modules" block of plugin.json
+	It is only loaded when the user navigates to /admin/plugins/quickstart page
+	It is not bundled into the min file that is served on the first load of the page.
+*/
+
+import { save, load } from 'settings';
+import * as uploader from 'uploader';
+
+export function init() {
+	handleSettingsForm();
+	setupUploader();
+};
+
+function handleSettingsForm() {
+	load('quickstart', $('.quickstart-settings'), function () {
+		setupColorInputs();
+	});
+
+	$('#save').on('click', () => {
+		save('quickstart', $('.quickstart-settings')); // pass in a function in the 3rd parameter to override the default success/failure handler
+	});
+}
+
+function setupColorInputs() {
+	var colorInputs = $('[data-settings="colorpicker"]');
+	colorInputs.on('change', updateColors);
+	updateColors();
+}
+
+function updateColors() {
+	$('#preview').css({
+		color: $('#color').val(),
+		'background-color': $('#bgColor').val(),
+	});
+}
+
+function setupUploader() {
+	$('#content input[data-action="upload"]').each(function () {
+		var uploadBtn = $(this);
+		uploadBtn.on('click', function () {
+			uploader.show({
+				route: config.relative_path + '/api/admin/upload/file',
+				params: {
+					folder: 'quickstart',
+				},
+				accept: 'image/*',
+			}, function (image) {
+				$('#' + uploadBtn.attr('data-target')).val(image);
+			});
+		});
+	});
+}

package/public/lib/main.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * This file shows how client-side javascript can be included via a plugin.
+ * If you check `plugin.json`, you'll see that this file is listed under "scripts".
+ * That array tells NodeBB which files to bundle into the minified javascript
+ * that is served to the end user.
+ *
+ * There are two (standard) ways to wait for when NodeBB is ready.
+ * This one below executes when NodeBB reports it is ready...
+ */
+
+(async () => {
+	const hooks = await app.require('hooks');
+
+	hooks.on('action:app.load', () => {
+		// called once when nbb has loaded
+		console.log('hello fab!');
+	});
+
+	hooks.on('action:ajaxify.end', (/* data */) => {
+		// called everytime user navigates between pages including first load
+	});
+})();
+
+/**
+ * ... and this one reports when the DOM is loaded (but NodeBB might not be fully ready yet).
+ * For most cases, you'll want the one above.
+ */
+
+$(document).ready(function () {
+	// ...
+});

package/public/lib/quickstart.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/*
+	This file is located in the "modules" block of plugin.json
+	It is only loaded when the user navigates to /quickstart page
+	It is not bundled into the min file that is served on the first load of the page.
+*/
+
+define('forum/quickstart', function () {
+	var module = {};
+	module.init = function () {
+		$('#last-p').text('quickstart.js loaded!');
+	};
+	return module;
+});

package/renovate.json

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "config:recommended"
+  ]
+}

package/scss/quickstart.scss

@@ -0,0 +1 @@
+/* Place any SASS in here */

package/static/samplefile.html

@@ -0,0 +1,8 @@
+<h1>Hello!</h1>
+
+<p>
+  This file is served by nodebb at
+  domain.com/assets/plugins/nodebb-plugin-fab-cards/static/samplefile.html
+</p>
+
+Check plugin.json for the "staticDirs" property if you want to change the path.

package/templates/admin/plugins/quickstart/partials/sorted-list/form.tpl

@@ -0,0 +1,10 @@
+<form>
+    <div class="mb-3">
+        <label class="form-label" for="name">Name</label>
+        <input type="text" id="name" name="name" class="form-control" placeholder="Name" />
+    </div>
+    <div class="mb-3">
+        <label class="form-label" for="description">Description</label>
+        <input type="text" id="description" name="description" class="form-control" placeholder="Description" />
+    </div>
+</form>

package/templates/admin/plugins/quickstart/partials/sorted-list/item.tpl

@@ -0,0 +1,12 @@
+<li data-type="item" class="list-group-item">
+    <div class="d-flex gap-2 justify-content-between align-items-start">
+        <div class="flex-grow-1">
+            <strong>{name}</strong><br />
+            <small>{description}</small>
+        </div>
+        <div class="d-flex gap-1 flex-nowrap">
+            <button type="button" data-type="edit" class="btn btn-sm btn-info">Edit</button>
+            <button type="button" data-type="remove" class="btn btn-sm btn-danger">Delete</button>
+        </div>
+    </div>
+</li>