Index by title
Development Guidelines¶
General Development Standards¶
Indentation should be in tabs not spaces for accessibility reasons, as well as keeping in line with the conventions used in the ACDH-CH frontend.
Static Site Generation¶
Part of our goal with OpenAtlas Discovery is making it possible and easy to host the project statically once it has finished and/or is ready for archiving. To achieve this we make use of multiple features that Nuxt3 as well as some additional Nuxt3 addons provide for SSG(Static Site Generation).
For more details please see Static Site Generation
NuxtImage¶
We use NuxtImage for making sure the images used in the Project are available once the project goes static. We do not use normal image elements and instead make use of the ones provided by nuxt image or in case that we make use of elements we don't have control over (e.g. from vuetify) we can use $img also provided by NuxtImage to make them compatible with SSG.
Ideas¶
A collection of ideas that haven't made it into an own ticket yet.
Collection from first meeting¶
- display data in table
- display entities on map
- display entities in single page
- search functionality for entities
- provide graphs for data visualization with D3.js ?
Ideas from the first version¶
These are ideas for the original frontend development. Feel free to process and/or remove these as you see fit.
Requirements¶
- Routing for entity and map views and later probably for other visualisations per entity
- API connection for data retrieval (authentication)
Pages/Navigation¶
Pages to create¶
- Entity Detailed View
- Basic data (Name, description, classification, main type (as categorized by system type), spatial and temporal data as well as relations to other entities (for the beginning only direct ones)
- later to be extended by entity specific relations depending on the type of entity and relation
- Map view (as in Thanados) for physical things/Places and their subunits
- Visualisations
- Search/Queries
- Admin interface for customization? E.g. toggle various classes, use only selected data.
Comments¶
- Index page - maybe a map with places. When clicked on a place more info shows up (e.g. popup, sidebar or similar) with a link to a "place view page". But not sure if this is approach is viable for our "general frontend template". (Alexander Watzinger)
- Manual - I would suggest Sphinx like used in OpenAtlas (Sphinx_documentation). (Alexander Watzinger)
New Site Workflow¶
When creating a new instance for ACDH-CH cooperations, there are certain steps that need to be taken:
1. Create a new fork of the base repo: https://github.com/acdh-oeaw/OpenAtlas-Discovery with at least the branches that you want to get your version from (in most cases develop)
2. Update frontend urls in public/admin/config.yaml
3. The workflow will be disabled, since it is a fork. Before re-enabling it update the `starter.yaml` the following way:
# In setup_workflow_env
# ...
image_tagged: openatlas-discovery # -> new name
registry_root: ghcr.io/acdh-oeaw/openatlas-discovery/ # -> link to the forked repo in all lower case: ghcr.io/user/repository
default_port: # leave unchange
submodules: # leave unchange
herokuish_base_image: # leave unchange
APP_NAME: openatlas-discovery # -> new name
# ...
4. Set up all the Enviroment Variables with their corresponding values:
KUBE_INGRESS_BASE_DOMAIN
KUBE_NAMESPACE # Namespace in rancher
PUBLIC_URL # Domain under which the instance should be reached
SERVICE_ID # ID of ACDH-CH Redmine
5. Re-Enable the workflow
You should now be able to update and add new content with deployments to the new site.
Release Workflow¶
- Move open tickets: Roadmap
- Close Redmine Version and add a release date
- Update main, push changes, tag
git checkout develop
git pull origin develop
git checkout main
git merge develop
git push origin
git tag x.x.x
git push --tags
Update instances¶
Checkout forked repositories:
git remote -v
Check if upstream remote is added. If not:
git remote add upstream https://github.com/acdh-oeaw/openatlas-discovery.git
Fetch upstream and origin changes
git fetch --all --tags
Checkout develop branch
git checkout develop
Rebase
git rebase upstream/develop
After all merge conflicts are resolved, test changes locally and take a look at the git history:
git log --oneline
Afterwards:
git push --force
git push --tags
Finishing¶
Site designs¶
Here we collect ideas for the generic presentation sites.
Sorry about the not so fine looking draft, it's just a starting point and feel free to add/adapt/restructure.
Views¶
This are individual views, in parenthesis criteria are criteria defined how to fetch related entities. Possible are:
- system_class (OpenAtlas specific class definitions used in the backend and also useful for frontend)
- view_class (Collection of system_class, e.g. actor for person and group)
- cidoc_class (not sure if needed)
You can see how these are related in the backend at model/OpenAtlas classes, e.g. in the demo at this site
General Notes
- Empty fields/attributes should be hidden.
- It should be possible to choose the default entity view via the CMS, similar to how it should be possible to what the default landing page is.
Main views
- All
- Should have a breadcrumb for their system classes. Clicking on elements higher in the hierarchy should lead to the data view containing elements of that system class.
Note about the breadcrumb (by Alex): in the backend the breadcrumb begins with the view, not the system class. E.g. with a system class of activity, acquisition, move, ... the first element would be the view for "event".
This is just a note and it can of course differ at the frontend. See about classes and views
- Primary
- Name
- Alias (only for place and actor)
- Types
- Dates
- Description
- Profile image
- Secondary
- References (This is probably dependent on the entity).
- All other Attributes
- @Mocca, I believe it should not include the attributes shown already, e.g. if the images are shown in the gallery, the link to the file entity would not be needed.
- Source (system_class source)
- Description extra important. It could be a summary or the source itself.
- Multiple Tabs for the different texts (Translations, Transliterations, ...)
- Download buttons for the non-viewable files extra important here.
- Event (view_class event), this includes: Acquisition, Activity, Creation, Event, Modification, Move, Production.
- The diferences are detailed in the Manual. Most share most commonalities with Activity, therefor a common template would be sensible.
- All except Event:
- Sub-Event
- Pre/Super-ceding event.
- Location (on map)
- Actors:
- Timespan of Actor for the event.
- Standard type: Involvement
- Actor (view_class actor), this includes: Person, Group. Detailed in Manual
- All
- Residence
- Born/Started in
- Died/Ended in
- Place (system_class place)
- All
- Location (on map)
- Administrative unit & historic place:
- Show as title & description & date (the Most important info)
- Show sub-locations (on map)
- Show all connected artifacts & human remains.
- Feature (system_class feature)
- For features and all "lower" elements (like Stratographic units, ..) it should be possible to navigate to the neighbouring entities (in the list not necessarily location wise).
- Linked Stratographic units
- Here breadcrumbs are especially important again.
- Stratigraphic unit (system_class stratigraphic_unit)
- Artifact (view_class artifact), this includes artifacts and human remains (maybe split them?)
- Images are essential, it might make sense to differ the view for images a bit for artifacts to accommodate for that.
- Owned by -> Actor
- Sub-Artifacts
- Vocabulary (not sure how to name or structure these)
- Type (system_class type)
- External & Interal reference are crucial.
- Type hierarchy, potentially a place for breadcrumbs again.
- Linked entities, both directly and for subtypes:
- Bar Graph
- Administrative unit (system_class administrative_unit), there are 2 fixed hierarchies (administrative units and historical places)
- File
There is some information that can possible be included in most (or at least multiple) classes so maybe we want to design a kind of "base layout". These are:
- Name
- Alias (only for place and actor)
- Types
- Dates
- Description
- Profile image (either a set one or just the first one, this could be a good point for a gallery function. The file class obviously is a special case)
- Reference to a source entity
- External references (e.g. to Wikidata, GeoNames or Vocabs)
- References (e.g. edition)
- Map (if connected to a place, e.g. in a move event or a residence of a person)
- I(@mocca) believe it would be a good idea to show linked places in this map as well, at least on demand. E.g. a gravesite would also show the connected graves on the same map.
- Files (attached to that entity)
Likely an extra view isn't needed for these
Following system classes probably won't need an own view:
- actor_function (actor function at a group e.g. a profession)
- actor_relation (between actors)
- appellation (alias)
- involvement (actor function at an event)
- bibliography
- edition
- external_reference
- object_location
- reference_system
- type_tools (types for e.g. radio carbon values, ... we take of these later)
Maps¶
- When an overview, e.g. at start page, only show system_class place and only use markers (if area choose center point)
- When showing at a detail view (e.g. of a place) show areas (instead of center points) and next subunits (e.g. features of a place)
Static Site Generation¶
Our goal with OpenAtlas Discovery is to make it easily possible to host as static site once a project using it has ended. To achieve this we make use of various technologies, this document is meant as a collection for all the relevant information regarding this.
Used Technologies¶
Generating the Site¶
Enviroment Variables¶
Enviroment variables enable us to make OA Discovery assign important variables ahead of time, like the URL of the site hosting the API for the backend. In static sites the enviroment variable cannot be changed once it has be generated, thus we need to make sure that the correct enviroment variable is provided at the time of generation. Though as we crawl the data from the backend in order to make the site static it should not pose a problem in most cases.
To work with nuxt and be available in the nuxt runtime config the enviroment variables need to follow the naming scheme "NUXT_PUBLIC_VAR_NAME" for public variables and "NUXT_VAR_NAME" for private ones. The naming sheme is explained in more detail here.
Generating a Static Site for the frontend-demos on the CRAWS servers¶
Steps:¶
- Make sure the right environment variables are declared: NUXT_PUBLIC_API_BASE_URL & NUXT_PUBLIC_OPEN_API_BASE_URL => are using https://demo.openatlas.eu/ or https://demo-dev.openatlas.eu/, set the NUXT_PUBLIC_SPECIAL_IMPRINT to "enabled" to render the custom imprint with Alex's email address.
- Check the index pages for the correct text (depending on the instance) and replace the content of content/system-pages/{de/en}/index.md accordingly.
- Generate the site with:
pnpm run generate
- Zip the generated '.output'-folder and send it to Alex
Wiki¶
Welcome to the Wiki and issue tracker of OpenAtlas Discovery, a presentation web application for OpenAtlas projects. At the moment we are in early development.
Links¶
Documentation¶
Ideas, drafts and concepts¶