@myrmidon/cadmus-refs-asserted-ids 7.0.0 → 8.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +221 -133
- package/fesm2022/myrmidon-cadmus-refs-asserted-ids.mjs +432 -286
- package/fesm2022/myrmidon-cadmus-refs-asserted-ids.mjs.map +1 -1
- package/lib/asserted-composite-id/asserted-composite-id.component.d.ts +23 -24
- package/lib/asserted-composite-ids/asserted-composite-ids.component.d.ts +15 -16
- package/lib/asserted-id/asserted-id.component.d.ts +29 -15
- package/lib/asserted-ids/asserted-ids.component.d.ts +8 -16
- package/lib/pin-target-lookup/pin-target-lookup.component.d.ts +22 -22
- package/lib/scoped-pin-lookup/scoped-pin-lookup.component.d.ts +5 -3
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -1,50 +1,108 @@
|
|
|
1
1
|
# CadmusRefsAssertedIds
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
📦 `@myrmidon/cadmus-refs-asserted-ids`
|
|
4
|
+
|
|
5
|
+
This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 19.0.0.
|
|
4
6
|
|
|
5
7
|
- [CadmusRefsAssertedIds](#cadmusrefsassertedids)
|
|
6
|
-
- [
|
|
7
|
-
|
|
8
|
-
|
|
8
|
+
- [External IDs](#external-ids)
|
|
9
|
+
- [Internal IDs](#internal-ids)
|
|
10
|
+
- [ID Components](#id-components)
|
|
11
|
+
- [AssertedIdComponent](#assertedidcomponent)
|
|
12
|
+
- [Configuring Asserted ID](#configuring-asserted-id)
|
|
13
|
+
- [AssertedIdsComponent](#assertedidscomponent)
|
|
14
|
+
- [PinTargetLookupComponent](#pintargetlookupcomponent)
|
|
15
|
+
- [Configuring the Target ID Editor](#configuring-the-target-id-editor)
|
|
9
16
|
- [Asserted Composite ID](#asserted-composite-id)
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
17
|
+
- [Asserted Composite IDs](#asserted-composite-ids)
|
|
18
|
+
- [History](#history)
|
|
19
|
+
- [8.0.1](#801)
|
|
20
|
+
|
|
21
|
+
The asserted ID and asserted composite IDs bricks provide a way to include _external_ or _internal_ references to resource identifiers, whatever their type and origin. These components are the foundation for pin-based links in links part and links fragment types, as they provide both external and internal links, optionally accompanied by an assertion.
|
|
22
|
+
|
|
23
|
+
## External IDs
|
|
24
|
+
|
|
25
|
+
External IDs are provided by users, either manually or with the aid of lookup services. Cadmus already provides a set of builtin lookup providers for popular web APIs like VIAF, DBPedia, Geonames, and WHG, and you can add as many as you want.
|
|
26
|
+
|
|
27
|
+
At a minimum, an external ID is just a string representing an identifier. Usually this is globally unique, or it is unique only within the scope defined by its context. For instance, a DBPedia ID is a URI, which makes it a globally unique identifier; while the numeric ID assigned to an entity in a RDBMS is unique only in the scope of its table in that database.
|
|
28
|
+
|
|
29
|
+
According to their type and purpose, such IDs can thus be totally opaque for human users, like a number; or provide a hint about their target, like e.g. the URI for Marco Polo in DBPedia: <http://dbpedia.org/resource/Marco_Polo>.
|
|
30
|
+
|
|
31
|
+
So, in its most complete model an external ID has:
|
|
16
32
|
|
|
17
|
-
|
|
33
|
+
- a value for the ID itself, whether it's globally unique or not.
|
|
34
|
+
- a human-friendly label conventionally attached to the ID.
|
|
35
|
+
- an optional scope.
|
|
36
|
+
- an optional tag, which can be used to group or classify IDs in some way.
|
|
18
37
|
|
|
19
|
-
##
|
|
38
|
+
## Internal IDs
|
|
20
39
|
|
|
21
|
-
|
|
40
|
+
Internal IDs are human-friendly identifiers connected to any data in the Cadmus database. They can refer to an item as a whole, or to a specific part or fragment of it, or to a specific feature inside a part or fragment.
|
|
22
41
|
|
|
23
|
-
|
|
24
|
-
- a _scope_, representing the context the ID originates from (e.g. an ontology, a repository, a website, etc.).
|
|
25
|
-
- an optional _tag_, used to group or classify the ID.
|
|
26
|
-
- an optional _assertion_, used to define the uncertainty level of the assignment of this ID to the context it applies to.
|
|
42
|
+
In most cases, human users prefer friendly identifiers, unique only in the context of their editing environment (which is what is present to the user's mind when entering data). These identifiers in Cadmus are named **EID**s (=_entity IDs_), and may be found scattered among parts or fragments via pins, or linked to whole items via a metadata part.
|
|
27
43
|
|
|
28
|
-
|
|
44
|
+
>Of course, all Cadmus data objects (items, parts and fragments) have their own globally unique identifier, which is an opaque GUID like `401267e7-282c-40e6-8f47-67be54382b07`. EIDs instead provide human-friendly identifiers, e.g. just like the IDs you type in a TEI document. Additionally, they can be used to target a specific feature inside a part or fragment, via search pins provided by it.
|
|
29
45
|
|
|
30
|
-
|
|
46
|
+
**Item EID**s are just human-friendly aliases used to refer to a Cadmus item as a whole. Whenever we want to assign a human-friendly ID to the _item_ itself, rather than referring to it by its GUID, the conventional method relies on the generic _metadata part_, which allows users entering any number of arbitrarily defined name=value pairs. So, a user might enter a pair like e.g. `eid=vat_lat_123`, and use it as the human friendly identifier for a manuscript item corresponding to Vat.Lat.123.
|
|
31
47
|
|
|
32
|
-
|
|
48
|
+
Ultimately, even an item EID, just like any other EID is just based on a **search pin**. In Cadmus, any part or fragment in an item provides any number of _search pins_, which essentially are name=value pairs, used for a simple search during editing.
|
|
33
49
|
|
|
34
|
-
|
|
50
|
+
Each pin name is unique only in the context of the part or fragment defining it, so that pin design is not constrained; yet, a pin can easily be turned into a globally unique identifier by adding to it other data.
|
|
35
51
|
|
|
36
|
-
|
|
52
|
+
For instance, given that every part or fragment has its own globally unique ID, you can just prepend it to the pin name to get a globally unique internal ID pointing to a specific feature of a specific part or fragment. Thus, users just enter pins as arbitrary, easy to use strings, when entering data; but the general architecture also provides a way for making them globally unique.
|
|
37
53
|
|
|
38
|
-
|
|
54
|
+
>This is how the in-editor search is implemented, and a similar mechanism is also used when mapping entities from parts into a semantic graph (via mapping rules).
|
|
39
55
|
|
|
40
|
-
|
|
56
|
+
For instance, say a decorations part in a manuscript item collects a number of decorations; for each one, it might define an arbitrary EID (like e.g. `angel1`) used to identify it among the others, in the context of that part.
|
|
41
57
|
|
|
42
|
-
|
|
58
|
+
When filling the decorations part with data, users just ensure that this EID is unique in the context of the list they are editing; in other terms, no other decoration in that part will have `angel1` as its ID, while it might happen that `angel1` is used somewhere else in another part. Yet, should we be in need of a non-scoped, unique ID, we could easily build it by assembling together the EID with its part/item IDs, which by definition are globally unique (being GUIDs).
|
|
43
59
|
|
|
44
|
-
|
|
45
|
-
- we must let users pick _the preferred combination_ of components which once assembled build a unique, yet human-friendly identifier.
|
|
60
|
+
## ID Components
|
|
46
61
|
|
|
47
|
-
|
|
62
|
+
The asserted ID library provides a number of components which can be used to easily refer to the entities identified with external or internal IDs.
|
|
63
|
+
|
|
64
|
+
According to the scenario illustrated above, the basic requirements for ID components are:
|
|
65
|
+
|
|
66
|
+
- provide a general lookup mechanism for external and/or internal IDs.
|
|
67
|
+
- for internal IDs, be able to draw data _from parts or from items_, assuming the convention by which an item can be assigned an EID via its generic _metadata_ part; and provide a quick way to build a globally unique identifier from an EID. Optionally, a component can also allow users pick _the preferred combination_ of components which once assembled build a unique, yet human-friendly identifier.
|
|
68
|
+
|
|
69
|
+
>👉 The demo found in this workspace uses a [mock data service](../../../src/app/services/mock-item.service.ts) instead of the real one, which provides a minimal set of data and functions, just required for the components to function.
|
|
70
|
+
|
|
71
|
+
Various components from this library provide a different level of complexity, so you can pick the one which best fits your purposes; in general, the most powerful and versatile ID picker is represented by the [asserted composite ID](#asserted-composite-id), which can be used for both external and internal IDs, with full lookup support from lookup providers in either case.
|
|
72
|
+
|
|
73
|
+
## AssertedIdComponent
|
|
74
|
+
|
|
75
|
+
- 🔑 `AssertedIdComponent`
|
|
76
|
+
- 🚩 `cadmus-refs-asserted-id`
|
|
77
|
+
- ▶️ input:
|
|
78
|
+
- id (`AssertedId? | null`)
|
|
79
|
+
- external (`boolean?`)
|
|
80
|
+
- hasSubmit (`boolean?`)
|
|
81
|
+
- pinByTypeMode (`boolean?`)
|
|
82
|
+
- canSwitchMode (`boolean?`)
|
|
83
|
+
- canEditTarget (`boolean?`)
|
|
84
|
+
- defaultPartTypeKey (`string?|null`)
|
|
85
|
+
- lookupDefinitions (`IndexLookupDefinitions?`)
|
|
86
|
+
- internalDefault (`boolean?`): true to start a new ID as internal rather than external
|
|
87
|
+
- 📚 thesauri:
|
|
88
|
+
- `asserted-id-scopes` (idScopeEntries)
|
|
89
|
+
- `asserted-id-tags` (idTagEntries).
|
|
90
|
+
- `assertion-tags` (assTagEntries).
|
|
91
|
+
- `doc-reference-types` (refTypeEntries).
|
|
92
|
+
- `doc-reference-tags` (refTagEntries).
|
|
93
|
+
- 🔥 output:
|
|
94
|
+
- idChange (`AssertedId`)
|
|
95
|
+
- editorClose
|
|
96
|
+
- extMoreRequest (`RefLookupSetEvent`): the user requested more about the current external lookup source.
|
|
97
|
+
|
|
98
|
+
The asserted ID component allows editing a simple model representing a generic ID with an optional assertion. The ID has:
|
|
99
|
+
|
|
100
|
+
- **value**: the ID itself.
|
|
101
|
+
- **scope**: the context the ID originates from (e.g. an ontology, a repository, a website, etc.).
|
|
102
|
+
- an optional **tag**, used to group or classify the ID.
|
|
103
|
+
- an optional **assertion**, used to define the uncertainty level of the assignment of this ID to the context it applies to.
|
|
104
|
+
|
|
105
|
+
The asserted ID component provides an internal lookup mechanism based on data pins and metadata conventions. When users want to add an ID referring to some internal entity, either found in a part or corresponding to an item, he just has to pick the type of desired lookup (when more than a single lookup search definition is present), and type some characters to get the first N pins starting with these characters; he can then pick one from the list. Once a pin value is picked, the lookup control shows all the relevant data which can be used as components for the ID to build:
|
|
48
106
|
|
|
49
107
|
- the item GUID.
|
|
50
108
|
- the item title.
|
|
@@ -54,19 +112,19 @@ To this end, the asserted ID component provides an internal lookup mechanism bas
|
|
|
54
112
|
|
|
55
113
|
The user can then use buttons to append each of these components to the ID being built, and/or variously edit it. When he's ok with the ID, he can then use it as the reference ID being edited.
|
|
56
114
|
|
|
57
|
-
|
|
115
|
+
### Configuring Asserted ID
|
|
58
116
|
|
|
59
|
-
|
|
117
|
+
The asserted ID component internally uses a scoped pin lookup component (`ScopedPinLookupComponent`) to provide a list of pin-based searches with a lookup control. Whenever the user picks a pin value, he gets the details about its item and part, and item's metadata part, if any. He can then use these data to build a globally unique internal identifier by variously assembling these components.
|
|
60
118
|
|
|
61
|
-
|
|
119
|
+
You can use the scoped ID lookup control to add a pin-based lookup for any entity in your own UI:
|
|
62
120
|
|
|
63
|
-
(1) ensure to import
|
|
121
|
+
(1) ensure to import the component (`ScopedPinLookupComponent`).
|
|
64
122
|
|
|
65
123
|
(2) add a lookup control to your UI, like this:
|
|
66
124
|
|
|
67
125
|
```html
|
|
68
126
|
<!-- lookup -->
|
|
69
|
-
<cadmus-scoped-pin-lookup *ngIf="!noLookup" (idPick)="onIdPick($event)"
|
|
127
|
+
<cadmus-scoped-pin-lookup *ngIf="!noLookup" (idPick)="onIdPick($event)"/>
|
|
70
128
|
```
|
|
71
129
|
|
|
72
130
|
In this sample, my UI has a `noLookup` property which can be used to hide the lookup if not required:
|
|
@@ -109,116 +167,60 @@ export const INDEX_LOOKUP_DEFINITIONS: IndexLookupDefinitions = {
|
|
|
109
167
|
|
|
110
168
|
>Note that while pin name and type will not be displayed to the end user, the key of each definition will. Unless you have a single definition, the lookup component will display a dropdown list with all the available keys, so that the user can select the lookup's scope. So, use short, yet meaningful keys here, like in the above sample (`meta_eid`, `event_eid`).
|
|
111
169
|
|
|
112
|
-
##
|
|
170
|
+
## AssertedIdsComponent
|
|
113
171
|
|
|
114
|
-
|
|
172
|
+
An editable list of asserted IDs.
|
|
115
173
|
|
|
116
|
-
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
-
|
|
124
|
-
-
|
|
125
|
-
-
|
|
174
|
+
- 🔑 `AssertedIdsComponent`
|
|
175
|
+
- 🚩 `cadmus-refs-asserted-ids`
|
|
176
|
+
- ▶️ input:
|
|
177
|
+
- ids (`AssertedId[]`)
|
|
178
|
+
- 📚 thesauri:
|
|
179
|
+
- `asserted-id-scopes` (idScopeEntries)
|
|
180
|
+
- `asserted-id-tags` (idTagEntries)
|
|
181
|
+
- `assertion-tags` (assTagEntries)
|
|
182
|
+
- `doc-reference-types` (refTypeEntries)
|
|
183
|
+
- `doc-reference-tags` (refTagEntries)
|
|
184
|
+
- 🔥 output:
|
|
185
|
+
- idsChange (`AssertedId[]`)
|
|
126
186
|
|
|
127
|
-
|
|
187
|
+
## PinTargetLookupComponent
|
|
128
188
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
-
|
|
132
|
-
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
-
|
|
137
|
-
-
|
|
138
|
-
-
|
|
139
|
-
|
|
140
|
-
|
|
189
|
+
- ▶️ input:
|
|
190
|
+
- target (`PinTarget? | null`)
|
|
191
|
+
- pinByTypeMode (`boolean?`)
|
|
192
|
+
- canSwitchMode (`boolean?`)
|
|
193
|
+
- canEditTarget (`boolean?`)
|
|
194
|
+
- defaultPartTypeKey (`string?|null`)
|
|
195
|
+
- lookupDefinitions (`IndexLookupDefinitions?`)
|
|
196
|
+
- extLookupConfigs (`RefLookupConfig[]`): the configurations of external lookup providers, if any.
|
|
197
|
+
- internalDefault (`boolean?`): true to start a new ID as internal rather than external
|
|
198
|
+
- 🔥 output:
|
|
199
|
+
- targetChange (`PinTarget`)
|
|
200
|
+
- editorClose
|
|
141
201
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
Three components are used for this brick:
|
|
145
|
-
|
|
146
|
-
- `AssertedCompositeIdsComponent`, the top level editor for the list of IDs. This has buttons to add new internal/external IDs, and a list of existing IDs. Each existing ID has buttons for editing, moving, and deleting it. When editing, the `AssertedIdComponent` is used in an expansion panel.
|
|
147
|
-
- `AssertedCompositeIdComponent`, the editor for each single ID. This allows you to edit shared metadata (tag and scope), and specific properties for both external and internal ID.
|
|
148
|
-
- `PinTargetLookupComponent`, the editor for an internal ID, i.e. a link target based on pins lookup. This is the core of the editor's logic.
|
|
149
|
-
|
|
150
|
-
### Components API
|
|
151
|
-
|
|
152
|
-
#### AssertedCompositeIdsComponent
|
|
153
|
-
|
|
154
|
-
- 📥 input:
|
|
155
|
-
- `ids` (`AssertedId[]`)
|
|
156
|
-
- `idScopeEntries` (`ThesaurusEntry[]?`): thesaurus `asserted-id-scopes`.
|
|
157
|
-
- `idTagEntries` (`ThesaurusEntry[]?`): thesaurus `asserted-id-tags`.
|
|
158
|
-
- `assTagEntries` (`ThesaurusEntry[]?`): thesaurus `assertion-tags`.
|
|
159
|
-
- `refTypeEntries` (`ThesaurusEntry[]?`): thesaurus `doc-reference-types`.
|
|
160
|
-
- `refTagEntries` (`ThesaurusEntry[]?`): thesaurus `doc-reference-tags`.
|
|
161
|
-
- `pinByTypeMode` (`boolean?`)
|
|
162
|
-
- `canSwitchMode` (`boolean?`)
|
|
163
|
-
- `canEditTarget` (`boolean?`)
|
|
164
|
-
- `defaultPartTypeKey` (`string?|null`)
|
|
165
|
-
- `lookupDefinitions` (`IndexLookupDefinitions?`)
|
|
166
|
-
- `internalDefault` (`boolean?`): true to start a new ID as internal rather than external
|
|
167
|
-
- ⚡ output:
|
|
168
|
-
- `idsChange` (`AssertedId[]`)
|
|
169
|
-
- `extMoreRequest` (`RefLookupSetEvent`): the user requested more about the current external lookup source.
|
|
202
|
+
This component is used to edit an internal or external ID via lookup, and is the core of the [asserted composite ID](#asserted-composite-id) component:
|
|
170
203
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
- 📥 input:
|
|
174
|
-
- `id` (`AssertedId? | null`)
|
|
175
|
-
- `idScopeEntries` (`ThesaurusEntry[]?`): thesaurus `asserted-id-scopes`.
|
|
176
|
-
- `idTagEntries` (`ThesaurusEntry[]?`): thesaurus `asserted-id-tags`.
|
|
177
|
-
- `assTagEntries` (`ThesaurusEntry[]?`): thesaurus `assertion-tags`.
|
|
178
|
-
- `refTypeEntries` (`ThesaurusEntry[]?`): thesaurus `doc-reference-types`.
|
|
179
|
-
- `refTagEntries` (`ThesaurusEntry[]?`): thesaurus `doc-reference-tags`.
|
|
180
|
-
- `external` (`boolean?`)
|
|
181
|
-
- `hasSubmit` (`boolean?`)
|
|
182
|
-
- `pinByTypeMode` (`boolean?`)
|
|
183
|
-
- `canSwitchMode` (`boolean?`)
|
|
184
|
-
- `canEditTarget` (`boolean?`)
|
|
185
|
-
- `defaultPartTypeKey` (`string?|null`)
|
|
186
|
-
- `lookupDefinitions` (`IndexLookupDefinitions?`)
|
|
187
|
-
- `internalDefault` (`boolean?`): true to start a new ID as internal rather than external
|
|
188
|
-
- ⚡ output:
|
|
189
|
-
- `idChange` (`AssertedId`)
|
|
190
|
-
- `editorClose`
|
|
191
|
-
- `extMoreRequest` (`RefLookupSetEvent`): the user requested more about the current external lookup source.
|
|
204
|
+
- for **external** IDs, you can enter the ID and its human-friendly label manually, or get them from any number of lookup providers (e.g. VIAF, geonames, etc.).
|
|
192
205
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
- 📥 input:
|
|
196
|
-
- `target` (`PinTarget? | null`)
|
|
197
|
-
- `pinByTypeMode` (`boolean?`)
|
|
198
|
-
- `canSwitchMode` (`boolean?`)
|
|
199
|
-
- `canEditTarget` (`boolean?`)
|
|
200
|
-
- `defaultPartTypeKey` (`string?|null`)
|
|
201
|
-
- `lookupDefinitions` (`IndexLookupDefinitions?`)
|
|
202
|
-
- `extLookupConfigs` (`RefLookupConfig[]`)
|
|
203
|
-
- `internalDefault` (`boolean?`): true to start a new ID as internal rather than external
|
|
204
|
-
- ⚡ output:
|
|
205
|
-
- `targetChange` (`PinTarget`)
|
|
206
|
-
- `editorClose`
|
|
206
|
+
- for **internal** IDs, your lookup is based on search pins.
|
|
207
207
|
|
|
208
|
-
|
|
208
|
+
- for **both** external and internal IDs, you can optionally specify a scope (usually defining the context of the ID, like VIAF or DBPedia, or your own Cadmus database) and a tag (an arbitrary string for grouping or tagging the ID in some way).
|
|
209
209
|
|
|
210
|
-
This component provides _two modes_ to get to a pin-based link target:
|
|
210
|
+
With thousands of parts/fragments providing dozens of pins, you quickly end up with a lot of them. So, to ease their lookup in this control, you can filter them. This component provides _two modes_ to get to a pin-based link target:
|
|
211
211
|
|
|
212
|
-
- **by item** (default mode): the user selects an item from a lookup list; then a part, from the list of the selected item
|
|
213
|
-
- **by type**: the user selects the part's type (
|
|
212
|
+
- **by item** (default mode): the user selects an item from a lookup list; then a part, from the list of the parts found in the selected item; and finally a pin, from a lookup list of pins filtered by that item's part. This essentially provides a way of selecting a pin from a restricted lookup set, by walking the data hierarchy from item to part/fragment and finally pin.
|
|
213
|
+
- **by type**: the user selects the part's type (this is automatically pre-selected when only a single type is set), and then selects a pin from a lookup list of pins filtered by that part's type. The list of part types may come from several sources:
|
|
214
214
|
- explicitly set via the component `lookupDefinitions` property;
|
|
215
215
|
- if this is not set, the lookup definitions will be got via injection when available;
|
|
216
216
|
- if the injected definitions are empty, the lookup definitions will be built from the `model-types` thesaurus;
|
|
217
217
|
- if this is not available either, the _by-type_ lookup will be disabled.
|
|
218
218
|
|
|
219
|
-
|
|
219
|
+
>Filtering by item essentially means filtering by an object instance: for instance a specific manuscript object. Filtering by type instead means filtering by pin class, as each part or fragment provides its own set of search pins, whose names are meaningful and unique only in their context.
|
|
220
220
|
|
|
221
|
-
|
|
221
|
+
In both cases, in the end the target ID model is the same; it's just the way the user selects the pin which changes. You can specify the mode for the component with `pinByTypeMode`, and control the possibility of switching between modes with `canSwitchMode`.
|
|
222
|
+
|
|
223
|
+
Once the user picks an internal pin, the target is automatically filled with data from the pin itself. Two values are calculated:
|
|
222
224
|
|
|
223
225
|
- `gid`, the global ID for the target is `P<part-id>/<pin-value>` when the pin is from a part; or `I<item-id>/<pin-value>` when it is from an item only.
|
|
224
226
|
- `label`, the human-friendly label for the target, is `<pin-value> | <item-title> (<part-type>[, <part-role>])`, where `<part-type>` is either the human-friendly name of the part type ID (as drawn from the `model-types` thesaurus), or the part type ID itself.
|
|
@@ -235,22 +237,21 @@ The user can then use buttons to append each of these components to the ID being
|
|
|
235
237
|
|
|
236
238
|
>👉 The demo found in this workspace uses a [mock data service](../../../src/app/services/mock-item.service.ts) instead of the real one, which provides a minimal set of data and functions, just required for the components to function.
|
|
237
239
|
|
|
238
|
-
###
|
|
240
|
+
### Configuring the Target ID Editor
|
|
239
241
|
|
|
240
|
-
|
|
242
|
+
You can configure the target ID editor to use any number of lookup providers:
|
|
241
243
|
|
|
242
|
-
(1) ensure to import
|
|
244
|
+
(1) ensure to import the `PinTargetLookupComponent` control in your component.
|
|
243
245
|
|
|
244
246
|
(2) add a lookup control to your UI, like this:
|
|
245
247
|
|
|
246
248
|
```html
|
|
247
249
|
<!-- lookup -->
|
|
248
250
|
<cadmus-pin-target-lookup [canSwitchMode]="true"
|
|
249
|
-
(targetChange)="onTargetChange($event)"
|
|
250
|
-
</cadmus-pin-target-lookup>
|
|
251
|
+
(targetChange)="onTargetChange($event)"/>
|
|
251
252
|
```
|
|
252
253
|
|
|
253
|
-
(3) specify the lookup definitions, either from
|
|
254
|
+
(3) specify the lookup definitions, either from binding, or via injection. In the latter case, in your app's `index-lookup-definitions.ts` file, add the required lookup definitions. Each definition has a conventional key, and is an object with part type ID for the lookup scope, and pin name, e.g.:
|
|
254
255
|
|
|
255
256
|
```ts
|
|
256
257
|
import { IndexLookupDefinitions } from '@myrmidon/cadmus-core';
|
|
@@ -275,3 +276,90 @@ export const INDEX_LOOKUP_DEFINITIONS: IndexLookupDefinitions = {
|
|
|
275
276
|
```
|
|
276
277
|
|
|
277
278
|
>Note that while pin name and type will not be displayed to the end user, the key of each definition will. Unless you have a single definition, the lookup component will display a dropdown list with all the available keys, so that the user can select the lookup's scope. So, use short, yet meaningful keys here, like in the above sample (`meta_eid`, `event_eid`).
|
|
279
|
+
|
|
280
|
+
## Asserted Composite ID
|
|
281
|
+
|
|
282
|
+
- 🔑 `AssertedCompositeIdComponent`
|
|
283
|
+
- 🚩 `cadmus-refs-asserted-composite-id`
|
|
284
|
+
- ▶️ input:
|
|
285
|
+
- ids (`AssertedId[]`)
|
|
286
|
+
- pinByTypeMode (`boolean?`)
|
|
287
|
+
- canSwitchMode (`boolean?`)
|
|
288
|
+
- canEditTarget (`boolean?`)
|
|
289
|
+
- defaultPartTypeKey (`string?|null`)
|
|
290
|
+
- lookupDefinitions (`IndexLookupDefinitions?`)
|
|
291
|
+
- internalDefault (`boolean?`): true to start a new ID as internal rather than external
|
|
292
|
+
- 📚 thesauri:
|
|
293
|
+
- `asserted-id-scopes` (idScopeEntries)
|
|
294
|
+
- `asserted-id-tags` (idTagEntries)
|
|
295
|
+
- `assertion-tags` (assTagEntries)
|
|
296
|
+
- `doc-reference-types` (refTypeEntries)
|
|
297
|
+
- `doc-reference-tags` (refTagEntries)
|
|
298
|
+
- ⚡ output:
|
|
299
|
+
- `idsChange` (`AssertedId[]`)
|
|
300
|
+
- `extMoreRequest` (`RefLookupSetEvent`): the user requested more about the current external lookup source.
|
|
301
|
+
|
|
302
|
+
This is the most complete ID reference, which can be used for both external and internal IDs, providing full lookup in either cases. Each asserted composite ID has:
|
|
303
|
+
|
|
304
|
+
- a `target`, representing the pin-based target of the ID. The target model has these properties:
|
|
305
|
+
- a global ID, `gid`, built from the pin or manually defined;
|
|
306
|
+
- a human-friendly `label` for the target, built from the pin or manually defined;
|
|
307
|
+
- for internal links only:
|
|
308
|
+
- `itemId` for the item the pin derives from;
|
|
309
|
+
- when the pin derives from a part, an optional `partId`, `partTypeId`, `roleId`;
|
|
310
|
+
- the `name` and `value` of the pin.
|
|
311
|
+
- an optional `scope`, representing the context the ID originates from (e.g. an ontology, a repository, a website, etc.).
|
|
312
|
+
- an optional `tag`, eventually used to group or classify the ID.
|
|
313
|
+
- an optional `assertion`, eventually used to define the uncertainty level of the assignment of this ID to the context it applies to.
|
|
314
|
+
|
|
315
|
+
When the ID is **external**, the only properties set for the target model are `gid` (=the ID) and `label`. You can easily distinguish between an external and internal ID by looking at a property like `name`, which is always present for internal IDs, and never present for external IDs.
|
|
316
|
+
|
|
317
|
+
There are different **options** to customize the lookup behavior:
|
|
318
|
+
|
|
319
|
+
- lookup pin without any filters, except for the always present part type ID and pin name (_by type_); or lookup pin with optional filters for the item and any of its parts (_by item_; this is the default).
|
|
320
|
+
- the part type ID and pin name filter (i.e. the _index lookup definitions_) can be set from many sources:
|
|
321
|
+
1. directly from the consumer code by setting `lookupDefinitions`;
|
|
322
|
+
2. from injection, when (1) is not used;
|
|
323
|
+
3. from thesaurus `model-types`, when (2) is empty.
|
|
324
|
+
- set `pinByTypeMode` to true, to let the editor use in by-type mode instead of by-item;
|
|
325
|
+
- set `canSwitchMode` to true, to allow users switch between by-type and by-item modes;
|
|
326
|
+
- set `canEditTarget` to true, to allow users edit the link target GID and label also for internal pins, where they are automatically provided by pin lookup.
|
|
327
|
+
|
|
328
|
+
These options can be variously combined to force users to use a specific behavior only; for instance, if you just want by-type lookup and automatic GID/label, set `pinByTypeMode` to true and `canSwitchMode` and `canEditTarget` to false.
|
|
329
|
+
|
|
330
|
+
Also, you can use any number of lookup components for external IDs. To globally configure all the asserted composite IDs components for this purpose, you can define (e.g. in your app's component constructor) an array of configuration objects keyed under `ASSERTED_COMPOSITE_ID_CONFIGS_KEY`.
|
|
331
|
+
|
|
332
|
+
Three components are used for this brick:
|
|
333
|
+
|
|
334
|
+
- `AssertedCompositeIdsComponent`, the top level editor for the list of IDs. This has buttons to add new internal/external IDs, and a list of existing IDs. Each existing ID has buttons for editing, moving, and deleting it. When editing, the `AssertedIdComponent` is used in an expansion panel.
|
|
335
|
+
- `AssertedCompositeIdComponent`, the editor for each single ID. This allows you to edit shared metadata (tag and scope), and specific properties for both external and internal ID.
|
|
336
|
+
- `PinTargetLookupComponent`, the editor for an internal ID, i.e. a link target based on pins lookup. This is the core of the editor's logic.
|
|
337
|
+
|
|
338
|
+
## Asserted Composite IDs
|
|
339
|
+
|
|
340
|
+
A collection of asserted composite IDs.
|
|
341
|
+
|
|
342
|
+
- 🔑 `AssertedCompositeIdsComponent`
|
|
343
|
+
- 🚩 `cadmus-refs-asserted-composite-ids`
|
|
344
|
+
- ▶️ input:
|
|
345
|
+
- ids (`AssertedId[]`)
|
|
346
|
+
- pinByTypeMode (`boolean?`)
|
|
347
|
+
- canSwitchMode (`boolean?`)
|
|
348
|
+
- canEditTarget (`boolean?`)
|
|
349
|
+
- defaultPartTypeKey (`string?|null`)
|
|
350
|
+
- lookupDefinitions (`IndexLookupDefinitions?`)
|
|
351
|
+
- internalDefault (`boolean?`): true to start a new ID as internal rather than external
|
|
352
|
+
- 📚 thesauri:
|
|
353
|
+
- `asserted-id-scopes` (idScopeEntries)
|
|
354
|
+
- `asserted-id-tags` (idTagEntries)
|
|
355
|
+
- `assertion-tags` (assTagEntries)
|
|
356
|
+
- `doc-reference-types` (refTypeEntries)
|
|
357
|
+
- `doc-reference-tags` (refTagEntries)
|
|
358
|
+
- ⚡ output:
|
|
359
|
+
- idsChange (`AssertedCompositeId[]`)
|
|
360
|
+
|
|
361
|
+
## History
|
|
362
|
+
|
|
363
|
+
### 8.0.1
|
|
364
|
+
|
|
365
|
+
- 2025-01-01: fixed missing unsubscribe in `AssertedCompositeIdComponent`.
|