Alt text

[dphiffer]

Overview

Adds an alt text mechanism for images and videos (see: #549). The interface for creating a new post works the same, but this PR adds new user interfaces for reading/editing alt text.

• Initially images get alt="No alt provided" and a prompt below the image to "add some alt text"
• Clicking the "add some alt text" prompt shows an editing interface similar to the description field
• Once the alt text is added, an "alt text" link appears below the image or video to toggle showing the alt text on the page (the default state is that alt text is not shown)
• The edit form has a link to a new FAQ entry about alt text and how to write good visual descriptions
• ~The visual interface for reading the alt text on the page is hidden from screen readers with aria-hidden="true"~ I changed my mind on this one, the visual interface is accessible from screen readers.

See also: https://github.com/MLTSHP/mltshp-patterns/pull/1024

Screenshots

Todo list

• [x] Add alt text to video template
• [x] Make the alt text editor reachable from a screen reader
• [x] Get alt_text into the search index
• [x] Focus the textarea when editing alt text / description
• [x] Figure out what should replace the 0000 part of my migration filename
• [x] Write the "about alt text" page / FAQ entry
• [x] Add unit tests
• [x] API support
• [x] Finalize the UX for editing alt text

[jessamynwest]

We can add a little "about alt text" in to the FAQ (and I agree probably shouldn't be linking to twitter, even though that Robot Hugs thing is perfect) how about this page that @spaceninja mentioned above? https://axesslab.com/alt-texts/

[bradchoate]

Thanks for picking this up! It looks pretty good. I see you have some things left to do. If it isn't too much to ask, you might include these as well:

• Unit tests... an update to test/FileTests.py to add a unit test for the new routes for editing alt text.
• API support... handlers/api.py has two routines that would need an update to accept alt text for new posts (FileUploadHandler.post) and for edits (SharedfileHandler.post). For including the property in other API endpoints, an update to the model would be needed (models/sharedfile.py and Sharedfile.as_json, specifically). Some updates to test/functional/api_tests.py could be included as well to assert that alt text is accepted for new posts and returned in feeds.

And a usability issue that is a holdover for other "quick edit" fields. Clicking the prompt that displays the input should cause the input to receive focus.

[dphiffer]

Yeah, I think I can get those things in. Adding to the Todo punch list. Thanks @bradchoate!

BTW do you happen to know what the hash-looking things are in the db migration filenames?

[bradchoate]

The migration file name is generated by the yoyo new command:

usage: yoyo new [-h] [--config CONFIG] [-v] [-b] [--no-config-file] [--message MESSAGE] [--sql] [--migration-table MIGRATION_TABLE] [-d DATABASE]
                [sources ...]

It looks like it formats a filename as yyyymmdd_nn_xxxx-message.py Where "nn" is "01" or more if there are other scripts for that same date. The "xxxxx" part is just a random alphanumeric string (not really sure why they include it). "message" portion is the lowercased translation of the "--message" switch. Source for the routine that makes the filename can be found here.

[dphiffer]

Ah thank you, that makes sense!

[dphiffer]

Thank you for those text edits @spaceninja!

[bradchoate]

Not a big deal, but migration files should generally not be renamed, since it's possible someone has at this point run a migration on their local dev installation (like me!). Changing the name makes it appear as an un-processed migration since yoyo keeps the migration states in a table and records the migration file name there. So, running the migration step afterward will fail.

If you have to revise a migration, or anything like that, include instructions in the PR to anyone that may be needing them. Yoyo has commands to reapply a migration (useful for changing the content of a migration -- issues a rollback for it, then runs it again), and also commands to unmark and mark a migration (useful in this case since it doesn't do anything but update the migration table).

[dphiffer]

Got it, thanks @bradchoate. I probably should've just left it as 0000!

[dphiffer]

I removed the "Draft" from the title, and uploaded a short demo video to show how it works: https://mltshp.com/p/1P4TE

[spaceninja]

~Related pattern library changes have been merged, and I just opened #711 to update the pattern library here to the new version.~

Whoops, should have looked closer, you've already done that as part of this. Nice work!