XWIKI-21375: Videos on the help page don't have alternatives #2466

Sereza7 · 2023-10-11T09:13:59Z

Jira

https://jira.xwiki.org/browse/XWIKI-21375

Forum discussion

Handle videos in the help page

PR Changes

Changed the list items to anchors sending to different documentation pages
Added a hint to explicitly set the text alternative of the videos

View

We can see that now all list items under the videos are anchors that redirect to various sections of the documentation.

Notes

The way I implemented the solution we converged to in the discussion is based upon this example in a proposal of atomic rule for ACT. There is no designated role for alternative to videos in aria, we rely on the user's understanding.
I decided to add a non-visual hint to highlight the bond between the video and its text counterpart. This element would clutter the visual UI, and fills a role for AT users that presentation handles visually.

Here are all the pairs label + URL added in this PR:

* Changed the list items to anchors sending to different documentation pages

* Added a hint to explicitly set the text alternative of the videos

vmassol · 2023-10-11T09:19:29Z

I like it! I think it brings value and not just for impaired viewers but for everyone.
Thanks

vmassol · 2023-10-11T09:20:49Z

Discover how to create an application --> http://localhost:8080/xwiki/bin/view/Help/Applications/

I think this should be a link on xwiki.org since we also need a link on https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/

BTW shouldn't we have the same vides on https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/ than on your screenshot? I see only 4 at https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/ which is weird.

vmassol · 2023-10-11T09:21:18Z

For creating an app there's https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/GettingStarted/CreatingABasicApp

There's also https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/Creating%20A%20Contact%20Manager%20Application/

michitux

I have some doubts regarding the note. Also, the code style is quite inconsistent and I think there is missing escaping, see the detailed comments.

...m-core/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/Help/Videos/WebHome.xml

michitux · 2023-10-11T14:34:04Z

...ore/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/Help/Code/Translations.xml

@@ -192,6 +192,7 @@ help.videos.videoCard5.topic2=Learn how to use your application
 help.videos.videoCard6.title=Add / Remove Extensions
 help.videos.videoCard6.topic1=Discover how to add/remove extensions using the Extension Manager
 help.videos.videoCard6.topic2=Discover the XWiki Administration UI
+help.videos.hint=The video in this card is an alternative to the documentation behind those links:


I'm not sure a screen reader user is aware what "this card" is. Maybe rather something like:

Suggested change

help.videos.hint=The video in this card is an alternative to the documentation behind those links:

help.videos.hint=The following documentation links provide an alternative to the preceeding video:

but even then I'm not sure that it is clear to the user that there was a video, in particular as the iframe is marked with role="presentation". What about putting this information in the title of the iframe and maybe even removing the role="presentation"?

Addressed in 016b9d7 👍

I decided to remove the presentation role, and add the hint as an 'aria-description' to the iframe. This way, it can be read out to AT users and it's clearly concerning the content of this iframe. Updated the L10N value accordingly.

michitux · 2023-10-11T14:35:27Z

...m-core/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/Help/Videos/WebHome.xml

+      'url': $xwiki.getURL('Help.Applications.WebHome'),
+      'label': "$services.localization.render('help.videos.videoCard5.topic1')"


Why is the $xwiki.getURL not in quotes but $services.localization.render is?

Inconsistency 👍 Addressed in ae18d59 by removing quotes around the label values

* Fixed code style

* Escaped previously unescaped string

* Removed the role='presentation' from the iframe * Moved the hint to a description of the iframe

* Fixed code style

* Updated one link

* Avoided breaking backward compatibility on the velocity macro 'helpVideoCard'

Sereza7 · 2023-10-12T09:52:16Z

@vmassol

BTW shouldn't we have the same vides on https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/ than on your screenshot? I see only 4 at https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/ which is weird.

From what I could see, this page is custom content, none of the videos are the same.
This page uses a video card macro, which is very similar to the one I changed in this file. I updated the PR in 291a7a1 to ensure there's retrocompatibility of the velocity macro (even if not useful in this case).

For creating an app there's https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/GettingStarted/CreatingABasicApp

There's also https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/Creating%20A%20Contact%20Manager%20Application/

👍 I chose to use the first one:

We already used other steps of the getting started in other links here
The video highlights app creation with AWM, so the first link is more appropriate

Updated in 29f8879

All comments so far have been addressed.

vmassol · 2023-10-12T13:36:56Z

From what I could see, this page is custom content, none of the videos are the same.

hmm we might need to review this. I don't see how we would have enough manpower to have 2 sets of videos. We also need to check how much outdated both sets are.

I chose to use the first one:

I think the second one has more value but I've now linked the first one to the second so I believe it's now ok, see https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/GettingStarted/CreatingABasicApp?viewer=changes&rev1=7.2&rev2=8.1&

Thanks

michitux · 2023-10-17T09:24:33Z

...ore/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/Help/Code/Translations.xml

@@ -192,6 +192,7 @@ help.videos.videoCard5.topic2=Learn how to use your application
 help.videos.videoCard6.title=Add / Remove Extensions
 help.videos.videoCard6.topic1=Discover how to add/remove extensions using the Extension Manager
 help.videos.videoCard6.topic2=Discover the XWiki Administration UI
+help.videos.hint=The following documentation links provide an alternative to this video.


Maybe we should make this an actual description of the video? Like saying that you see a screencast showcasing the features that are listed below without audio (which could be interesting information for a blind user)?

Addressed in 758d90d 👍

michitux · 2023-10-17T09:27:24Z

...m-core/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/Help/Videos/WebHome.xml

    &lt;div class="videoCard-body"&gt;
      &lt;div class="videoCard-title"&gt;
        $escapetool.xml($data.title)
      &lt;/div&gt;
      &lt;ul&gt;
        #foreach ($topic in $data.topics)
-          &lt;li&gt;$topic&lt;/li&gt;
+          &lt;li&gt;#if ($topic.url)
+            &lt;a href="$escapetool.html($topic.url)"&gt;$topic.label&lt;/a&gt;


This needs to be $escapetool.xml as $escapetool.html doesn't escape {. Same for all other uses of $escapetool.html. Also, why is the label not escaped?

Also, why is the label not escaped?

I went too fast when updating the definition of the topics. I thought I'd factorize the escaping but forgot to add it back.

👍 Addressed in 61140f9

michitux · 2023-10-17T09:28:19Z

...m-core/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/Help/Videos/WebHome.xml

+          &lt;li&gt;#if ($topic.url)
+            &lt;a href="$escapetool.html($topic.url)"&gt;$topic.label&lt;/a&gt;
+          #else 
+            $topic


Same here, the topic should be escaped.

👍 Addressed in 61140f9

* Improved translation value

* Escaped properly strings in the velocity macro

Sereza7 · 2023-10-18T09:58:31Z

Addressed all comments :)

Sereza7 added 2 commits October 10, 2023 18:12

XWIKI-21375: Videos on the help page don't have alternatives

e8b3435

* Changed the list items to anchors sending to different documentation pages

XWIKI-21375: Videos on the help page don't have alternatives

dac6897

* Added a hint to explicitly set the text alternative of the videos

michitux requested changes Oct 11, 2023

View reviewed changes

Sereza7 added 6 commits October 11, 2023 17:12

XWIKI-21375: Videos on the help page don't have alternatives

ff76bbe

* Fixed code style

XWIKI-21375: Videos on the help page don't have alternatives

5a5e8eb

* Escaped previously unescaped string

XWIKI-21375: Videos on the help page don't have alternatives

016b9d7

* Removed the role='presentation' from the iframe * Moved the hint to a description of the iframe

XWIKI-21375: Videos on the help page don't have alternatives

ae18d59

* Fixed code style

XWIKI-21375: Videos on the help page don't have alternatives

29f8879

* Updated one link

XWIKI-21375: Videos on the help page don't have alternatives

291a7a1

* Avoided breaking backward compatibility on the velocity macro 'helpVideoCard'

michitux requested changes Oct 17, 2023

View reviewed changes

Sereza7 added 2 commits October 18, 2023 11:50

XWIKI-21375: Videos on the help page don't have alternatives

758d90d

* Improved translation value

XWIKI-21375: Videos on the help page don't have alternatives

61140f9

* Escaped properly strings in the velocity macro

michitux merged commit 877d3e6 into xwiki:master Oct 18, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

XWIKI-21375: Videos on the help page don't have alternatives #2466

XWIKI-21375: Videos on the help page don't have alternatives #2466

Sereza7 commented Oct 11, 2023

vmassol commented Oct 11, 2023

vmassol commented Oct 11, 2023

vmassol commented Oct 11, 2023 •

edited

michitux left a comment

michitux Oct 11, 2023

Sereza7 Oct 11, 2023

michitux Oct 11, 2023

Sereza7 Oct 11, 2023

Sereza7 commented Oct 12, 2023

vmassol commented Oct 12, 2023

michitux Oct 17, 2023

Sereza7 Oct 18, 2023

michitux Oct 17, 2023

Sereza7 Oct 18, 2023

michitux Oct 17, 2023

Sereza7 Oct 18, 2023

Sereza7 commented Oct 18, 2023

	help.videos.hint=The video in this card is an alternative to the documentation behind those links:
	help.videos.hint=The following documentation links provide an alternative to the preceeding video:

		'url': $xwiki.getURL('Help.Applications.WebHome'),
		'label': "$services.localization.render('help.videos.videoCard5.topic1')"

XWIKI-21375: Videos on the help page don't have alternatives #2466

XWIKI-21375: Videos on the help page don't have alternatives #2466

Conversation

Sereza7 commented Oct 11, 2023

Jira

Forum discussion

PR Changes

View

Notes

vmassol commented Oct 11, 2023

vmassol commented Oct 11, 2023

vmassol commented Oct 11, 2023 • edited

michitux left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sereza7 commented Oct 12, 2023

vmassol commented Oct 12, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sereza7 commented Oct 18, 2023

vmassol commented Oct 11, 2023 •

edited