Links to online documentation:

* Adding a help button on top of the chat, that links to the online documentation on frama.io.
* Replaced github.io documentation links by frama.io documentation.
* Adding links to the documentation in the diagnostic tool.

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### New Features
 
+* Adding a help button on top of the chat, that links to the online documentation on frama.io.
 * Implementing the [FEP-1970](https://codeberg.org/fediverse/fep/src/branch/main/fep/1970/fep-1970.md) draft for ActivityPub chat declaration.
 * Podcast RSS feed support (thanks to [Alecks Gates](https://github.com/agates)).
 
@@ -12,6 +13,8 @@
 * Translation updates.
 * Documentation can now also be translated using [Weblate](https://weblate.framasoft.org/projects/peertube-livechat/peertube-plugin-livechat/).
 * Documentation can use hugo shortcode livechat_label to get application strings.
+* Replaced github.io documentation links by frama.io documentation.
+* Adding links to the documentation in the diagnostic tool.
 
 ## 7.1.0
 

assets/images/help.svg

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="16"
+   height="16"
+   viewBox="0 0 4.2333332 4.2333334"
+   version="1.1"
+   id="svg1428"
+   inkscape:version="1.0.2 (e86c870879, 2021-01-15)"
+   sodipodi:docname="help.svg"
+   inkscape:export-xdpi="9.6000004"
+   inkscape:export-ydpi="9.6000004">
+  <defs
+     id="defs1422" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="7.919596"
+     inkscape:cx="-17.648117"
+     inkscape:cy="-26.635604"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     inkscape:document-rotation="0"
+     showgrid="false"
+     inkscape:window-width="1857"
+     inkscape:window-height="1016"
+     inkscape:window-x="0"
+     inkscape:window-y="1077"
+     inkscape:window-maximized="1"
+     units="px" />
+  <metadata
+     id="metadata1425">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Calque 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <path
+       id="rect1876-6-3"
+       style="display:inline;opacity:0.998;fill:none;fill-opacity:1;stroke:#7d7d7d;stroke-width:0.529167;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 1.4794425,1.5830698 5e-7,-0.723613 c -5e-7,-0.17175814 0.085244,-0.31003323 0.1911302,-0.31003308 l 0.892189,-2.1e-7 c 0.1058843,2.12e-6 0.1911286,0.13827105 0.1911285,0.31003556 l -3e-7,0.83722633 c -10e-8,0.1717589 -0.1075818,0.2191497 -0.191131,0.2841985 L 2.1592073,2.2950768 C 2.0234338,2.4007858 1.9400782,2.5290177 1.9377428,2.7839064 l -0.00226,0.2468256"
+       sodipodi:nodetypes="cssssssssc" />
+    <rect
+       style="display:inline;fill:#7d7d7d;stroke-width:0.235169"
+       id="rect841"
+       width="0.52883095"
+       height="0.59673518"
+       x="1.6701595"
+       y="3.4287369" />
+  </g>
+</svg>

client/@types/global.d.ts

@@ -3,6 +3,7 @@ declare const PLUGIN_CHAT_SHORT_NAME: string
 
 // Constants that begins with "LOC_" are loaded by build-client.js, reading the english locale file.
 // See the online documentation: https://johnxlivingston.github.io/peertube-plugin-livechat/contributing/translate/
+declare const LOC_ONLINE_HELP: string
 declare const LOC_OPEN_CHAT: string
 declare const LOC_OPEN_CHAT_NEW_WINDOW: string
 declare const LOC_CLOSE_CHAT: string

client/settings.ts

@@ -1,6 +1,10 @@
 interface MessageWithLevel {
   level: 'info' | 'warning' | 'error'
   message: string
+  help?: {
+    url: string
+    text: string
+  }
 }
 
 interface Result {
@@ -63,8 +67,15 @@ function launchTests (): void {
           } else if (message.level === 'error') {
             messageSpan.style.color = 'red'
           }
-          messageSpan.textContent = message.message
+          messageSpan.textContent = message.message + ' ' // adding a space, in case there is a help button
           messageLi.append(messageSpan)
+
+          if (message.help) {
+            const helpButton = document.createElement('a')
+            helpButton.href = message.help.url
+            helpButton.textContent = message.help.text
+            messageLi.append(helpButton)
+          }
         }
         messageUl.append(messageLi)
       }

client/videowatch-client-plugin.ts

@@ -1,8 +1,9 @@
 import type { Video } from '@peertube/peertube-types'
 import type { RegisterClientOptions } from '@peertube/peertube-types/client'
 import { videoHasWebchat, videoHasRemoteWebchat } from 'shared/lib/video'
+import { helpUrl } from 'shared/lib/help'
 import { logger } from './videowatch/logger'
-import { closeSVG, openBlankChatSVG, openChatSVG, shareChatUrlSVG } from './videowatch/buttons'
+import { closeSVG, openBlankChatSVG, openChatSVG, shareChatUrlSVG, helpButtonSVG } from './videowatch/buttons'
 import { displayButton, displayButtonOptions } from './videowatch/button'
 import { shareChatUrl } from './videowatch/share'
 import { getIframeUri } from './videowatch/uri'
@@ -79,12 +80,14 @@ function register (registerOptions: RegisterClientOptions): void {
         peertubeHelpers.translate(LOC_OPEN_CHAT),
         peertubeHelpers.translate(LOC_OPEN_CHAT_NEW_WINDOW),
         peertubeHelpers.translate(LOC_CLOSE_CHAT),
-        peertubeHelpers.translate(LOC_SHARE_CHAT_LINK)
+        peertubeHelpers.translate(LOC_SHARE_CHAT_LINK),
+        peertubeHelpers.translate(LOC_ONLINE_HELP)
       ]).then(labels => {
         const labelOpen = labels[0]
         const labelOpenBlank = labels[1]
         const labelClose = labels[2]
         const labelShareUrl = labels[3]
+        const labelHelp = labels[4]
 
         const iframeUri = getIframeUri(registerOptions, settings, video)
         if (!iframeUri) {
@@ -130,6 +133,17 @@ function register (registerOptions: RegisterClientOptions): void {
             additionalClasses: []
           })
         }
+        groupButtons.push({
+          buttonContainer,
+          name: 'help',
+          label: labelHelp,
+          href: helpUrl({
+            page: 'documentation/user/viewers'
+          }),
+          targetBlank: true,
+          icon: helpButtonSVG,
+          additionalClasses: []
+        })
 
         // If more than one groupButtons:
         // - the first must have class 'peertube-plugin-livechat-multi-button-main'

client/videowatch/button.ts

@@ -1,38 +1,49 @@
 import type { SVGButton } from './buttons'
 import { logger } from './logger'
 
-interface displayButtonOptions {
+interface displayButtonOptionsBase {
   buttonContainer: HTMLElement
   name: string
   label: string
-  callback: () => void | boolean
   icon?: SVGButton
   additionalClasses?: string[]
 }
 
-function displayButton ({
-  name,
-  label,
-  callback,
-  buttonContainer,
-  additionalClasses,
-  icon
-}: displayButtonOptions): void {
+interface displayButtonOptionsCallback extends displayButtonOptionsBase {
+  callback: () => void | boolean
+}
+
+interface displayButtonOptionsHref extends displayButtonOptionsBase {
+  href: string
+  targetBlank?: boolean
+}
+
+type displayButtonOptions = displayButtonOptionsCallback | displayButtonOptionsHref
+
+function displayButton (dbo: displayButtonOptions): void {
   const button = document.createElement('a')
   button.classList.add(
     'orange-button', 'peertube-button-link',
     'peertube-plugin-livechat-button',
-    'peertube-plugin-livechat-button-' + name
+    'peertube-plugin-livechat-button-' + dbo.name
   )
-  if (additionalClasses) {
-    for (let i = 0; i < additionalClasses.length; i++) {
-      button.classList.add(additionalClasses[i])
+  if (dbo.additionalClasses) {
+    for (let i = 0; i < dbo.additionalClasses.length; i++) {
+      button.classList.add(dbo.additionalClasses[i])
     }
   }
-  button.onclick = callback
-  if (icon) {
+  if ('callback' in dbo) {
+    button.onclick = dbo.callback
+  }
+  if ('href' in dbo) {
+    button.href = dbo.href
+  }
+  if (('targetBlank' in dbo) && dbo.targetBlank) {
+    button.target = '_blank'
+  }
+  if (dbo.icon) {
     try {
-      const svg = icon()
+      const svg = dbo.icon()
       const tmp = document.createElement('span')
       tmp.innerHTML = svg.trim()
       const svgDom = tmp.firstChild
@@ -40,14 +51,14 @@ function displayButton ({
         button.prepend(svgDom)
       }
     } catch (err) {
-      logger.error('Failed to generate the ' + name + ' button: ' + (err as string))
+      logger.error('Failed to generate the ' + dbo.name + ' button: ' + (err as string))
     }
 
-    button.setAttribute('title', label)
+    button.setAttribute('title', dbo.label)
   } else {
-    button.textContent = label
+    button.textContent = dbo.label
   }
-  buttonContainer.append(button)
+  dbo.buttonContainer.append(button)
 }
 
 export type {

client/videowatch/buttons.ts

@@ -99,11 +99,24 @@ const shareChatUrlSVG: SVGButton = () => {
 `
 }
 
+const helpButtonSVG: SVGButton = () => {
+  // This content comes from the file assets/images/help.svg, after svgo cleaning.
+  // To get the formated content, you can do:
+  // xmllint dist/client/images/url.svg --format
+  // Then replace the color by `currentColor`
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 4.233 4.233">
+  <path style="display:inline;opacity:.998;fill:none;fill-opacity:1;stroke:currentColor;stroke-width:.529167;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" d="M1.48 1.583V.86c0-.171.085-.31.19-.31h.893c.106 0 .19.139.19.31v.838c0 .171-.107.219-.19.284l-.404.314c-.136.106-.219.234-.221.489l-.003.247"/>
+  <path style="display:inline;fill:currentColor;stroke-width:.235169" d="M1.67 3.429h.529v.597H1.67z"/>
+</svg>
+`
+}
+
 export {
   closeSVG,
   openChatSVG,
   openBlankChatSVG,
-  shareChatUrlSVG
+  shareChatUrlSVG,
+  helpButtonSVG
 }
 export type {
   SVGButton

languages/en.yml

@@ -1,3 +1,4 @@
+online_help: "Help"
 open_chat: "Open chat"
 open_chat_new_window: "Open chat in a new window"
 close_chat: "Close chat"
@@ -31,7 +32,7 @@ connect_using_xmpp_help: "You can connect to the room using an external XMPP acc
 important_note_title: "<h3>Important notes</h3>"
 important_note_text: |
   You can find the plugin documentation here:
-  <a href="https://johnxlivingston.github.io/peertube-plugin-livechat/" target="_blank">
+  <a href="https://livingston.frama.io/peertube-plugin-livechat/" target="_blank">
     Peertube Plugin Livechat documentation
   </a>.
 

server/lib/diagnostic/index.ts

@@ -4,6 +4,7 @@ import { TestResult, newResult } from './utils'
 import { diagDebug } from './debug'
 import { diagProsody } from './prosody'
 import { diagVideo } from './video'
+import { helpUrl } from '../../../shared/lib/help'
 
 export async function diag (test: string, options: RegisterServerOptions): Promise<TestResult> {
   let result: TestResult
@@ -16,6 +17,20 @@ export async function diag (test: string, options: RegisterServerOptions): Promi
     result = await diagVideo(test, options)
   } else if (test === 'prosody') {
     result = await diagProsody(test, options)
+  } else if (test === 'everything-ok') {
+    result = newResult(test)
+    result.label = 'Everything seems fine'
+    result.messages = [{
+      level: 'info',
+      message: 'If you still encounter issues with the plugin, check this documentation page:',
+      help: {
+        text: 'Plugin troubleshooting',
+        url: helpUrl({
+          page: 'documentation/installation/troubleshooting'
+        })
+      }
+    }]
+    result.ok = true
   } else {
     result = newResult(test)
     result.messages.push('Unknown test')

server/lib/diagnostic/prosody.ts

@@ -3,6 +3,7 @@ import { getProsodyConfig, getProsodyConfigContentForDiagnostic, getWorkingDir }
 import { checkProsody, getProsodyAbout, testProsodyCorrectlyRunning } from '../prosody/ctl'
 import { newResult, TestResult } from './utils'
 import { getAPIKey } from '../apikey'
+import { helpUrl } from '../../../shared/lib/help'
 import * as fs from 'fs'
 
 const got = require('got')
@@ -190,7 +191,16 @@ export async function diagProsody (test: string, options: RegisterServerOptions)
     if (testResult.ok === true) {
       result.messages.push('API Prosody -> Peertube is OK')
     } else {
-      result.messages.push('API Prosody -> Peertube is KO. Response was: ' + JSON.stringify(testResult))
+      result.messages.push({
+        level: 'error',
+        message: 'API Prosody -> Peertube is KO. Response was: ' + JSON.stringify(testResult),
+        help: {
+          text: 'Check the troubleshooting documentation.',
+          url: helpUrl({
+            page: 'documentation/installation/troubleshooting'
+          })
+        }
+      })
       return result
     }
   } catch (error) {
@@ -226,5 +236,6 @@ export async function diagProsody (test: string, options: RegisterServerOptions)
   }
 
   result.ok = true
+  result.next = 'everything-ok'
   return result
 }

server/lib/diagnostic/utils.ts

@@ -1,8 +1,12 @@
-type nextValue = 'backend' | 'debug' | 'webchat-video' | 'prosody'
+type nextValue = 'backend' | 'debug' | 'webchat-video' | 'prosody' | 'everything-ok'
 
 interface MessageWithLevel {
   level: 'info' | 'warning' | 'error'
   message: string
+  help?: {
+    url: string
+    text: string
+  }
 }
 export interface TestResult {
   label?: string

shared/lib/help.ts

@@ -0,0 +1,17 @@
+function helpUrl (options: {
+  lang?: string
+  page?: string
+}): string {
+  let url = 'https://livingston.frama.io/peertube-plugin-livechat/'
+  if (options.lang && /^[a-zA-Z_-]+$/.test(options.lang)) {
+    url = url + options.lang + '/'
+  }
+  if (options.page && /^[\w/-]+$/.test(options.page)) {
+    url = url + options.page + '/'
+  }
+  return url
+}
+
+export {
+  helpUrl
+}