Upgrade a custom collector
Contents
In order to make further development easier and to clean up old tech dept both lib-explorer and app-explorer have gotten new major releases. As such there are some breaking changes to the API’s.
This document explains what is needed to move from
-
lib-explorer-3.x.x to lib-explorer-4.x.x
-
app-explorer-1.5.x to app-explorer-4.x.x
Development
Dependencies
gradle.properties
lib-explorer-4.0.0 (and app-explorer-4.0.0) requires xpVersion=7.12.2
xpVersion=7.12.2build.gradle
In build.gradle you have to bump lib-explorer version to 4.0.0.
dependencies {
include "com.enonic.lib:lib-explorer:4.x.x"
}Installation
Document-types
Collectors are now supposed to provide their own documentTypes.
Deprecations
Register
-
In lib-explorer-3.0.0/app-explorer-1.5.0 the register function would log a deprecation warning.
-
In lib-explorer-4.0.0/app-explorer-4.0.0 the register function will now throw a deprecation error.
| The register function is deprecated and will throw an error! |
Simply remove it from src/main/resources/main.ts
Unregister
| The unregister function is deprecated and will log a warning. |
Simply remove it from src/main/resources/main.ts
Configuration
collectors.json
The collectors.json file has been simplified a bit.
-
configAssetPathhas been renamed toformAssetPath. -
componentPathhas been replaced byformLibraryName
Renamed:
< "configAssetPath": "collector/form/SampleCollector.esm.js", > "formAssetPath": "collector/form/SampleCollector.esm.js",
Replaced:
< "componentPath": "window.SampleCollector.Collector", > "formLibraryName": "SampleCollector",
The SampleCollector.tsx is now expected to export a React Component named Collector. |
| The old syntax is still supported, but might be removed in a future release. |
React Component
The previous way to implement a Collector React Component was strongly hooked to semantic-ui-react-form, which had various complexity issues.
The new way uses React.forwardRef and React.useImperativeHandle in order for the (child) Collector component to provide callbacks that the (parent) Collection component can run when appropriate.
These are named afterReset and validate:
-
When the [Reset] button is clicked: the (parent) Collection component will reset it’s state, but whatever state is internal to the (child) Collector component needs to be handled inside it’s afterReset function.
-
When the [Save] button is clicked: the (parent) Collection component will validate it’s own input fields, but whatever inputs are provided by the (child) Collector component, should be handeled inside it’s own validate function.
These props are removed:
-
context object (sort of replaced by collectorConfig)
-
dispatch function (sort of replaced by setCollectorConfig)
-
isFirstRun ref (no longer needed)
-
path string (no longer needed)
These props are added:
-
collectorConfig (object)
-
setCollectorConfig (setState function)
-
setCollectorConfigErrorCount (setState function)
This prop is untouched:
-
explorer (object)
See Collector form.
Run
Task
Task Descriptor XML
-
name has been replaced by collectionId.
-
language has been added.
See Task schema.
Journal
collector.addSuccess() and collector.addError() no longer takes an uri parameter.
See addSuccess, addInformation, addWarning and addError.
persistDocument
create
Since collectors now provide their own document-types, you also have to specify documentTypeName when persisting a document. Just make sure it matches a (lowercased and ascii folded) _name in the src/main/resources/documentTypes.json file.
See persistDocument.
update
Since uri is no longer a required parameter to persistDocument, there is no way for a collector instance to automatically figure out which document node to update. If you want to update a document, rather than creating endless new ones, you have to lookup and provide the document node _id in your collector task implementation.
See queryDocuments and persistDocument.
