Skip to content

Field pages

Jump to bottom
joschne edited this page Jul 10, 2024 · 7 revisions

Field pages are a core element of the Geovistory toolbox. They are used to load and display graph data as (nested) lists, and the are used to synchronize data from server to client for collaborative data editing.

Terminology

Field In Geovistory a field is the set of statements of the same source entity, property, direction and scope (~ the project).

Field page is a field plus limit and offset, defining a subset of statements of the field.

Field pages in UI

The following image depicts a entity card in the Geovistory UI. The card is composed by a header with the entity label and edit buttons. What you see below, are fields many field pages, put together.

jakarta

Let's focus on the "is departure place of voyage". This is a field page, defined as:

  • source entity: 207386 (Jakarta ID)
  • property: 1335 ("is departure place of voyage")
  • direction: incoming (because the source entity is the range / object)
  • limit: 5 (Items per page = 5)
  • offset: 0 (we see the first page)

In this field page, we see five rows, each of them representing a statement with a ship voyage as its target entity. You can also see a paginator: The UI knows the total number of statement in the field: 2295, of which the first 5 are visible.

There are nested fields. Let's focus at the first row. To the left, there is a star-symbol. This symbol represents the ship voayage. We do not see the id number of this entity, but you could click and open it in a separate tab and see its id: 158062. This is the source entity for the fields within that row.

The first field, "has arrival place", of the first row is another field page, defined as:

  • source entity: 158062 (a Ship Voyage)
  • property: 1336 ("has arrival place)
  • direction: outgoing (because the source entity is the domain / subject)
  • limit: 1 (implicit)
  • offset: 0 (implicit)

Field pages are not always nested:

shipvoyages

On entity card of a ship voyage, the "has arrival place" field page just displays the entity preview of the target entity "Wielingen BE". No nested fields for "Wielingen BE" are loaded.

To sum up: An entire entiy card is composed by many field pages that are potentially nested.

Rest API

The API to load field pages is accessible at /subfield-page/load-subfield-page.

You find the technical documentation here:

[LoopBack API Explorer](https://toolbox.geovistory.org/api/explorer/#/SubfieldPageController/SubfieldPageController.loadSubfieldPages)

Request

The request body is of type GvFieldPageReq: Bildschirm­foto 2024-07-09 um 15 10 29

The request object has three main members.

req.pkProject is used to check permissions of the requester to access the requested field pages

req.page identifies the page

  • req.page.source The source entity is identified by the id given by Geovistory Toolbox. An information.statement can have subjects/objects in different tables. Therefore we use an object to identify the source:

    • fkInfo references an entity in schema information (actually exclusively in table information.resource)

    • fkData references an entity in schema data

    • fkTablesRow references a record in tables.row

    • fkTablesCell references a record in tables.cell

  • req.page.property The property id given by OntoME. (fkPropertyOfProperty is never used)

  • req.page.isOutgoing defines the direction of the statements in the field. If true, the source entity is the subject of the statements, else the object.

  • req.page.scope is an additional filter on the statements. The object may only have one of the following keys filled:

    • inProject only statements of this project id are included from the field page

    • notInProject statements of this project id are excluded from the field page

    • inRepo statements present in the community graph are taken

    • noConstraint take all statements

req.targets is an object where the key references the class id of the target entity and the value is of type GvFieldTargetViewType. Since the ontology allows one property to have different range/domain classes, using sub-classes, the classes of the target entities of the different statements may differ, even within one field. For each target class, you can define the target.

  • req.targets[class_id]
    • {"appellation": "true"} the target view type is information.appellation
    • {"language": "true"} the target view type is information.language
    • {"place": "true"} the target view type is information.place
    • {"timePrimitive": "true"} the target view type is information.timePrimitive
    • {"langString": "true"} the target view type is information.langString
    • {"dimension": "true"} the target view type is information.dimension
    • {"cell": "true"} the target view type is tables.cell
    • {"entityPreview": "true"} the target view type is pgwar.entityPreview
    • {"nestedResource": [...]} the target view type is an entity, for which individual pages are requested, see below
    • {"subReqsRecursiveTargets": "true"} this target view type is never used!

[JS 24/07/10] Currently, the server joins the correct target data independent from the request. Only if "nestedResource" is set, the serve queries the nested fields of that resource. All other GvFieldTargetViewTypes are ignored on the server. But the server returns the request in its response. -> Why are these GvFieldTargetViewTypes passed from client to server and back? -> here we may generate a lot of overhead ?

Clone this wiki locally