rahix/openflexure-microscope-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Plugin schema are now just plugin forms (requires eV 1.2)

Browse source
This commit is contained in:
Joel Collins 2019-09-14 15:51:51 +01:00
parent 0d7a5f71e0
commit d9e07f913a
16 changed files with 106 additions and 98 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/source/plugins.rst
View file

@ -8,6 +8,6 @@ Developing Plugins
./plugins/structure.rst
./plugins/routes.rst
./plugins/hardware.rst
./plugins/schema.rst
./plugins/form.rst
./plugins/example.rst
./plugins/class.rst

4
docs/source/plugins/example.rst
View file

@ -7,10 +7,10 @@ plugin.py
.. literalinclude:: example/plugin.py
:language: python
schema.json
form.json
+++++++++++
.. literalinclude:: example/schema.json
.. literalinclude:: example/form.json
:language: JSON
Notes

4
docs/source/plugins/example/schema.json → docs/source/plugins/example/forms.json
View file

@ -7,7 +7,7 @@
"isTask": false,
"selfUpdate": true,
"route": "/hello",
"schema": [
"form": [
{
"fieldType": "textInput",
"placeholder": "Enter a string",
@ -21,7 +21,7 @@
"isTask": true,
"route": "/timelapse",
"submitLabel": "Start timelapse",
"schema": [
"form": [
{
"fieldType": "numberInput",
"name": "n_images",

8
docs/source/plugins/example/plugin.py
View file

@ -9,7 +9,7 @@ import json
from flask import request, Response, escape, jsonify
HERE = os.path.dirname(os.path.realpath(__file__))
SCHEMA_PATH = os.path.join(HERE, "schema.json")
FORM_PATH = os.path.join(HERE, "forms.json")
### MICROSCOPE PLUGIN ###
@ -18,10 +18,10 @@ class MyPluginClass(MicroscopePlugin):
A set of default plugins
"""
global SCHEMA_PATH
global FORM_PATH
with open(SCHEMA_PATH, 'r') as sc:
api_schema = json.load(sc)
with open(FORM_PATH, 'r') as sc:
api_form = json.load(sc)
api_views = {
'/identify': IdentifyAPI,

26
docs/source/plugins/schema.rst → docs/source/plugins/forms.rst
View file

@ -4,39 +4,39 @@ Adding a GUI
Introduction
------------
In order to bind user-interface elements to your plugin, an ``api_schema`` variable must be included in your microscope plugin, similar to your ``api_views``.
In order to bind user-interface elements to your plugin, an ``api_form`` variable must be included in your microscope plugin, similar to your ``api_views``.
This variable must be in the form of a dictionary, with all data able to be parsed into JSON. Because of this requirement, it is suggested that you create your API schema as a JSON file, and load that file as a dictionary into your plugin. For example:
This variable must be in the form of a dictionary, with all data able to be parsed into JSON. Because of this requirement, it is suggested that you create your API form as a JSON file, and load that file as a dictionary into your plugin. For example:
.. code-block:: python
import json
HERE = os.path.dirname(os.path.realpath(__file__)) # Find the full path of your plugin Python file
SCHEMA_PATH = os.path.join(HERE, "schema.json") # Find the full path of the adjascent JSON file
FORM_PATH = os.path.join(HERE, "form.json") # Find the full path of the adjascent JSON file
class MyPluginClass(MicroscopePlugin):
with open(SCHEMA_PATH, 'r') as sc: # Open the JSON file
api_schema = json.load(sc) # Load the JSON file into the api_schema dictionary
with open(FORM_PATH, 'r') as sc: # Open the JSON file
api_form = json.load(sc) # Load the JSON file into the api_form dictionary
Throughout this documentation, all example of ``api_schema`` sections will be in JSON format. Keep in mind however that it is possible to directly define your ``api_schema`` as a dictionary, without loading an external file.
Throughout this documentation, all example of ``api_form`` sections will be in JSON format. Keep in mind however that it is possible to directly define your ``api_form`` as a dictionary, without loading an external file.
Forms from ``api_schema``
Forms from ``api_form``
-------------------------
The ``api_schema`` object essentially describes HTML forms, which it is up to the client to render. The form is constructed by specifying a set of components, and their values. A form can update it's values by sending a GET request to the API route bound to that form, and can send it's current values via a POST request to *this same API route*.
The ``api_form`` object essentially describes HTML forms, which it is up to the client to render. The form is constructed by specifying a set of components, and their values. A form can update it's values by sending a GET request to the API route bound to that form, and can send it's current values via a POST request to *this same API route*.
Each component in the form has a ``name`` property, which must match up to a property your API route expects in JSON POST requests, and returns in JSON GET requests.
Structure of ``api_schema``
Structure of ``api_form``
---------------------------
Root level
++++++++++
The root of your ``api_schema`` expects 3 properties:
The root of your ``api_form`` expects 3 properties:
``id`` - A unique ID to give your client-side plugin
@ -61,7 +61,7 @@ Each form is described by a JSON object, with the following properties:
``submitLabel`` *(optional)* - String to place inside of the form's submit button
``schema`` - An array of form components as described below
``form`` - An array of form components as described below
Component level
+++++++++++++++
@ -182,11 +182,11 @@ Overview of components
JSON form example
-----------------
.. literalinclude:: schema_example.json
.. literalinclude:: forms_example.json
:language: JSON
.. toctree::
:maxdepth: 1
./schema/json_schema.rst
./form/json_form.rst

4
docs/source/plugins/schema_example.json → docs/source/plugins/forms_example.json
View file

@ -9,7 +9,7 @@
"selfUpdate": true,
"route": "/do",
"submitLabel": "Do things",
"schema": [
"form": [
{
"fieldType": "numberInput",
"placeholder": "Some integer",
@ -75,7 +75,7 @@
"selfUpdate": true,
"route": "/task",
"submitLabel": "Start task",
"schema": [
"form": [
{
"fieldType": "numberInput",
"name": "run_time",

4
docs/source/plugins/schema/json_schema.rst
View file

@ -1,5 +1,5 @@
Full JSON Schema
Full JSON Form
================
.. literalinclude:: schema.json
.. literalinclude:: form.json
:language: JSON

34
docs/source/plugins/schema/schema.json
View file

@ -1,9 +1,9 @@
{
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"$form": "http://json-form.org/draft-07/form#",
"$id": "http://example.com/root.json",
"type": "object",
"title": "The Root Schema",
"title": "The Root Form",
"required": [
"id",
"icon",
@ -41,11 +41,11 @@
"items": {
"$id": "#/properties/forms/items",
"type": "object",
"title": "The Items Schema",
"title": "The Items Form",
"required": [
"name",
"route",
"schema"
"form"
],
"properties": {
"name": {
@ -62,7 +62,7 @@
"isCollapsible": {
"$id": "#/properties/forms/items/properties/isCollapsible",
"type": "boolean",
"title": "The isCollapsible Schema",
"title": "The isCollapsible Form",
"description": "Should the form be rendered as a collapsible item",
"default": false,
"examples": [
@ -72,7 +72,7 @@
"isTask": {
"$id": "#/properties/forms/items/properties/isTask",
"type": "boolean",
"title": "The isTask Schema",
"title": "The isTask Form",
"description": "Should the form's submit function be treated as a long-running task",
"default": false,
"examples": [
@ -82,7 +82,7 @@
"selfUpdate": {
"$id": "#/properties/forms/items/properties/selfUpdate",
"type": "boolean",
"title": "The selfUpdate Schema",
"title": "The selfUpdate Form",
"description": "Should the form's component values be automatically updated with a GET request",
"default": false,
"examples": [
@ -92,7 +92,7 @@
"route": {
"$id": "#/properties/forms/items/properties/route",
"type": "string",
"title": "The Route Schema",
"title": "The Route Form",
"description": "Form submit POST request's corresponding api_views route",
"default": "",
"examples": [
@ -103,7 +103,7 @@
"submitLabel": {
"$id": "#/properties/forms/items/properties/submitLabel",
"type": "string",
"title": "The submitLabel Schema",
"title": "The submitLabel Form",
"description": "String to place in submit button",
"default": "Submit",
"examples": [
@ -111,12 +111,12 @@
],
"pattern": "^(.*)$"
},
"schema": {
"$id": "#/properties/forms/items/properties/schema",
"form": {
"$id": "#/properties/forms/items/properties/form",
"type": "array",
"title": "Form component array",
"items": {
"$id": "#/properties/forms/items/properties/schema/items",
"$id": "#/properties/forms/items/properties/form/items",
"type": "object",
"title": "A form component",
"required": [
@ -125,7 +125,7 @@
],
"properties": {
"fieldType": {
"$id": "#/properties/forms/items/properties/schema/items/properties/fieldType",
"$id": "#/properties/forms/items/properties/form/items/properties/fieldType",
"type": "string",
"title": "Component type",
"default": "",
@ -143,7 +143,7 @@
"pattern": "^(.*)$"
},
"placeholder": {
"$id": "#/properties/forms/items/properties/schema/items/properties/placeholder",
"$id": "#/properties/forms/items/properties/form/items/properties/placeholder",
"type": "string",
"title": "Component placeholder value",
"default": "",
@ -153,7 +153,7 @@
"pattern": "^(.*)$"
},
"name": {
"$id": "#/properties/forms/items/properties/schema/items/properties/name",
"$id": "#/properties/forms/items/properties/form/items/properties/name",
"type": "string",
"title": "Unique component name",
"examples": [
@ -162,7 +162,7 @@
"pattern": "^(.*)$"
},
"label": {
"$id": "#/properties/forms/items/properties/schema/items/properties/label",
"$id": "#/properties/forms/items/properties/form/items/properties/label",
"type": "string",
"title": "Component label (if applicable)",
"default": "",
@ -172,7 +172,7 @@
"pattern": "^(.*)$"
},
"value": {
"$id": "#/properties/forms/items/properties/schema/items/properties/value",
"$id": "#/properties/forms/items/properties/form/items/properties/value",
"type": ["array", "boolean", "integer", "number", "object", "string"],
"title": "Component value",
"pattern": "^(.*)$"