Customize DPI#
Add new field if similar properties are already present:#
To be able to define a new field, it is a good idea to check in dcatap-input-definitions.js whether fields/properties with similar parameters already exist.
File: piveau-hub-ui-modules\src\modules\data-provider-interface\config\dcatap-input-definition.js
// If you only need a template like this, without changing any parameters
// (except the IDENTIFIER) you can just copy and paste it.
IDENTIFIER: {
identifier: 'datasetID',
type: 'text',
name: 'semanticNameOfProperty',
class: 'property',
'@change': true,
},
If this is the case, copy this property and rename it according to your needs. To enable a display in the frontend, this property must be initialised under page-content-config.js.
File: piveau-hub-ui-modules\src\modules\data-provider-interface\config\page-content-config.js
datasets: {
step1: {
title: {},
datasetID: {},
description: {},
catalog: {},
publisher: {},
theme: {},
issued: {},
modified: {},
},
step2: {
politicalGeocodingLevelURI: {},
politicalGeocodingURI: {},
IDENTIFIER: {}, <--- Insert your new property here
...
}
...
}
Make sure that the property is necessary, recommended or optional and write its name in the appropriate "step". If properties with the same name are defined in different areas, they must also be initialised in these areas in page-content-config.js. Pay attention to the Weblate translation.
To get the new Field displayed in the Dataset overview, you have to add the information of the new field into the following file:
How to add a specification#
The DPI supports different metadata schemas/ specifications (e.g. DCAT-AP, DCAT-AP.de). These specifications define metadata properties, their ranges as well as their cardinalities. For further detials see DCAT-AP and DCAT-AP.de.
You will find the specifications under the following path ".../data-provider-interface/config/". Each specification should be placed within a seperate directory containing all specification-related files. Best practice here would be to simply copy the folder of dcatap and replace/ overwrite everything that differs from it. In order to use the newly defined specification all related files must be imported into the file "dpi-spec-config.js".
Prefixes#
If the prefixes of the new specification are different from the ones of dcatap you have to adapt them in the file "prefixes.js".
Page Content#
If you want to have your new fields displayed in the DPI you need to specify where you want them to be shown inside of the input form. Make sure that you know if this property is mandatory, recommended or optional - note that step 1 equals mandatory and the rest contains recommended and optional fields.
Input definition#
For defining/ adapting fields see Input definition. Sidenote: if you want to change the styling of the chosen field use the class attribute to add individual classes.
RDF and input converter#
If the new specifications includes fields which format type is not already covered by the predefined format types there are two possibilities. If you have numerous fields with the same new format type, you can define a new format type and related functions to handle it. If it is just one property you can directly include it into the converter based on the property name.
Mandatory checker#
If your specifications contain additional mandatory properties (or less) you have to alter the mandatory checker (.../data-provider-interface/utils/general-helper.js). Otherwise the navigation won't work as expected.
Customize New Field#
Add new props to the property to use them inside of the specific input type
File: piveau-hub-ui-modules\src\modules\data-provider-interface\config\dcatap-input-definition.js
IDENTIFIER: {
identifier: 'datasetID',
type: 'autocomplete-input',
name: 'semanticNameOfProperty',
class: 'property',
NEW_PROPERTY: true, <- added a new boolean to the property
'@change': true,
},
File: piveau-hub-ui-modules\src\main.ts
Vue.use(VueFormulate, {
...
library: {
...
'autocomplete-input': {
classification: 'text',
component: 'AutocompleteInput',
slotProps: {
component: ['voc', 'multiple','annifTheme','dcatDE', NEW_PROPERTY],
},
...
},
...
}
...
}
File: piveau-hub-ui-modules\src\modules\data-provider-interface\config\page-content-config.js
export default {
props: {
NEW_PROPERTY: {
type: Boolean,
required: true,
},
...
}
...
}
Format Types#
Add new type#
If you want to add a new type, you need make a new component (ideally in the same folder as the present ones : ... data-provider-interface\components -- also note the present name conventions) register it in the main.ts and index.ts (code example).
Form Input Definition#
The data provider interface (DPI) is a frontend presenting a multi-step form to the user providing the ability to upload data and metadata trough the given form. The given form and its content is based on the DCAT-AP specification which defines different classes and their properties.
To specify all properties and their behavior an object is provided within the file dcatap-input-definition.js. This file contains all definitions according to VueFormulate schema.
Currently the following classes and their properties are included: * catalogue * dataset * distribution * dataservice
This document provides a description on all definition keys and their purpose as well as linking to external sources for additional information.
Form properties#
As already mentioned the frontend should provide a form for the classes catalogue, dataset, distribution and dataservice. Based on the configuration file each class will have its own subroute (except dataservice which is a part of distribution).
Each class consists of properties which need to be defined. All definitions are stored within a general object containing nested objects for each class and their properties defining their behavior, cardinality, validation rules...
const dcatapProperties = {
datasets: {...}, // definitions of all dataset properties
distributions: {...}, // definitions of all distribution properties
catalogues: {...} // definitions of all catalogues properties
}
General property keys#
All properties are described as key-value-pairs based on VueFormulate schema. Each key serves as keyword enabling a specific behavior. There are some general keys provided by VueFormulate which are needed to define the properties specified by DCAT-AP.
property: {
name: "...",
type: "...",
options: {1: "First option", 2: "Second option"},
validation: "required",
...
}
Type#
Mandatoy key
The type defines which type of input form is used. There are numerous types defined by VueFormulate e.g. buttons, textareas, slider, selects...
There are also custom types developed specific for the DPI (see chapter 2 for detailed description): * autocomplete * conditional * datepicker * fileupload
To use a specific type of input the name of this type should be provided as value:
Name#
The form should also fulfill the purpose of providing the data and metadata as semantic data including namespaces. To achieve this each property should include a name-key containing the namespaced property name based on DCAT-AP:
For all namespaced property names see DCAT-AP.Class#
The class-key conatins css-classes whcih should be applied to the defined input. There are already a few classes predefined:
| Class | Description |
|---|---|
| property | A general class for each main property providing a border and some margins |
| grid1r2c | A class for a grid with 1 row and 2 columns |
Value#
The value-key provides a predefined value for the rendered input which can be changed using the form.
language: {
type: "select",
name: "dct:language",
value: "en", // englisch as predefined language tag
...
}
Validation#
VueFormulate provides the ability to assign validation rules to an input. There are numerous predefined rules provided by VueFormulate and also the possibility to decalre new rules.
The validation-key can contain multiple rules.
accessURL: {
type: "conditional",
name: "dct:accessUrl",
validation: "required|url", //property is mandatory and needs to be a valid URL
...
}
Options#
Mandatory property for selects and conditional inputs
The options-key only is needed for inputs with type 'select' or 'conditional'. It contains the options the input should present.
The options can be provided as object or as a list of values. For selects both possibilities are valid. For conditional inputs the options should be provided as object with keys matching the prvided data attributes (see chapter 1.2.4 & 2.2).
issued: {
type: "conditional",
name: "dct:issued",
options: {date: "Date", datetime: "Datetime"},
....
}
Children#
Mandatory key for grouped properties
This key is required for grouped input provided by VueFormulate! A group input bundles several inputs into one group. These nested inputs also need to be defined. This happens in an array of objects where each object contains the definition of a nested input.
creator: {
type: "group",
name: "dct:creator",
children: [
{
type: "text",
name: "foaf:name",
...
},
{
type: "url",
name: "foaf:homepage",
...
},
...
]
}
Repeatable#
Only for grouped input
The repeatable-key is only defined within groups making them repeatable. The value is a simple boolean determining if the grouped input should be repeatable or not.
Custom property keys#
Some properties specified by DCAT-AP require more complex inputs with very specific behavior. Therefore we implemented additional keys expanding the input definitions provided by VueFormulate.
Identifier#
The identifier key serves multiple purposes. One of it is to provide a unique identifier for each input which later is used to run cypress tests.
The more important purpose is to add labels to all inputs. The provided identifier is also used as key within the translation files. Based on the identifier and type of the input the folowwing label/descirptions are added to the definition automatically:
- label
- placeholder
- help-text
- info
- add-label (only for repeatable groups)
Minimum#
The minimum-keys was defined for mandatory properties which are repeatable (title, description, accessUrl...). If set to 1 it determines the minimum number of instances of repeatable inputs.
title: {
type: "group",
name: "dct:title",
children: [...],
repeatable: true,
validation: "required",
minimum: 1,
...
}
Voc#
Mandatory key for autocomplete inputs
This key is rquired for autocomplete inputs and also only works for autocomplete inputs. It defines which vocabulary (specified by DCAT-AP) should be used for presenting options wihtin the input.
The key should only contain the name of the vocabulary which later will be extended to an URL for requesting the actual values of the vocabulary.
A list of all available vocabularies from the OSC backend can be found here.Multiple#
Only for autocomplete input
This key only works for autocomplete inputs and requires a simple boolean value. It determines wether an autocomplete inputaccepts multiple values or just one which will be overwritten on change. The key is not mandatory, so if it's not given the default are singular values.
also determines specific behavior in terms of data saving and formatting (see 2.1)
subject : {
identifier: "subject",
name: "dct:subject",
type: "autocomplete-input",
voc: "eurovoc",
multiple: true
}
Data#
Mandatory key for conditional inputs
This key is mandatory for conditional inputs and only works for these inputs. The value of this key should be an object containing the keys defined within the value of the options object.
Each key within the provided object should be an array containing the inputs definition similar to the children-key for grouped inputs.
issued: {
name: "dct:issued,
type: "conditional-input",
options: {date: "Date", datetime: "DateTime"},
data: {
date: [
{
name: "@value",
type: "date-picker",
...
}
],
datetime: [
{
name: "@value",
type: "datetime-picker",
...
}
]
}
}
Event trigger#
VueFormulate provided the possibility define event trigger which can be also integrated within the schema. The DPI uses two trigger so far to handle specific events.
@change#
The @change trigger is a custom trigger emitting on each change within the form leading to saving all form values to the localStorage.
For nested inputs the trigger must be set to all nested properties otherwise their changes won't be considered.
title: {
type: "group",
name: "dct:title",
children: [
{
type: "text",
name: "@value",
"@change": true,
...
}
]
}
@repeatableRemoved#
Only for repetabale group inputs
This trigger emits when an item from a repetabale input is removed via the remove button. It is used to remove the saved data value from the cached dataset.
The trigger is defined while using an @ and set to a boolean value:
title: {
type: "group",
repetabale: true,
name: "dct:title",
children: [...],
minimum: 1,
"@repetableRemoved": true,
...
}
Custom input components#
VueFormulate provides a wide range of input fields but DCAT-AP sometimes requires a very specific behavior so we implemented custom input components (custom inpt types).
Autocomplete input#
Some properties need to provide values from a certain vocabulary. Since some of these vocabularies are quiet big a normal select isn't very useful. Therefore the autocomplete input was implemented.
This input type presents a normal text input field where the user can write something and based on the written value the vocabulary gets filtered. The first 10 filtered results are displayed as a list of choosable values. If no vocabulary has been found, the input field tells you that in form of a text.
Because some properties also have a higher cardinality, the input type was also designed to collect multiple values.
There are some additional keys defined specifically for thistype of input to provide all needed values.
theme: {
identifier: "theme",
name: "dcat:theme",
type: "autocomplete-input",
"@change": true,
multiple: true, //specific for autocomplete-input (not mandatory)
voc: "data-theme", // mandatory for autocomplete-input
...
}
Conditional input#
DCAT-AP specifies a few properties where the usershould be able to chosse betwenn different formats or event between providing the data manually or choosing from a vocabulary. Therefore a conditional input type is needed. VueFormulate supports conditional inputs but not to an extend that the inbuild functionality works while using schemas.
The implemented components consist of two parts. The first part is a select where the user can choose the wanted form of input.
The second part of the component renders the input field based on the chosen value. Therefore this component requires values for the options-keyword and especially values for the data-keyword, which should include the input definitions available.
Therefore some additional keys were implemented to provide all values needed for creating a conditioanl input.
accessUrl: {
identifier: 'accessUrl',
name: '@id',
type: 'conditional-input',
'@change': true,
options: { url: 'Provide URL', file: 'Upload file' },
data: {
// matching keys with options required!
url: [
{
identifier: 'accessUrlLink',
type: 'url',
name: '@id',
'@change': true,
validation: 'required|url',
},
],
file: [
{
identifier: 'accessUrlFile',
type: 'fileupload',
name: '@id',
'@change': true,
validation: 'required',
},
],
},
}
DatePicker and DateTimePicker#
VueFormulate provides an input type for date and datetime but the datetime input is not supported by Firefox so we implemented two components using another library (vue2-datepicker).
One component using the library was designed to provide dates (Datepicker) the other one extends the Datepicker-component to enable providing datetimes (DateTimePicker)
These components need no additional keys. There can be used by just providing the type.
issued: {
identifier: "issued",
name: "dct:issued",
type: "date-picker", // or "datetime-picker"
...
}
Fileupload#
VueFormulate provides a file input but we needed the input to also behave in a certain way based on the response of the attempted upload of the file. Therefore we implemented a custom component utilizing the available file input.
The component provides information about wether the upload was successful or not. Furthermore if it was sucessful it returns the location path of the uploaded file which needs to be saved as value within the dataset.
This component doesn't need additional keys, providing the input type is sufficient.