Skip to content

Commit 5ac5ff3

Browse files
committed
Fix eclipsesource#567: Add JsDoc
1 parent 8ebdefe commit 5ac5ff3

35 files changed

+1123
-79
lines changed

src/core.ts

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,43 @@ import {DataService} from './core/data.service';
55
import {RendererService} from './core/renderer.service';
66
import {StylingRegistry, StylingRegistryImpl} from './core/styling.registry';
77

8+
/**
9+
* Represents a JSONForms service.
10+
*/
811
export interface JsonFormService {
12+
13+
/**
14+
* Disposes this service.
15+
*/
916
dispose(): void;
1017
}
18+
19+
/**
20+
* Encapsulates instantiation logic of a JSONForms service.
21+
*/
1122
export interface JsonFormsServiceConstructable {
23+
/**
24+
* Constructor logic.
25+
*
26+
* @param {DataService} dataService the data service
27+
* @param {JsonSchema} dataSchema the JSON schema describing the data
28+
* @param {UISchemaElement} uiSchema the UI schema to be rendered
29+
*/
1230
new(dataService: DataService, dataSchema: JsonSchema, uiSchema: UISchemaElement): JsonFormService;
1331
}
32+
33+
/**
34+
* Annotation for registering a class as JSONForms service.
35+
* @param config
36+
* @constructor
37+
*/
1438
export const JsonFormsServiceElement = (config) => (cls: JsonFormsServiceConstructable) => {
1539
JsonFormsHolder.jsonFormsServices.push(cls);
1640
};
41+
42+
/**
43+
* Global JSONForms object that holds services and registries.
44+
*/
1745
export class JsonFormsHolder {
1846
public static rendererService = new RendererService();
1947
public static jsonFormsServices: Array<JsonFormsServiceConstructable> = [];

src/core/data.service.ts

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,51 @@
11
import {ControlElement} from '../models/uischema';
22
import { getValuePropertyPair } from '../path.util';
33

4+
/**
5+
* A listener that is notified whenever the underlying data changes.
6+
*/
47
export interface DataChangeListener {
8+
9+
/**
10+
* Determines whether this listener is interested in any data change.
11+
* If this returns true, the notifyChange method of the listener will be called.
12+
* @param {ControlElement} uischema the control element that is affected by the data change
13+
* @returns whether this listener is interested in the given control element
14+
*/
515
isRelevantKey(uischema: ControlElement): boolean;
16+
17+
/**
18+
* Represents the listener's logic to be called in case of a data change that
19+
* is relevant to the listener.
20+
*
21+
* @param {ControlElement} uischema the control element that is affected by the data change
22+
* @param {any} newValue the changed data value
23+
* @param {any} data the current data value
24+
*/
625
notifyChange(uischema: ControlElement, newValue: any, data: any): void;
726
}
27+
28+
/**
29+
* The data service that holds the data of a form and maintains
30+
* a list of listeners that are notified whenever the data changes.
31+
*/
832
export class DataService {
933
private changeListeners: Array<DataChangeListener>= [];
34+
35+
/**
36+
* Constructor
37+
* .
38+
* @param data the data object to be wrapped by the service
39+
*/
1040
constructor(private data: any) {
1141
}
42+
43+
/**
44+
* Notifies any data change listeners about a data change.
45+
*
46+
* @param {ControlElement} uischema the affected control element
47+
* @param newValue the new value of the data chunk
48+
*/
1249
notifyChange(uischema: ControlElement, newValue: any): void {
1350
if (uischema !== undefined && uischema !== null) {
1451
const pair = getValuePropertyPair(this.data, uischema.scope.$ref);
@@ -21,19 +58,40 @@ export class DataService {
2158
}
2259
});
2360
}
61+
62+
/**
63+
* Register the given data change listener.
64+
* @param {DataChangeListener} listener the listener to be registered
65+
*/
2466
registerChangeListener(listener: DataChangeListener): void {
2567
this.changeListeners.push(listener);
2668
}
69+
70+
/**
71+
* Un-register the given data change listener.
72+
* @param {DataChangeListener} listener the data change listener to be un-registered
73+
*/
2774
unregisterChangeListener(listener: DataChangeListener): void {
2875
this.changeListeners.splice(this.changeListeners.indexOf(listener), 1);
2976
}
77+
78+
/**
79+
* Resolve the ref of the given control against the root data.
80+
*
81+
* @param {ControlElement} uischema
82+
* @return {any} the de-referenced data chunk
83+
*/
3084
getValue(uischema: ControlElement): any {
3185
const pair = getValuePropertyPair(this.data, uischema.scope.$ref);
3286
if (pair.property === undefined) {
3387
return pair.instance;
3488
}
3589
return pair.instance[pair.property];
3690
}
91+
92+
/**
93+
* Notifies all data change listeners initially.
94+
*/
3795
initialRootRun(): void {
3896
this.changeListeners.forEach(listener => {
3997
if (listener.isRelevantKey(null)) {

src/core/renderer.service.ts

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,46 @@ import {DataService} from './data.service';
55
import {Renderer} from './renderer';
66
import {RankedTester} from './testers';
77

8+
/**
9+
* The renderer service maintains a list of renderers and
10+
* is responsible for finding the most applicable one given a UI schema, a schema
11+
* and a data service.
12+
*/
813
export class RendererService {
914
private renderers: Array<{tester: RankedTester, renderer: string}> = [];
15+
16+
/**
17+
* Register a renderer. A renderer is represented by the tag name of the corresponding
18+
* HTML element, which is assumed to have been registered as a custom element.
19+
*
20+
* @param {RankedTester} tester a tester that determines whether when the renderer should be used
21+
* @param {string} renderer the tag name of the HTML element that represents the renderer
22+
*/
1023
registerRenderer(tester: RankedTester, renderer: string): void {
1124
this.renderers.push({tester, renderer});
1225
}
26+
27+
/**
28+
* Unregister a renderer.
29+
* @param {RankedTester} tester the tester of the renderer to be un-registered.
30+
* Note that strict equality is used when un-registering renderers.
31+
* @param {string} renderer the tag name of the HTML element that represents
32+
* the renderer to be un-registered
33+
*/
1334
unregisterRenderer(tester: RankedTester, renderer: string): void {
1435
this.renderers = _.filter(this.renderers, r =>
1536
// compare testers via strict equality
1637
r.tester !== tester || !_.eq(r.renderer, renderer)
1738
);
1839
}
40+
41+
/**
42+
* Find the renderer that is capable of rendering the given UI schema.
43+
* @param {UISchemaElement} uischema the UI schema to be rendered
44+
* @param {JsonSchema} schema the JSON data schema the associated data schema
45+
* @param {DataService} dataService the data service holding the data to be rendered
46+
* @return {HTMLElement} the rendered HTML element
47+
*/
1948
getBestRenderer(uischema: UISchemaElement,
2049
schema: JsonSchema,
2150
dataService: DataService): HTMLElement {

src/core/renderer.ts

Lines changed: 53 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,41 +3,91 @@ import { JsonSchema } from '../models/jsonSchema';
33
import {DataService} from './data.service';
44
import {Runtime, RUNTIME_TYPE, RuntimeListener} from './runtime';
55

6+
/**
7+
* A renderer is a regular HTMLElement that has a render method which will
8+
* manipulate the underlying document when called. It also provides several
9+
* lifecycle hooks.
10+
*/
611
export abstract class Renderer extends HTMLElement implements RuntimeListener {
12+
13+
/**
14+
* The {@link UISchemaElement} to be rendered.
15+
*/
716
protected uischema: UISchemaElement;
17+
18+
/**
19+
* The {@link DataService} holding the data to be rendered.
20+
*/
821
protected dataService: DataService;
22+
23+
/**
24+
* The {@link JsonSchema} to be rendered.
25+
*/
926
protected dataSchema: JsonSchema;
27+
28+
/**
29+
* Set the UI schema.
30+
* @param {UISchemaElement} uischema the UI schema element to be set
31+
*/
1032
setUiSchema(uischema: UISchemaElement) {
1133
this.uischema = uischema;
1234
}
1335

36+
/**
37+
* Set the data service.
38+
* @param {DataService} dataService the data service to be set
39+
*/
1440
setDataService(dataService: DataService) {
1541
this.dataService = dataService;
1642
}
1743

44+
/**
45+
* Set the JSON data schema .
46+
* @param {JsonSchema} dataSchema the data schema
47+
*/
1848
setDataSchema(dataSchema: JsonSchema) {
1949
this.dataSchema = dataSchema;
2050
}
2151

52+
/**
53+
* Notify this renderer about any run-time changes.
54+
*
55+
* @param {RUNTIME_TYPE} type the type of runtime change
56+
*/
2257
notify(type: RUNTIME_TYPE): void {
23-
//
58+
// no-op
2459
}
2560

61+
/**
62+
* Called when this renderer is inserted into a document.
63+
*/
2664
connectedCallback(): void {
2765
if (!this.uischema.hasOwnProperty('runtime')) {
28-
const runtime = new Runtime();
29-
this.uischema['runtime'] = runtime;
66+
this.uischema['runtime'] = new Runtime();
3067
}
3168
const runtime = <Runtime>this.uischema['runtime'];
3269
runtime.addListener(this);
3370
this.render();
3471
}
72+
73+
/**
74+
* Called when this renderer is removed from a document.
75+
*/
3576
disconnectedCallback(): void {
3677
this.dispose();
3778
const runtime = <Runtime>this.uischema['runtime'];
3879
runtime.removeListener(this);
3980
}
4081

82+
/**
83+
* Represents the render logic, i.e. it manipulates the DOM in-place.
84+
*
85+
* @return {HTMLElement} the renderer HTML element
86+
*/
4187
abstract render(): HTMLElement;
88+
89+
/**
90+
* Dispose this renderer.
91+
*/
4292
abstract dispose(): void;
4393
}

src/core/runtime.ts

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,102 @@
1+
/**
2+
* The different types of runtime related changes.
3+
*/
14
export enum RUNTIME_TYPE {
25
VALIDATION_ERROR, VISIBLE, ENABLED
36
}
7+
8+
/**
9+
* A listener that is notified about any runtime related changes.
10+
*/
411
export interface RuntimeListener {
12+
13+
/**
14+
* Called when a runtime related property changes.
15+
* @param {RUNTIME_TYPE} type the type of runtime change
16+
*/
517
notify(type: RUNTIME_TYPE): void;
618
}
19+
20+
/**
21+
* A runtime object holds information about runtime related properties
22+
* of a rendered UI schema element, like the visible/disabled state and
23+
* possible validation errors.
24+
*/
725
export class Runtime {
826
private _validationErrors: Array<string>;
927
private _visible = true;
1028
private _enabled = true;
1129
private _listeners: Array<RuntimeListener> = [];
1230

31+
/**
32+
* Whether the element is visible.
33+
* @return {boolean} true, if the element is visible, false otherwise
34+
*/
1335
get visible(): boolean {return this._visible; };
36+
37+
/**
38+
* Whether the element is enabled.
39+
* @return {boolean} true, if the element is enabled, false otherwise
40+
*/
1441
get enabled(): boolean {return this._enabled; };
42+
43+
/**
44+
* Returns the validation errors associated with the element.
45+
* @return {Array<string>} the validation errors
46+
*/
1547
get validationErrors(): Array<string> {return this._validationErrors; };
1648

49+
/**
50+
* Set the visibility state of the element
51+
* @param {boolean} visible whether the element should be visible
52+
*/
1753
set visible(visible: boolean) {
1854
this._visible = visible;
1955
this.notifyListeners(RUNTIME_TYPE.VISIBLE);
2056
};
2157

58+
/**
59+
* Set the enabled state of the element
60+
* @param {boolean} enabled whether the element should be enabled
61+
*/
2262
set enabled(enabled: boolean) {
2363
this._enabled = enabled;
2464
this.notifyListeners(RUNTIME_TYPE.ENABLED);
2565
};
2666

67+
/**
68+
* Set the validation errors.
69+
*
70+
* @param {string[]} validationErrors the validation errors
71+
*/
2772
set validationErrors(validationErrors: Array<string>) {
2873
this._validationErrors = validationErrors;
2974
this.notifyListeners(RUNTIME_TYPE.VALIDATION_ERROR);
3075
};
3176

77+
/**
78+
* Add the given runtime listener.
79+
*
80+
* @param {RuntimeListener} listener the runtime listener to be added
81+
*/
3282
addListener(listener: RuntimeListener): void {
3383
this._listeners.push(listener);
3484
}
3585

86+
/**
87+
* Remove the given runtime listener.
88+
*
89+
* @param {RuntimeListener} listener the runtime listener to be removed
90+
*/
3691
removeListener(listener: RuntimeListener): void {
3792
this._listeners.splice(this._listeners.indexOf(listener), 1);
3893
}
3994

95+
/**
96+
* Notifies any runtime listeners about a runtime change.
97+
*
98+
* @param {RUNTIME_TYPE} type the runtime type
99+
*/
40100
private notifyListeners(type: RUNTIME_TYPE): void {
41101
this._listeners.forEach(listener => listener.notify(type));
42102
}

0 commit comments

Comments
 (0)