Installation and configuration¶

This page sets up a WissKI date field so it stores an EDTF value, fills sortable sibling fields and, optionally, writes the time model into the pathbuilder. What the values mean is explained in wisski_date_field_extractor.

Install the module¶

Enable Wisski Date Field Extractor at Extend, or run:

drush en wisski_date_field_extractor

Create the date field¶

Go to Configuration → WissKI → Pathbuilders → your main pathbuilder.
Add the path for the date input, for example on a work:
```
ecrm:E22_Man-Made_Object -> ecrm:P12i_was_present_at -> ecrm:E12_Production -> ecrm:P4_has_time-span -> ecrm:E52_Time-Span
```
As the datatype property choose P3_has_note. As the type of the field that should be generated choose WissKI date field. 3. Add a number (integer) field for each sortable value you need: earliest and latest begin, earliest and latest end. Leave out the ones you do not need. 4. For the Views filter Within, add an unlimited text field for the date list. 5. Click Save and generate bundles and fields.

Point the date field at its sibling fields¶

Open Structure → WissKI Entities and Bundles → the bundle → Manage fields → the date field. Fill in the field IDs:

Setting	Field
Field ID for qualified begin field, qualified end field	The stated date, such as `1943-01-01` and `1943-12-31`
Field ID for earliest begin, latest begin, earliest end, latest end	The number fields from step 3
Field ID for the date list	The unlimited text field from step 4

Leave a setting blank to skip that value. Before and After in Views need the earliest-begin and latest-end fields; Within also needs the date list.

Set the widths¶

Set the widths once at Configuration → WissKI → WissKI Date Field Extractor, tab Widths (/admin/config/wisski/edtf). The Mapping tab (/admin/config/wisski/edtf/mapping) holds the bundles and fields of the time model. A WissKI date field uses those widths. Clear Use the site-wide EDTF widths on the field only when that one field needs different numbers. The time-span collection written to the pathbuilder always uses the site-wide widths.

Setting	Default	What it changes
Approximate years, months, days	1	Added on each side of `~` and of `%`. `?` alone keeps the stated date
Earliest year of an open interval	-9999	Sort index for `../`. Not a date and not an RDF bound. An unknown start (`/1984`) leaves the integer empty
Latest year of an open interval	9999	Sort index for `/..`. Not a date and not an RDF bound. An unknown end (`1984/`) leaves the integer empty

Examples of what the widths do are in Widths.

Reparse after a width change

Already stored spans stay as they are. Saving an entity again does not reread an unchanged EDTF string, unless that value adjusts its own widths. Run drush wisski:edtf-reparse after a change. The command resaves the date field and the mapped date bundles. It does not change the EDTF text.

Map the time model onto the pathbuilder¶

Nothing is written until a mapping is saved. The date field and its Views filter work without it.

Add the WissKI time model¶

On the Mapping tab, Add the WissKI time model (/admin/config/wisski/edtf/time-model) adds the groups and sets the mapping to their bundles and fields. Running it again keeps a path that already has its bundle or field and still adds the uncertainty field on the time-span. This is the quickest way. Only the EDTF text is in the edit form. Its help text, and that of the time-span text, links the module's help page (/admin/help/wisski_date_field_extractor), which explains the notation: the EDTF specification plus !(…) and =(…). Without the Help module it links the specification. The type, the time-spans, their text and the four bounds are computed from it, so they are shown on the entity but not offered for editing. A time-span's text keeps the mark of its date: !(1900/1910) gives the time-span !(1900/1910), not 1900/1910, which would mean other bounds.

Computed fields are disabled in the form display

The WissKI SPARQL adapter stores and clears only fields that are in the bundle's form display, unless a field is marked computed. Saving the mapping, and adding the time model, marks every mapped field except the EDTF text as computed. The time model also disables them under Manage form display; for a mapping made by hand, disable them there yourself.

The time expression lists its time-spans by title (formatter WissKI entity reference label). A bundle without a title pattern gets its EDTF text as title, for example 1900/1910; a pattern you set is kept.

The time-span bundle also gets an Uncertainty field. It is a text list marked as annotation field, not a path. Its list is Uncertain (probable, EDTF ?), Approximate (approximate, ~), Unspecified (unspecified, X) and Estimated (estimated, significant digits). Empty means certain, and several values may apply together. The stored text is the key. It is written on the four bound triples by a reifier of class wisski:Uncertainty_Annotation with P3 has note. It is filled from the EDTF text like the bounds: ? gives Uncertain, ~ Approximate, % both, X Unspecified and significant digits (1950S2) Estimated. Each time-span of a set or a choice gets its own reading, so in [1990?,2000,2010] only the first is uncertain. The field is computed and not in the edit form. The labels follow the interface language.

Before it adds anything, it checks that the pathbuilder's store has every class and property the paths use, in any graph. CIDOC CRM 7.1.3 and the WissKI ontology 2.7.0 (for Preferred Name) have to be loaded on the WissKI ontology page; the form lists each missing term. The classes Time Expression, Time expression type, Statement annotation and Uncertainty annotation (a statement annotation, which is a CRM entity, so the reasoner offers P3 has note for it) are inserted into the graph http://wiss-ki.eu/ontology/default/time-additions when the store lacks them. A read-only store has to have them already: load ontology/time-expression.rdf of this module into it. If the store cannot be queried or does not take the insert, no path is added.

Map existing bundles by hand¶

On the Mapping tab, choose the time expression bundle and the time-span bundle. Once a bundle is chosen, its fields are offered, limited to fields of a type that fits the role. Nothing is written until both bundles, the dates field and the EDTF text field are saved; an empty select leaves that role alone.

Bundle	Field	What is written
Time expression	EDTF text	Where the EDTF value is typed. This is the string that is parsed. Required
Time expression	Dates	Reference to the time-spans, earliest first. Cardinality unlimited. Required
Time expression	Type	A list field. `all_of_these_dates` for a set `{…}`, `one_of_these_dates` for a choice `[…]`, empty otherwise
Time-span	Text	The time-span's own label
Time-span	Some time within, begin and end	The outer bounds (`P82a`, `P82b`). Empty when that side is unknown or open
Time-span	At least throughout, begin and end	The inner bounds (`P81a`, `P81b`). Empty for a single year, for `!(…)`, and when the windows overlap
Time-span	Uncertainty	A list field offering `probable`, `approximate`, `unspecified` and `estimated`, filled from `?`, `~`, `%`, `X` and significant digits; empty for a certain date. Mark it as annotation field and list it on the bound paths to write it onto the bound triples

A later save whose text did not change does not write the time-spans again. drush wisski:edtf-reparse writes them again.

A bound is stored as YYYY-MM-DDThh:mm:ss without a time zone, for example 1900-01-01T00:00:00. Its field can be a text field, or a Drupal date field when every date lies in the years 1 to 9999: a date-only field gets YYYY-MM-DD. A bound before the year 1, such as -0044-03-15, leaves a date field empty and is logged as a warning. Drupal shows a date field in the site's time zone, so choose UTC in its formatter. The time model keeps text fields, because they hold every EDTF year.

The type field has to be a list that offers all_of_these_dates and one_of_these_dates; a key the list does not offer is not stored and is logged. The time model's own type field takes its keys and labels (All of these dates, One of these dates) from the module, translated with the interface.

Date and Date Period of ontology 2.7.0

Groups that reference one begin and one end Date, each with from, until and an operator, are not written by this module. Their data stay as they are. Use the time model for new dates.

Set up Views¶

On the date field, filter with:

Within — one stored date overlaps the value. Needs the date-list field and compares at most 64 dates; a longer value matches nothing. Without the date-list field, Within matches nothing.
Before (including the bound) — the last date ends on or before the value.
After (including the bound) — the first date starts on or after the value.

Sort on the earliest-begin integer, which is the first date. Why Within needs the date list is explained in Views.

With the time model, add the entry …: time-span bounds of the field that references the time expression, for example Event → Date (…): time-span bounds, as a filter or a sort criterion. To list events by date, add it as sort criterion and keep the Bound All mapped bounds, chronologically; ascending lists the earliest first. As a filter, keep the Bound All mapped bounds, by operator and choose the operator, for example Overlaps 1800/1900. The operators are described in Views on the time model.

Try it out¶

Edit an entity of the bundle and type a date such as 1943-05 or 1952/1954 into the date field. After Save, the sibling fields hold the computed values, and with a saved mapping the pathbuilder holds the time-spans.