How do I get started as a new contributor?

Developers
#1

Hey folks,

I want to make some accessibility contributions but don’t know how to get started. For background, I have quite a bit of experience and am familiar with working with Node/NPM-based projects. I just don’t quite know how to work with this one.

For starters, I want to add role="region" to the sidebar. I believe I tracked this back to core\ui\PageTemplate\sidebar.tid. I added role="region" to:

<$scrollable fallthrough="no" class="tc-sidebar-scrollable" role="region" >

And now I guess I need to edit core\modules\widgets\scrollable.js. I do, adding a check for the attribute and a console.log for good measure. But either I’ve edited the wrong files, or restarting the server via:

tiddlywiki editions/tw5-com-server --listen

is the wrong command or is missing a step.

Are there any developer docs I’ve missed? I’ve googled but haven’t found much. Also, I’ll need to restart quite a bit. Does anyone have a favorite setup for handling hot reload of changes? Or at least something to restart the server so I can refresh from the browser without having to switch between 3 windows?

Thanks.

#2

Welcome to the club! :wink:

You are right. The attribute check has to be done in the $scrollable.js code.

Attributes are calculated in the .prototype.execute() function, where they are assigned to local object variables to keep them in the closure.

The DOM elements are created in the .render() function, where you can add the role, to one of the elements. … You have to choose the right one. Looking at the code atm, scrollable seems to create 2 DIVs … So a bit of testing needs to be done.

#3

The main TW concept is discussed at: https://tiddlywiki.com/dev/ … BUT there is no complete low level dev API docs. It mainly is the tests at: TiddlyWiki5/editions/test/tiddlers/tests at master · Jermolene/TiddlyWiki5 · GitHub and the source code.

We would absolutely appreciate help with this part of the docs.

#4

I personally don’t mind to manually restart the server. It’s probably a second to switch between the browser, the terminal window, restart the server and switch back to the browser or VSCode. … BUT I would like to assist to create a more automated workflow.

The last time I did test an automatic “save code” – “restart server” – “reload the browser tab” mechanism, the node “file watch” functions where not reliable enough on Windows.

So if we create something, we need to make sure it works with Linux, MacOS, Windows and a nice to have would be the possibility to make it work with a Docker “server container” too.

I did clone the TiddlyWiki repo and made a “npm link”, so it always uses my active source branch to start tiddlywiki with tiddlywiki .\editions\tw5.com-server --listen … (So your command looks rigth :wink:

#5

To start contributing, there also is a bit of bureaucracy.

See: https://tiddlywiki.com/#Contributing especially the CLA (contributor license agreement) section and How to sign the CLA.

2 Likes
#6

Thanks! The npm link was the missing piece. I wasn’t sure how the JS in the repository was pulled into the build that got loaded in the server. I guess that’s loaded by the executable in the repo, which I just linked.

I have a first batch of changes ready to PR. Just a few more quick questions:

  1. Is there a place to add non-user-visible translatable strings" I have an aria-label="Sidebar" on the sidebar region to indicate to screen readers what it is. This isn’t a button. Guessing Misc.multids might be the right place? If so, is there some sort of convention I should use for the ID, or is it fairly loosely enforced? I.e. would Sidebar/Accessibility/Label be a good key? I want to make it clear that this is a label for accessibility so someone doesn’t change it without context.

  2. Assuming I’m on the right track, how do I change aria-label="Sidebar" to aria-label="<my internationalized string>"?

  3. As a screen reader user myself, I want these changes in my current wiki. What would be the easiest way to do that? I assume I can build an HTML wiki from the repo pretty easily, and it should be easy to upgrade when these changes land in an official release?

Plugin updates are a bit difficult to manage with a screen reader right now, which is something I’d like to improve with guidance. Drag-and-drop of links is either impossible or so difficult that I don’t know how to do it personally. I know I can find and export/import plugin tiddlers, but the workflow for that isn’t nearly as easy and I haven’t done it in over a year, so I don’t remember how. That’s why I’m focusing on just rebuilding the whole wiki for now, rather than on making them part of a plugin.

Thanks.

1 Like
#7

Hi @nolan welcome to the project. Thanks for your questions, we really appreciate help making TiddlyWiki better for screenreader users. We aim for TiddlyWiki to be universal, which includes the idea of being available to everyone everywhere, with none of the usual barriers like money, or the inability for users to customise industrialised products.

The convention we use at the moment is to describe UI components with two language strings: /Hint for a long description of the component, and /Caption for a short description. We then reuse the caption as the aria label. You can see examples in core tiddlers such as $:/core/ui/Buttons/new-image.

We transclude the language string. For example:

<$button tooltip={{$:/language/Buttons/NewImage/Hint}} aria-label={{$:/language/Buttons/NewImage/Caption}} class=<<tv-config-toolbar-class>> actions={{$:/core/ui/Actions/new-image}}>

Excellent! That’s right: you’d maintain your own fork of TW5, periodically cherry picking commits into PRs to the core.

#8

Got it, thanks. So if I do something like:

Sidebar/Caption: Sidebar

in tiddlywiki5/languages/en-US/Misc.multids and transclude that into the aria-label, that should be good?

#9

Thanks everyone, think I’m getting the hang of this.

One final question and I’ll step away from this thread. I’m going to try merging all my accessibility fixes into a custom branch based off the latest release. I can rebuild an empty wiki for my own purposes, but how would I go about updating something existing? Note that I can’t drag-and-drop. Is there a plugin I can export and then import into an existing wiki to perform the upgrade?

Eventually I’d like to brainstorm a plugin installation/update mechanism that’s both accessible and as easy as drag-and-drop. I wonder if something might be made to use the clipboard? Like, add a “Copy Tiddler” button that dumps something on the clipboard, then when pasted, the event handler could determine that it’s getting tiddler text and perform the import transparently?

#10

Hi @nolan the first thing to note is that the usual upgrader at https://tiddlywiki.com/upgrade.html doesn’t require drag and drop; there is an <input type="file"/> in the centre of the page that summons a file open dialogue. From there you can select the TW HTML file that needs upgrading. Then there’s another “save” button to click to save the upgraded version.

I’m guessing that we don’t do a good job of marking that button for screen reader users?

Anyhow, rather than working with your own custom build could you just use the prerelease? The upgrader is available online so it might be fairly easy to use.

https://tiddlywiki.com/prerelease/upgrade.html

#11

Awesome, thanks. I did know about the online upgrader, but I didn’t know
there was a pre-release version. Excellent. Still need to figure out a
good story for installing third-party plugins–I know someone explained
how to export the tiddlers so everything is batched in a single file
that can be imported at once, I just need to dig up those instructions
and figure out if there’s any way to make the process more discoverable.

#12

Hi @nolan

As ever, improvements to discoverability are very welcome, particularly from your perspective as a screenreader user.

The general approach for installing third party plugins is to obtain the plugin as a file – either a JSON file that has been exported for the purpose, or a full TW HTML file that contains the plugins. Then one uses the “import” button in the “Tools” sidebar tab to start the import process. That brings up the $:/Import tiddler. One then uses the checkboxes to select just the plugins that you want to install, and then click the “import” button. Note that plugins that contain JavaScript code require a restart after installation in order for them to be fully activated.