From 4a75ab24398107ea2891741b2b534b045a9adb3c Mon Sep 17 00:00:00 2001 From: jygaulier Date: Mon, 18 Dec 2023 18:54:33 +0100 Subject: [PATCH] doc of feedback-report & stamper --- doc/feedback_report.md | 93 ++++++++++++++++++++++++++++++++++++++++++ doc/stamper.md | 74 +++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+) create mode 100644 doc/feedback_report.md create mode 100644 doc/stamper.md diff --git a/doc/feedback_report.md b/doc/feedback_report.md new file mode 100644 index 0000000000..70e210283e --- /dev/null +++ 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) diff --git a/doc/stamper.md b/doc/stamper.md new file mode 100644 index 0000000000..83ca020e81 --- /dev/null +++ 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 + + ... + +``` + +### 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 + +``` + +### Adding lines of text: +Each `` block defines a line of text +```xml + +Copyright NASA +``` + +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 +Credit: +Record-id: exported on +``` + + + +### 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. + + +