Developer Documentation: Hooks: order and logic

Omeka Player StreamOnly Plugin

Developer Documentation

Hooks: order and logic

This page describes the order in which Omeka calls the hooks in the 5 scenarios where StreamOnly must/may need to move files from one directory to another. Most of the StreamOnly Plugin code is invoked when there is an update to a database table.

The plugin is inherently event-driven, and not all information about the context is provided by Omeka to the StreamOnly hook. The StreamOnly object stores contextual information in a protected variable $this->_soState, a keyed array.

Also, except during installation, each instantiation of the plugin object initializes $this->_soState with information created during installation, to help with optimization.

Definitions/Abbreviations:

• protected file – a file of mimetype “audio/mpeg” that is associated with a record of Item Type StreamOnly
• OmekaDir – default Omeka upload directory files/original/
• SOMRecord – the record in the StreamOnlyModel table that corresponds to the current Item, and which contains the directory where the protected files are stored for this item
• SODOption – the record in the Option table for the default Stream Only Directory
• SODElemText – a record in the Element Text table which contains the directory where protected files associated with this Item are to be stored. If the record does not exist, the files are stored in the default Stream Only Directory
• operation – a field in the protected array $this->_soState. The value is set to “unknown” when a new instance of StreamOnlyPlugin class is created, and is updated by hookBeforeSaveItem() and hookBeforeDeleteItem(), so that other hooks can act appropriately for the context in which they are operating. Possible values are:
  • “unknown” - hookBeforeSaveItem() has not yet been called, and the scenario is ambiguous
  • “insert” - Creating a new StreamOnly Item
  • “delete” - Deleting an existing StreamOnly Item
  • “update” - StreamOnly Item being updated, with no change to Item Type
  • “+StreamOnly” - Item is being changed to StreamOnly Item Type
  • “-StreamOnly” - Item of Item Type StreamOnly is being changed to some other Item Type
• filelist – a list of files that have been added to an existing Item. Omeka calls hookBeforeSaveFile() and hookAfterSaveFile() for these operations before hookBeforeSaveItem(), and the scenario is ambiguous. The Item the files are associated with may or may not be of ItemType StreamOnly, and the files may or may not be protected. The other hooks will move the files as appropriate, or leave them in OmekaDir.
• (true), (false), (true/false) – the value of the parameter $args[‘insert’], if available. In some scenarios, the value never varies (true)/(false); in others it can take on either value (true/false)

NOTE: by convention, all Omeka hook methods have the prefix “hook”. To save space, that prefix has been omitted when referring to the hooks by name.

NOTE: All hooks have a block of code at the start that returns to the caller if the Item is not currently, or not going to be, an Item of StreamOnly Type.

NOTE: If the order in which hooks are called changes in future updates of Omeka, StreamOnly will not work as specified.

---

Scenario: Create StreamOnly Item

Conditions:

• ItemType == StreamOnly
• SOMRecord does not exist
• parameter $args['insert'] == true for SaveItem hooks Hooks:

• __construct – set operation to ‘unknown’
• BeforeSaveItem (true) – set operation to ‘insert’
• BeforeSaveFile (true)
• BeforeSaveFile (false)
• AfterSaveFile (false)
• AfterSaveFile (true) – move protected file from OmekaDir to SODOption
• BeforeSaveElementText (true)
• AfterSaveElementText (true) – if SODElemText != SODOption move protected files from SODOption to SODElemText
• AfterSaveItem (true) – create SOMRecord based on SODElemText/SODOption

---

Scenario: Delete StreamOnly Item

Conditions:

• ItemType == StreamOnly
• DeleteItem hooks called Hooks:

• __construct – set operation to ‘unknown’
• BeforeDeleteItem – set operation to ‘delete’
• BeforeDeleteFile – move protected file from SOMRecord to OmekaDir
• AfterDeleteFile
• BeforeDeleteElementText
• AfterDeleteElementText
• AfterDeleteItem – delete SOMRecord

---

Scenario: Update existing StreamOnly Item, with no change to ItemType

Conditions:

• ItemType == StreamOnly
• the SOMRecord exists
• parameter $args['insert'] == false for SaveItem hooks Hooks

• __construct – set operation to ‘unknown’
• BeforeSaveFile (true)
• BeforeSaveFile (false)
• AfterSaveFile (false)
• AfterSaveFile (true) – add file to filelist
• BeforeSaveItem (false) – set operation to ‘update’ and move protected files in filelist from OmekaDir to SOMRecord
• BeforeSaveFile (false)
• AfterSaveFile (false)
• BeforeDeleteFile – move file from SOMRecord to OmekaDir
• AfterDeleteFile
• BeforeSaveElementText (true/false)
• AfterSaveElementText (true/false) – if (SOMRecord != SODElemText) move files from SOMRecord to SODElemText and update SOMRecord
• BeforeDeleteElementText
• AfterDeleteElementText – if (SOMRecord != SOOption) move protected files from SOMRecord to SOOption and update SOMRecord to SOOption
• AfterSaveItem (false)

---

Change the ItemType of an existing Item from another ItemType to StreamOnly

Conditions:

• ItemType == StreamOnly
• SOMRecord does not exist
• parameter $args['insert'] == false for SaveItem hooks Hooks:

• __construct – set operation to ‘unknown’
• BeforeSaveFile (true)
• BeforeSaveFile (false)
• AfterSaveFile (false)
• AfterSaveFile (true) – add file to $this->_soState[‘filelist’]
• BeforeSaveItem (false) – set operation to ‘+StreamOnly’ and move protected files in filelist from Omeka to SODOption
• BeforeSaveFile (false)
• AfterSaveFile (false) – move protected file from Omeka to SODOption
• BeforeDeleteFile – move protected file from SODOption to OmekaDir
• AfterDeleteFile
• BeforeSaveElementText (true/false)
• AfterSaveElementText (true/false) - move protected files from SODOption to SODElemText
• BeforeDeleteElementText
• AfterDeleteElementText
• AfterSaveItem (false) – create SOMRecord based on SODElemText/SODOption

---

Change the ItemType of an existing Item from StreamOnly to another ItemType

Conditions:

• ItemType != StreamOnly
• SOMRecord exists
• parameter $args['insert'] == false for SaveItem hooks Hooks:

• __construct – set operation to ‘unknown’
• BeforeSaveFile (true)
• BeforeSaveFile (false)
• AfterSaveFile (false)
• AfterSaveFile (true) – add file to $this->_soState[‘filelist’]
• BeforeSaveItem (false) – set operation to ‘-StreamOnly’ and move protected files in filelist from Omeka to SOMRecord
• BeforeSaveFile (false)
• AfterSaveFile (false)
• BeforeDeleteFile – move protected file from SOMRecord to Omeka
• AfterDeleteFile
• BeforeSaveElementText (true/false)
• AfterSaveElementText (true/false)
• BeforeDeleteElementText
• AfterDeleteElementText
• AfterSaveItem (false) – move protected files from SOMRecord to Omeka and delete SOMRecord