Extensions

Like any other Emacs package, Vino can be extended using its available public functions. Remember, Vino is built on top of Vulpea, which provides an API for building various features on top of your wine-related notes.

This document describes a few extension hooks provided by Vino in addition to the configuration options covered in other sections.

Refer to the Inventory section to learn more about this feature and its extension points.

Entry creation handler

Whenever a new wine entry is created using vino-entry-create, the abnormal hook vino-entry-create-handle-functions is invoked with the newly created vulpea-note as its argument.

To register a hook, use the add-hook function:

(add-hook 'vino-entry-create-handle-functions #'my-vino-entry-create-handler)

(defun my-vino-entry-create-handler (note)
  "Handle wine entry creation.

NOTE is a `vulpea-note'."
  (message "%s was created" (vulpea-note-title note)))

If you are using the Inventory feature, you may want to register vino-inv-acquire as a handler:

(add-hook 'vino-entry-create-handle-functions #'vino-inv-acquire)

Entry update handler

Whenever a wine entry is updated (either through interactive use of vino-entry-update or as part of other functions), the abnormal hook vino-entry-update-handle-functions is called with the updated note.

To register a hook, use the add-hook function:

(add-hook 'vino-entry-update-handle-functions #'my-vino-entry-update-handler)

(defun my-vino-entry-update-handler (note)
  "Handle wine entry update.

NOTE is a `vulpea-note'."
  (message "%s was updated" (vulpea-note-title note)))

If you are using the Inventory feature, you may want to register vino-inv-update-availability as a handler:

(add-hook 'vino-entry-create-handle-functions #'vino-inv-update-availability)

Remember that each handler is called with the original note value. If your code depends on changes made by other handlers (which is generally not advisable), you need to re-read the note from the database:

(defun my-vino-entry-update-handler (note)
  "Handle wine entry update.

NOTE is a `vulpea-note'."
  (let ((note (vulpea-db-get-by-id (vulpea-note-id note))))
    (message "%s was updated" (vulpea-note-title note))))

Rating creation handler

Whenever a new rating is created, the abnormal hook vino-rating-create-handle-functions is invoked with the newly created vulpea-note and additional data as arguments. The additional data allows extensions to pass extra information to hooks. Read on to learn more.

To register a hook, use the add-hook function:

(add-hook 'vino-rating-create-handle-functions #'my-vino-entry-create-handler)

(defun my-vino-rating-create-handler (note extra-data)
  "Handle wine rating creation.

NOTE is a `vulpea-note'.

EXTRA-DATA is whatever was passed the rating creation routine."
  (message "%s was created" (vulpea-note-title note)))

Extra data

As mentioned, the second argument of the handler function allows passing any extra useful information. For example, if you are using the Inventory feature, you might want to know which specific bottle was consumed. In this case, vino-inv-consume passes an alist that contains bottle id.

Suppose you want to record the bottle id and its volume in the rating. Here's how you can implement this:

(add-hook 'vino-rating-create-handle-functions #'my-vino-rating-assign-extra-meta)

(defun my-vino-rating-assign-extra-meta (rating extra-data)
  "Assign extra meta for RATING note.

EXTRA-DATA contains bottle-id."
  (let* ((wine (vulpea-note-meta-get rating "wine" 'note))
  
         ;; extract bottle id
         (bottle-id (assoc-default 'bottle-id extra-data))
         
         ;; get information about bottle
         (bottle (vino-inv-get-bottle bottle-id)))
    (vulpea-utils-with-note rating
      (vulpea-buffer-meta-set "bottle" bottle-id 'append)
      (vulpea-buffer-meta-set "volume" (vino-inv-bottle-volume bottle) 'append))))

Refer to the Inventory documentation for more information about bottles.