Poll WIP (#231):

* user documentation

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### New features
 
+* #231: [polls](https://livingston.frama.io/peertube-plugin-livechat/documentation/user/streamers/polls/).
 * #233: new option to [mute anonymous users](https://livingston.frama.io/peertube-plugin-livechat/documentation/user/streamers/moderation/).
 * #18: terms & conditions. You can configure terms&conditions on your instance that will be shown to each joining users. Streamers can also add [terms&conditions in their channels options](https://livingston.frama.io/peertube-plugin-livechat/documentation/user/streamers/terms/).
 

conversejs/custom/plugins/poll/styles/poll-form.scss

@@ -4,11 +4,14 @@
  * SPDX-License-Identifier: AGPL-3.0-only
  */
 
-livechat-converse-poll-form-modal {
-  /* Special case: when the form is in a modal */
+.conversejs {
+  livechat-converse-poll-form-modal {
+    /* Special case: when the form is in a modal */
 
-  .converse-form {
-    max-height: 50vh;
-    overflow-y: scroll;
+    .converse-form {
+      max-height: 50vh;
+      overflow-y: scroll;
+      padding-top: 0;
+    }
   }
 }

conversejs/custom/plugins/poll/templates/poll-form.js

@@ -2,11 +2,16 @@
 //
 // SPDX-License-Identifier: AGPL-3.0-only
 
+import { converseLocalizedHelpUrl } from '../../../shared/lib/help'
 import { html } from 'lit'
 import { __ } from 'i18n'
-
 export function tplPollForm (el) {
   const i18nOk = __('Ok')
+  // eslint-disable-next-line no-undef
+  const i18nHelp = __(LOC_online_help)
+  const helpUrl = converseLocalizedHelpUrl({
+    page: 'documentation/user/streamers/polls'
+  })
 
   return html`
     ${el.alert_message ? html`<div class="error">${el.alert_message}</div>` : ''}
@@ -14,7 +19,14 @@ export function tplPollForm (el) {
       el.form_fields
         ? html`
           <form class="converse-form" @submit=${ev => el.formSubmit(ev)}>
-            <p class="title">${el.title}</p>
+            <p class="title">
+              ${el.title}
+              <a href="${helpUrl}" target="_blank"><converse-icon
+                  class="fa fa-circle-question"
+                  size="1em"
+                  title="${i18nHelp}"
+              ></converse-icon></a>
+            </p>
             <p class="form-help instructions">${el.instructions}</p>
             <div class="form-errors hidden"></div>
 

languages/en.yml

@@ -573,10 +573,8 @@ poll_duration: Poll duration (in minutes)
 poll_anonymous_results: Anonymous results
 poll_choice_n: 'Choice {{N}}:'
 poll_end: 'Poll ends at:'
-poll_vote_instructions: |
-  To vote, click on your choice or send a message with an exclamation mark followed by your choice number (Example: !1).
-poll_vote_instructions_xmpp: |
-  Send a message with an exclamation mark followed by your choice number to vote. Example: !1
+poll_vote_instructions: "To vote, click on your choice or send a message with an exclamation mark followed by your choice number (Example: !1)."
+poll_vote_instructions_xmpp: "Send a message with an exclamation mark followed by your choice number to vote. Example: !1"
 poll_is_over: This poll is now over.
 poll_choice_invalid: This choice is not valid.
 poll_anonymous_vote_ok: Your vote is taken into account. Votes are anonymous, they will not be shown to other participants.

languages/fr.yml

@@ -555,9 +555,7 @@ poll_duration: Durée du sondage (en minutes)
 poll_anonymous_results: Résultats anonymes
 poll_choice_n: 'Choix {{N}} :'
 poll_end: 'Fin du sondage :'
-poll_vote_instructions: |
-  Pour voter, cliquez sur votre choix, ou envoyez un message avec un point d'exclamation suivi de votre choix (Exemple: !1).
-
+poll_vote_instructions: "Pour voter, cliquez sur votre choix, ou envoyez un message avec un point d'exclamation suivi de votre choix (Exemple: !1)."
 poll_is_over: Ce sondage est à présent terminé.
 poll_choice_invalid: Ce choix n'est pas valide.
 poll_anonymous_vote_ok: Votre vote a été pris en compte. Les votes sont anonymes, ils ne seront pas montrés aux autres participant⋅es.

support/documentation/content/en/documentation/user/streamers/polls.md

@@ -0,0 +1,88 @@
+---
+title: "Polls"
+description: "You can create polls to ask viewers their opinion."
+weight: 33
+chapter: false
+---
+
+{{% notice info %}}
+This feature comes with the livechat plugin version 10.2.0.
+{{% /notice %}}
+
+## Create a poll
+
+You can create a new poll by using the "{{% livechat_label new_poll %}}" action in the chat top menu:
+
+![Poll form](/peertube-plugin-livechat/images/polls_form.png?classes=shadow,border&height=200px)
+
+{{% notice warning %}}
+This poll feature should not be considered as a reliable voting system.
+It is easy to cheat.
+There is no mechanism to prevent anonymous users to vote multiple times by just reloading the chat.
+Votes are never fully anonymous, someone having access to the server could see who voted for what choice.
+{{% /notice %}}
+
+### Poll form
+
+Fill the form fields:
+
+* "{{% livechat_label poll_question %}}": the question to ask to you viewers
+* "{{% livechat_label poll_duration %}}": the duration for which viewers can vote
+* "{{% livechat_label poll_anonymous_results %}}": if checked, votes won't be publicly visible in the chat
+* "Choice N": choices that will be presented to viewers
+
+You must at least fill the two first choices fields.
+
+Once you submit the form, the poll will instantly start.
+
+If there was a previous unfinished poll, it will end and its result will be shown.
+
+### Access rights
+
+Every room's admins can create a new poll.
+
+When you promote someone as room admin or owner, they gets instant access to the "{{% livechat_label new_poll %}}" action.
+
+When you remove admin or owner rights to someone, they can't create new poll. But any existing poll will continue until it ends.
+
+Every user that is not muted can vote.
+This means that you can prevent anonymous users to vote by using the ["{{% livechat_label livechat_configuration_channel_mute_anonymous_label %}}" feature](/peertube-plugin-livechat/documentation/user/streamers/moderation).
+
+## Poll workflow
+
+When the polls starts, a first message will be sent in the chat, from the account of the user creating the poll.
+
+A banner will also appear to show the poll, and will be updated regularly with the current votes.
+
+![Poll start](/peertube-plugin-livechat/images/polls_start.png?classes=shadow,border&height=200px)
+
+Viewers can then vote by clicking on their choice, or by sending message like "!1" in the chat.
+
+Votes counts will be updated regularly in the banner.
+
+Viewers can change their vote at any time, just by making a new choice.
+Their precedent choice will be replaced by the new one.
+
+![Poll votes](/peertube-plugin-livechat/images/polls_votes.png?classes=shadow,border&height=200px)
+
+{{% notice tip %}}
+Anonymous viewers can only vote once they have choosen their nickname.
+{{% /notice %}}
+
+If "{{% livechat_label poll_anonymous_results %}}" is checked, votes won't be shown to other users.
+If unchecked, votes will be publicly visible as you will see message like "!1" in the chat.
+
+{{% notice info %}}
+For viewers using XMPP clients or outdated livechat plugin versions, the banner will not be visible.
+But they will see the message in the chat and will be able to vote by sending messages with their choices.
+{{% /notice %}}
+
+When the poll ends, a new message will be sent in the chat, with the results.
+
+![Poll end](/peertube-plugin-livechat/images/polls_start.png?classes=shadow,border&height=200px)
+
+{{% notice info %}}
+The only way to get old polls results is to search for the poll end message in the chat.
+For now, polls results are not saved by any other means.
+So don't forget to note polls results if you want to keep them.
+{{% /notice %}}