doc of feedback-report & stamper (#4447)

2025-10-17 06:53:15 +00:00 · 2023-12-20 16:34:08 +01:00
parent 7d72143ff2
commit 9b34492d97
2 changed files with 167 additions and 0 deletions
--- a/doc/feedback_report.md
+++ b/doc/feedback_report.md
@@ -0,0 +1,93 @@
+# feedback_report
+
+`bin/console feedback_report`
+
+Reports closed (expired) feedback result (votes) on every record.
+
+### CLI options
+
+`--min_date=yyy-mm-dd` will only act on feedback sessions opened (basket creation) __from__ this date.
+This allows to __not__ report "antique" feedbacks. 
+
+`--report=(all | condensed)` report per record or per feedback.
+
+`--dry` list actions but do not apply.
+
+### Run
+For every record of a recently expired feedback, results are computed (number of voters, number of "yes", etc.).
+
+Results can be used in `actions` to compute the value to set for status-bit or field.
+The value to set is computed using a __twig__ formula, allowing for e.g. to set a sb to check that 
+every voter has voted on the record, if at least 1/3 of voters voted "yes", etc...
+
+Multiple actions allow to act on different sb / fields, using different value-formulas.
+
+Because a feedback can contain records from different databoxes with different structures, a `databoxes` filter 
+can be specified for an action. This action will be played only if the current record belongs to one of those.
+
+### Participants _vs_ voters
+
+Only users who can vote are taken in account to compute the results.
+
+### Multiple feedbacks
+
+Because a record can be part of multiple feedbacks, only the __most recently closed__ feedback is used to
+report users votes.
+
+Every record will preserve the reported status of its __last__ feedback session, until a most recent 
+feedback session expires.
+
+If a feedback expiration date is extended (even after the previous expiration has passed), the report will 
+be updated afert the expiration on the new delay.
+
+
+### Configuration example
+
+e.g. for a status-bit value:
+```yaml
+# config/configuration.yaml
+...
+feedback-report:
+  enabled: true
+  actions:
+    action_unvoted:
+      # if any participant has not voted, set the "incomplete" icon
+      status_bit: 8
+      value: '{% if vote.votes_unvoted > 0 %} 1 {% else %} 0 {% endif %}'
+
+    action_red:
+      # if _any_ vote is "no", set the red flag
+      status_bit: 9
+      value: '{% if vote.votes_no > 0 %} 1 {% else %} 0 {% endif %}'
+
+    action_log_1:
+      databoxes:
+        # only those 2 databoxes have a dedicated field for textual history
+        dbMyDatabox  # one can use db name
+        12           # sbas_id
+      metadata: 'Feedbacks_history'
+      value: 'Vote initated on {{ vote.created }} by {{ initiator ? initiator.getEmail() : "?" }} expired {{ vote.expired }} : {{ vote.voters_count }} participants, {{ vote.votes_unvoted }} unvoted, {{ vote.votes_no }} "no", {{ vote.votes_yes}} "yes".'
+
+    action_log_2:
+      databoxes:
+        # same report, but on another field
+        34
+        56
+      metadata: 'Comment'
+      value: 'Vote initated on {{ vote.created }} by {{ initiator ? initiator.getEmail() : "?" }} expired {{ vote.expired }} : {{ vote.voters_count }} participants, {{ vote.votes_unvoted }} unvoted, {{ vote.votes_no }} "no", {{ vote.votes_yes}} "yes".'
+
+```
+
+### twig context
+
+To compute the `value` of a status-bit or field, the twig formula can use:
+- `vote.votes_unvoted`: the number of voters that has not voted on this record
+- `vote.votes_yes`: the number of voters that has voted yes
+- `vote.votes_no`: the number of voters that has voted no
+- `vote.voters_count`: the number of voters (sum of yes, no, unvoted)
+- `vote.basket_id`
+- `vote.sbas_id`
+- `vote.record_id`
+- `vote.created`: the creation date of feedback request
+- `vote.expired`: the expiration date 
+- `initiator`: the initiator (__user__ object) 
--- a/doc/stamper.md
+++ b/doc/stamper.md
@@ -0,0 +1,74 @@
+# Stamper
+
+Adds banner(s) on document or previews downloads, to include information like a logo, text or metadata.
+
+Stamp is possible on most bitmap image documents (jpeg, png, gif, ...), but may not work on specific formats like multi-layers tif.
+
+To configure Stamper, edit the collection’s setting using the XML view in Collection settings section (the user must have Manage value lists right applied).
+
+### stamp
+Each `stamp` block configures one banner, declaring its position:
+- position="TOP": On top of the image
+- position="BOTTOM": Under the image
+- position="TOP-OVER": On top, over the image (to use with a (semi)transparent background color)
+- position="BOTTOM-OVER"
+
+One can define the color of the background
+
+```xml
+<stamp position="BOTTOM-OVER" background="255,255,255,32">
+    ...
+</stamp> 
+```
+
+### Adding a logo:
+First upload a logo (jpg, png) using the Admin interface in the corresponding collection(s).
+
+Declare the logo inside the stamp block, set to the left side of the banner.
+```xml
+<logo position="left" width="25%"/>     <!-- 1/4 of the image width -->
+```
+
+### Adding lines of text:
+Each `<text...>` block defines a line of text
+```xml
+<!-- big white text with transluant black shadow --> 
+<text size="150%" color="255,255,255,0" shadow="0,0,0,64">Copyright NASA</text>
+```
+
+text can **include** variable parts, like **field** value (metadata) from the record, or technical
+**var**iables like the record_id or the date of export
+```xml
+<text size="50%" color="0,0,0,0">Credit: <field name="Credit" /></text>
+<text size="50%" color="0,0,0,0">Record-id: <var name="RECORD_ID" /> exported on <var name="DATE" /></text>
+```
+
+
+
+### About colors
+Colors are expressed as `"R,G,B,t"`, with R,G,B: 0...255 ; t is the transparency, with 0: opaque...127: transparent.
+
+t can be ommited, in case the color is opaque.
+
+### About shadow (text)
+The plain-colored text can be unreadable if its color matches the image color.
+
+Setting an opposite shadow color will enhance readability. Printing semi-transparant text over a shadow can
+simulate a 3D look.
+
+
+### About sizes
+Size applies to logo (`width` attribute) or text (`size` attribute).
+
+Sizes can be expressed as asolute (e.g. `width="100"`) or relative to the image width (e.g. `width="25%"`).
+
+Because one can download a hi-res document like 6000 * 4000 pixels, or a smaller preview like 800 * 600, using relative
+sizes will generate stamps with similar "look" relative to the image size.
+
+For a `logo`, the relative size `width="25%"` will render the logo as 1/4 of the width of the image.
+
+For a `text`, the `size="100%"` will fit ~60 characters on the image width.
+This ensures a readable text even for small size previews.
+
+
+