Skip to content

Home

Jump to bottom Edit New page
Michael J. Giarlo edited this page Dec 2, 2020 · 10 revisions

Welcome to the happy-heron ("H2") wiki! This is where we put developer-focused documentation.

State machine diagrams

State machine diagrams for collections and works live in the application repository:

Collections

Collections

Works

Works

Updates

To keep these up to date, run the following command and commit the resulting changes whenever the state machines change:

$ bin/rake state_machines:draw CLASS=Work,Collection FORMAT=svg

Complete deposits locally

Completing a deposit of a work or a collection in H2 requires SDR integration, which we don't have when doing development locally. (We could add sdr-api in docker-compose.yml, but then we need dor-services-app, workflow-service, fedora, etc. etc., so it would very quickly become heavier than we want.) It's still useful to simulate completion of deposits. Here's how to do that:

# Make sure to have the object ID (the database ID, an integer), e.g.:
id = 123
# Make up a druid too, e.g.:
druid = 'druid:bc123df4567'

# This simulates what's done in the DepositStatusJob when we receive a response from sdr-api
object = Work.find(id) # or Collection.find(id)
object.druid = druid
object.add_purl_to_citation # if it's a Work
object.deposit_complete!

You may wish to check the latest definition of DepositStatusJob#complete_deposit to confirm this documentation hasn't gotten stale. If it has, please update it.

Remote form validation (Stimulus, XHR, and server-based validations)

  • Naming conventions (from snake_case Rails models to kebab-case in Stimulus-land), documenting that we take whatever Rails gives us, translate it to Stimulus (also relates to controller naming)
    • For doing name translation, there is a helper method declared in the works controller called normalize_key, make sure your field is normalized here (you may only need to do this if the field on the Rails side contains an underscore)
  • Where to declare validations in the app (forms, models, how to decide). Presence validation in the forms. Format validation in the models. Why? Allow drafts to be saved without required fields for deposit, but don't allow garbage values.
  • Stimulus 101 (controllers, targets, actions)
    • Adding the expected error hook to controllers to handle remote form validation
  • Remote forms 101 (submitting via XHR, + using stimulus hooks to retrieve and parse responses)
    • Add field target corresponding to controller to allow dispatching of errors
    • In your field controller (which is nested in the edit-deposit controller), make sure to add a data-action that handles the error event and runs your field controller's error() function
    • ... and a data-target for your field within the edit-deposit controller (e.g., edit-deposit.embargo-dateField for embargo date work, making sure to use Stimulus/JavaScript naming conventions, see above)
  • Example PRs:
Add a custom footer
Add a custom sidebar
Clone this wiki locally