Document plugins to be used by integrators

Signed-off-by: Julius Härtl <jus@bitgrid.net>

2 files changed, 112 insertions, 32 deletions

diff --git a/apps/workflowengine/src/components/Values/file.js b/apps/workflowengine/src/components/Values/file.js
new file mode 100644
index 00000000000..4a473dbc13c
--- /dev/null
+++ b/apps/workflowengine/src/components/Values/file.js
@@ -0,0 +1,67 @@
+/*
+ * @copyright Copyright (c) 2019 Julius Härtl <jus@bitgrid.net>
+ *
+ * @author Julius Härtl <jus@bitgrid.net>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+import './../../legacy/filenameplugin'
+import './../../legacy/filesystemtagsplugin'
+import './../../legacy/requestremoteaddressplugin'
+import './../../legacy/requesttimeplugin'
+import './../../legacy/requesturlplugin'
+import './../../legacy/requestuseragentplugin'
+import './../../legacy/usergroupmembershipplugin'
+
+import FileMimeType from './FileMimeType';
+import SizeValue from './SizeValue';
+
+const FileChecks = Object.values(OCA.WorkflowEngine.Plugins).map((plugin) => {
+	if (plugin.component) {
+		return { ...plugin.getCheck(), component: plugin.component() }
+	}
+	return plugin.getCheck()
+})
+
+
+// new way of registering checks
+FileChecks.push({
+	class: 'OCA\\WorkflowEngine\\Check\\FileMimeType',
+	name: t('workflowengine', 'File MIME type'),
+	operators: [
+		{ operator: 'is', name: t('workflowengine', 'is') },
+		{ operator: '!is', name: t('workflowengine', 'is not') },
+		{ operator: 'matches', name: t('workflowengine', 'matches') },
+		{ operator: '!matches', name: t('workflowengine', 'does not match') }
+	],
+	component: FileMimeType
+})
+
+FileChecks.push({
+	class: 'OCA\\WorkflowEngine\\Check\\FileSize',
+	name: t('workflowengine', 'File size (upload)'),
+	operators: [
+		{ operator: 'less', name: t('workflowengine', 'less') },
+		{ operator: '!greater', name: t('workflowengine', 'less or equals') },
+		{ operator: '!less', name: t('workflowengine', 'greater or equals') },
+		{ operator: 'greater', name: t('workflowengine', 'greater') }
+	],
+	component: SizeValue
+})
+
+export default FileChecks
diff --git a/apps/workflowengine/src/workflowengine.js b/apps/workflowengine/src/workflowengine.js
index bdf30397883..6e22852b829 100644
--- a/apps/workflowengine/src/workflowengine.js
+++ b/apps/workflowengine/src/workflowengine.js
@@ -1,50 +1,63 @@
-import './legacy/filemimetypeplugin'
-import './legacy/filenameplugin'
-import './legacy/filesizeplugin'
-import './legacy/filesystemtagsplugin'
-import './legacy/requestremoteaddressplugin'
-import './legacy/requesttimeplugin'
-import './legacy/requesturlplugin'
-import './legacy/requestuseragentplugin'
-import './legacy/usergroupmembershipplugin'
-
 import Vue from 'vue'
 import Vuex from 'vuex'
-
 import store from './store'
 
 import Settings from './components/Workflow'
-import FileMimeType from './components/Values/FileMimeType';
+import FileValues from './components/Values/file'
+
+/**
+ * A plugin for displaying a custom value field for checks
+ *
+ * @typedef {Object} CheckPlugin
+ * @property {string} class - The PHP class name of the check
+ * @property {Comparison[]} operators - A list of possible comparison operations running on the check
+ * @property {Vue} component - A vue component to handle the rendering of options
+ * 	The component should handle the v-model directive properly,
+ * 	so it needs a value property to receive data and emit an input
+ * 	event once the data has changed
+ **/
+
+/**
+ * A plugin for extending the admin page repesentation of a operator
+ *
+ * @typedef {Object} OperatorPlugin
+ * @property {string} class - The PHP class name of the check
+ * @property {string} operation - Default value for the operation field
+ * @property {string} color - Custom color code to be applied for the operator selector
+ * @property {Vue} component - A vue component to handle the rendering of options
+ * 	The component should handle the v-model directive properly,
+ * 	so it needs a value property to receive data and emit an input
+ * 	event once the data has changed
+ */
 
+/**
+ * @typedef {Object} Comparison
+ * @property {string} operator - value the comparison should have, e.g. !less, greater
+ * @property {string} name - Translated readable text, e.g. less or equals
+ **/
+
+/**
+ * Public javascript api for apps to register custom plugins
+ */
 window.OCA.WorkflowEngine = Object.assign({}, OCA.WorkflowEngine, {
+	/**
+	 *
+	 * @param {CheckPlugin} Plugin
+	 */
 	registerCheck: function (Plugin) {
 		store.commit('addPluginCheck', Plugin)
 	},
+	/**
+	 *
+	 * @param {OperatorPlugin} Plugin
+	 */
 	registerOperator: function (Plugin) {
 		store.commit('addPluginOperator', Plugin)
 	}
 })
 
-// Load legacy plugins for now and register them in the new plugin system
-Object.values(OCA.WorkflowEngine.Plugins).map((plugin) => {
-	if (plugin.component) {
-		return { ...plugin.getCheck(), component: plugin.component() }
-	}
-	return plugin.getCheck()
-}).forEach((legacyCheckPlugin) => window.OCA.WorkflowEngine.registerCheck(legacyCheckPlugin))
-
-// new way of registering checks
-window.OCA.WorkflowEngine.registerCheck({
-	class: 'OCA\\WorkflowEngine\\Check\\FileMimeType',
-	name: t('workflowengine', 'File MIME type'),
-	operators: [
-		{ operator: 'is', name: t('workflowengine', 'is') },
-		{ operator: '!is', name: t('workflowengine', 'is not') },
-		{ operator: 'matches', name: t('workflowengine', 'matches') },
-		{ operator: '!matches', name: t('workflowengine', 'does not match') }
-	],
-	component: FileMimeType
-})
+// Register shipped checks for file entity
+FileValues.forEach((checkPlugin) => window.OCA.WorkflowEngine.registerCheck(checkPlugin))
 
 Vue.use(Vuex)
 Vue.prototype.t = t