ShowVoc Developers Manual

This section provides comprehensive information for users and developers integrating the ShowVoc widget for semantic annotation and for accessing dataset catalogue metadata. It currently outlines the core architectural principles underlying the widget. Additional technical details and implementation guidelines will be provided in future updates.

Widget

The widgets are implemented using @angular/elements (version ^20.1.4), the Angular library designed for building framework-agnostic Web Components. This technology allows Angular components to be packaged as Custom Elements, enabling their use in any HTML-based environment regardless of the underlying framework or application stack.

In the context of widget development, @angular/elements provides several advantages:

• Encapsulation: each widget is delivered as a self-contained component, including its logic, styles, and template.
• Interoperability: the resulting Web Components can be embedded in external platforms (such as ShowVoc, VocBench, or third-party applications) without requiring Angular to be present in the host environment.
• Reusability: the same widget can be distributed and reused across different projects and architectures with minimal integration effort.
• Maintainability: Angular’s structured development model allows for consistent, testable, and version-controlled widget evolution over time.

This approach ensures a flexible and scalable solution for integrating semantic annotation and dataset catalogue functionalities into heterogeneous client applications.

Search widget - <st-search>

The <st-search> widget provides a search interface over the resources contained in the datasets imported into ShowVoc. The component is implemented as an Angular-based Web Component using the @angular/elements library, which allows it to be embedded in any HTML application regardless of the underlying framework.

The widget exposes several user-configurable options:

• Language selection: a dropdown placed in the lower-left corner of the search form allows users to select the language used to search and display resource labels.
• String match mode: users can specify how the input text is matched against resource labels, choosing among:
  • exact – exact match of the entire string
  • starts with – labels starting with the given string
  • ends with – labels ending with the given string
  • contains – labels containing the given string
• Case insensitivity: an option is available to enable or disable case-insensitive matching, controlling whether uppercase and lowercase characters are treated as equivalent.
• Search in local name: the widget can optionally perform the search on the resource local name in addition to the language-specific labels.

These options allow fine-grained control over the search behaviour and make it possible to tailor the discovery of resources to different querying and browsing needs.

Developer Reference <st-search>

Inputs

The <st-search> widget exposes a set of configuration parameters that allow developers to control its localisation, available languages, and project filtering behaviour. These inputs can be provided either through HTML attributes when embedding the Web Component, or through JavaScript property assignment when interacting programmatically.

• locale ('en' | 'it'): Defines the language used for all labels, placeholders, and UI strings inside the widget. When omitted, the widget defaults to 'en'.
• translations (Record<LocaleCode, SearchTranslations>): Provides the full translation dictionary for the widget UI. The widget comes with built-in translations for en and it, but custom translations can be supplied to override or extend the defaults. This is useful when integrating the widget into multilingual applications or providing additional localisation layers.
• languages (LanguageFilter[]): Defines the list of selectable search languages displayed in the language dropdown. Each entry must include a user-friendly label, a language code, and its active state. Example:

  [{ label: 'English', code: 'en', active: false }]

• projects (string[]): Optional list of project identifiers that restricts the search to specific contexts. When provided, the search input will display and support project filtering.

Outputs

The widget emits a set of CustomEvents to notify the host application about search results and user interactions with the returned resources.

• st-search:results: Emitted when the search operation completes successfully. The event payload is an array of ResourcesInfoWithProject[], containing the list of resources returned by the backend along with their associated project context (when available).

      export interface ResourceInfo {
          "@id": string;
          nature: string;
          qname: string;
          show: string;
      }
  
      export interface ResourcesInfoWithProject {
        result: ResourceInfo[];
        project: string;
      }
  

• st-search:result-selected: Emitted when the user selects a specific resource from the results list. The event payload is a ResourceInfo object, representing the full metadata of the selected resource.

These outputs allow the host application to respond to search activity, update the UI, or trigger additional logic without requiring direct access to the internal implementation of the widget.

Behaviour

The internal logic of the <st-search> widget is organised around a simple, predictable lifecycle that coordinates the search input, filter controls, and results list.

1. Initialization:
   On startup, the widget reads configuration parameters from the locale, translations, languages and projects inputs. It derives the effective translation set, initialises the search mode (exact match, case sensitivity, local-name search) and renders the UI by composing the internal components: <app-search-input>, <app-languages-dropdown>, <app-match-mode-dropdown> and <app-resources-info>.
2. Search configuration:
   When the user interacts with the language filter or the match mode dropdown, the widget updates its internal state (searchMode, caseSensitive, searchInLocalName) and propagates these values to the child components. This ensures that subsequent search operations are executed with the currently selected filters and options.
3. Result handling:
   The <app-search-input> component performs the actual search and emits a resultsChange event when new results are available. The widget listens to this event, updates its internal resources collection, refreshes the <app-resources-info> view, and emits the searchResult output so that the host application can access the list of ResourcesInfoWithProject[].
4. Resource selection:
   When the user selects a resource from the results list, <app-resources-info> emits a resourceSelect event. The widget forwards this selection through the selectedResource output, exposing the corresponding ResourceInfo object to the host application.

This behavior keeps the widget self-contained while providing a clear integration surface for developers via the searchResult and selectedResource outputs.

Annotation form widget - <st-annotation-form>

The <st-annotation-form> widget provides a form-based interface to create semantic annotations associated with a given online resource or external content (e.g. text fragments, documents, or records). The component is implemented as an Angular-based Web Component using the @angular/elements library, which allows it to be embedded in any HTML application regardless of the underlying framework.

The widget exposes several user-configurable options:

• Digital object identification: the form allows users to define the main identification fields of the annotated digital object, such as its human-readable label and the corresponding URI. These fields are used to consistently reference the object across annotation workflows.
• Custom facets definition: users can add a set of custom facets to the annotation, modelled as key–value pairs (e.g. documentType = "report", project = "SoSI", language = "en"). These facets capture additional context and business-specific dimensions for the annotated resource.
• Facets for advanced querying: the custom facets associated with each annotation can be leveraged by downstream services to perform advanced filtering and faceted search over the semantic annotations created with the widget.
• Language selection: a dropdown placed in the lower-left corner of the search form allows users to select the language used to search and display resource labels.
• String match mode: users can specify how the input text is matched against resource labels, choosing among:
  • exact – exact match of the entire string
  • starts with – labels starting with the given string
  • ends with – labels ending with the given string
  • contains – labels containing the given string
• Case insensitivity: an option is available to enable or disable case-insensitive matching, controlling whether uppercase and lowercase characters are treated as equivalent.
• Search in local name: the widget can optionally perform the search on the resource local name in addition to the language-specific labels.

These options allow fine-grained control over the search behaviour and make it possible to tailor the discovery of resources to different querying and browsing needs.

Developer Reference <st-annotation-form>

Inputs

The <st-annotation-form> widget exposes a set of configuration parameters that allow developers to control its localisation, the identification of the digital object being annotated, the organisational context and the languages and projects used during semantic search. These inputs can be provided either through HTML attributes when embedding the Web Component, or through JavaScript property assignment when interacting programmatically.

• locale ('en' | 'it'):
  Defines the language used for all labels, placeholders and UI strings inside the widget. When omitted, the widget defaults to 'en'.
• translations (Record<LocaleCode, AnnotationTranslations>):
  Provides the translation dictionary for the annotation form UI. The widget ships with built-in translations for en and it, but custom translations can be supplied to override or extend the defaults, for example to support additional locales or to align terminology with the host application.
• token (string):
  Authentication token used when invoking the backend service that stores semantic annotations. This value is forwarded to the underlying AnnotationService when calling the annotation endpoint.
• projects (string[]):
  Optional list of project identifiers that restricts the search to specific contexts. When provided, the search input will display and support project filtering.
• digitalObjectLabel (string):
  Human-readable label of the digital object being annotated (e.g. document title, record label). It is shown in the “Digital Object” section and in the preview modal, and is included in the final annotation payload.
• digitalObject (string):
  URI of the digital object being annotated. This value is typically a persistent URI and is used to bind created annotations to the correct target.
• system (string):
  Technical identifier (IRI) of the source system in which the widget exists. It is included in the annotation payload to record the system context.
• systemLabel (string):
  Human-readable label for the source system (e.g. “Metadata Registry”, “Document Repository”). Displayed in the preview modal and stored alongside the annotation to improve readability of the context.
• organization (string):
  Technical identifier of the organisation responsible for the annotation or owning the digital object (for example, an organisation code or IRI). Used to capture provenance information in the annotation payload.
• organizationLabel (string):
  Human-readable label for the organisation (e.g. “Fisheries Division”). Displayed in the preview header and stored as part of the annotation context.
• languages (LanguageFilter[]):
  Defines the list of selectable languages used in the semantic search section of the widget. Each entry specifies a display label, a language code and an active flag indicating whether the language is initially selected. By default, the widget enables English and Italian as additional options:

                  
  [{ label: 'English', code: 'en', active: true }, { label: 'Italian', code: 'it', active: false }]
                  
              

Outputs

The <st-annotation-form> widget exposes a set of CustomEvents that notify the host application about changes in the semantic annotation, resource selection, and the result of the save operation.

• semanticAnnotationChange:
  Emitted whenever the full semantic annotation object is updated inside the widget, for example after modifying facets or the set of selected resources.
  The event payload is a SemanticAnnotation object encapsulating the full annotation context:

  export interface SemanticAnnotation {
    organizationLabel: string;
    organization: string;
    systemLabel: string;
    system: string;
    digitalObjectLabel: string;
    digitalObject: string;
    annotation: Map<string, string>;
    facets: Map<string, string[]>;
    datasets: string[];
  }

  The annotation map holds pairs of (label → resource IRI) for all selected semantic resources, facets stores user-defined key–values used for advanced querying, and datasets contains the list of adopted datasets inferred from the selected resources.

• resourceSelectedChange:
  Emitted when the user selects a new resource from the semantic search results.
  The event payload is a ResourceInfoWithPath object, which combines the selected resource metadata with its hierarchical path in the dataset:

  export interface ResourceInfo {
    "@id": string;
    nature: string;
    qname: string;
    show: string;
  }
  
  export interface ResourceInfoWithPath {
    resource: ResourceInfo;
    path: string[]; // ordered path segments from the root to the resource
  }

• resourceDeselectedChange:
  Emitted when the user deselects a previously selected resource (i.e. unchecks it in the results list).
  The event payload is also a ResourceInfoWithPath object, allowing the host application to update its internal state symmetrically to the selection case (for example removing chips, tags or entries from an external view).
• saveCompleted:
  Emitted when the widget completes the call to the backend service that persists the semantic annotation via AnnotationService.annotateDigitalObject().
  The event payload is an object of the following shape:

  type SaveCompletedEvent = {
    success: boolean;
    data?: any;
    error?: any;
  };

  When the backend response indicates a successful operation (e.g. a reply message), success is set to true and the response is exposed in data. In case of failure or network error, success is false and the error object is provided in error. This allows the host application to react accordingly (show notifications, update its own state, or retry).

These outputs provide a clear integration surface for consuming applications: they can react to resource selection changes, inspect or store the full semantic annotation, and handle the result of the save operation without coupling directly to the internal implementation of the widget.

Behaviour

The internal logic of the <st-annotation-form> widget is organised around a predictable lifecycle that covers initialisation of the digital object context, semantic search and resource selection, facets management and persistence of the final annotation.

1. Initialization:
   On startup, the widget reads configuration parameters from the locale, translations, digitalObject, digitalObjectLabel, system, systemLabel, organization, organizationLabel, projects and languages inputs. It derives the effective translation set, initialises the “Digital Object” section with the provided identifiers and labels, prepares the facets area, and configures the internal semantic search controls with the given projects and language filters.
2. Form interaction:
   As the user edits the digital object information, adds or updates custom facets, or selects/deselects semantic resources via the integrated search, the widget maintains an internal SemanticAnnotation representation. Each change to the annotation context (digital object, facets, selected resources, datasets) triggers an update of this internal model and results in the semanticAnnotationChange event being emitted so that the host application can inspect or mirror the current annotation state.
3. Resource selection:
   When the user selects a semantic resource from the search results, the widget computes its contextual path within the dataset (for example using project, role and language information) and emits a resourceSelectedChange event carrying a ResourceInfoWithPath payload. Conversely, when a previously selected resource is deselected, a resourceDeselectedChange event is emitted with the corresponding ResourceInfoWithPath, allowing the host application to keep any external views (chips, tags, lists) in sync with the widget state.
4. Save operation:
   When the user confirms the annotation, the widget sends the current SemanticAnnotation payload to the backend service that persists semantic annotations (for example via AnnotationService.annotateDigitalObject()), using the configured token for authentication. Once the backend call completes, the widget emits a saveCompleted event containing a { success: boolean, data?: any, error?: any } object that reports the outcome of the operation. This allows the host application to display success or error notifications, update its own state, or trigger additional workflows.

This behaviour keeps the annotation logic encapsulated within the widget while providing a clear integration surface through the semanticAnnotationChange, resourceSelectedChange, resourceDeselectedChange and saveCompleted outputs.

The annotation form widget includes a preview modal that provides a read-only summary of the semantic annotation before it is submitted to the backend service. The modal is opened from the main form and displays the full context of the annotation in a compact, human-readable way.

Copyright © ART Group - Università degli Studi di Roma 'Tor Vergata'