ADA Compliance - Everything you need

ADA Compliance

Making a website ADA compliant is a multistep process that cannot be completed with the single installation of a WordPress plugin.

Step 1: Understand the Guidelines

The WCAG 2.0 Guidelines are the legal standard for compliance. Documentation can be found here explaining the guidelines in full. A more digestible checklist is available here to get a quicker overview of the requirements. There are three levels of ADA compliance: A, AA, and AAA. Aim for AA at minimum if you can. Read more about the differences between the levels here.

Step 2: Evaluate your Website

https://wave.webaim.org/ is a free ADA compliance checker tool. It will point out exactly what errors your website has and will even direct you to the part of the HTML code where it found the error.

Step 3: Become Compliant

Becoming Compliant may take a few weeks work depending on your website. If using a WordPress site, investigate both native and plugin solutions. Alternative text can be added in the Media Library, although it may or may not be automatically updated to your pages depending on your website theme. Skip Links can be easily added with a plugin like the ADA Accessibility Helper. Color Contrast can hopefully be edited via your theme, or you can hardcode those changes locally via the CSS file.

Step 4: Remain Compliant

It is important to properly train the organization not only at the higher level understanding of compliance but at the lower level in making changes to the website. You wouldn’t want your revised website to slowly revert back out of compliance so having usable and clear user, admin, and developer guides is vital as well as having training sessions with relevant individuals.

Editing WordPress Source Code

Is your client’s template not compatible with the block editor? Do you struggle to make basic changes to your website’s appearance? Don’t worry! You are not the first team stuck with this problem, and your predecessors have the perfect solution for you: editing your website's source code.

Buried deep in the heart of your WordPress site lies code just like any other website. WordPress sites are built on an annoying complicated infrastructure of PHP files. Those PHP files when executed then retrieve HTML code blocks from the WordPress backend which, combined with your website's CSS file magically transmutes into a functional website.

“But I don’t know PHP or CSS or HTML!” You say alarmed. No, they certainly didn’t teach it in MIS304. But it's ok, you’ll live. They are relatively easy to pick up especially as you won’t be coding from scratch and instead just modifying existing files. Google can teach you anything your classes won’t.

So, now that you’ve decided you want to edit your website's source code (Oh boy!), you are going to need a couple things. The first is to host your website locally on your machine.

Why You Need to Host The Source Code On Your Machine With Fancy Software

All right so let’s think for a minute more on how WordPress is really working here. So your client has PHP files that summon chunks of HTML from the abyss to make a working website. But where exactly is that HTML coming from? And how does the admin page of my clients website even exist? You won’t find the PHP for that page in your file manager.

WordPress, at its most simple, is like any other computer program, and like any computer program it has to be hosted (aka run) on a machine. Typically, your client will be paying Some Big Company ™ to host their website for them on some remote server in the middle of West Virginia, Kansas, or Nowheresville, North Dakota. (Think Bluehost, Flywheel, WP Engine, etc) [Sidenote: Our client used WP Engine, so we are going to pretend you are using WP Engine too but the following solution can be used with other hosting providers as well.]

But what’s even running? Isn’t it just some boring ‘ol PHP? Let’s oversimplify. Your client has paid some big company to install a copy of WordPress on a small corner of some server in the same way one installs iTunes. The PHP and CSS files that you see in your file manager are alot like iTunes songs. MP3 Files can’t play themselves, and need help from Mr. Apple to get the beats vibin and make noise. In the same way, the PHP files get chatty with the WordPress installation to create those beautiful pages of HTML.

If you edit an MP3 file, to hear your changes you would take the file you edited, cram it back into iTunes and enjoy because you can’t just download an MP3, edit it, and expect to listen to it without the help of some kind of software. WordPress? Same deal. If you are going to pull down your themes code and edit it on your machine, you are going to need to set up an environment on your computer just like the one that's being hosted so the PHP has the necessary files to load the HTML so you can witness your changes in real time without having to re-upload the file to the website after every minor tweak to see if it worked.

So like it or not, you are going to need to install some stuff.

Let’s Install Some Stuff

Ok cool, but what do I need to install? First things first you are going to need what is generically called a “local installation” of WordPress. There are lots of ways to do this. But we are going to talk through a solution that's fairly easy to set up and maintain and can actually connect to your remotely hosted WordPress environments to simplify pushing and pulling code from the actual website. The name for the software, however, is extremely confusing. It's called “Local”, which you may be aware is a term that refers to oh so many different things in the technology world. So, for the sake of clarity, when you google it and for the rest of the documentation, let “Local” be known as “Local by Flywheel”.

Part 1. Install Local by FlyWheel

1.1: Download and install Local by Flywheel: Instructions to Download Local

1.2 Set Up Development, Staging, and Production Environments

Now before you go onto the next part, let's chat a bit about good practices in website development. Big companies that have teams working on websites typically have 3 environments: Development, Staging, and Production. Development is where code gets edited. Once the developers think the code is stable, they push the code to Staging. Staging is where the BAs test your code and break it 6 ways to Sunday. Making these environments two different ecosystems mean that you can make the website unresponsive to start fixing the bugs as the BAs point them out. You don’t have to wait until they finish running tests. Once you complete the edits in Dev, you re-push to stage, they retest, and if it's all good your client gives it the green Light, and then finally you push to prod.

It's ok if every sprint you are just pushing to stage and then in the last week you push the 100% completed stable website to the production environment to go live. In all honesty, I 100% recommend this. It will save your heartache.

So chat with your team and decide how you want to deal with all this. And then Set up some development environments by copying over the production code.

1.3: Connect Local by Flywheel to WP Engine: Guide to Connect WP Engine API with Flywheel

If you are using a different hosting service google how to connect your API key with Local by Flywheel. It is possible to not connect your environments (some clients may not even let you do that). Instead, just go into your website and download a full backup of the website as a zip file. Then you can use that zip to set up your environment. It will be more difficult to push the code back into the production environment but it will be manageable.

If you can connect the API keys, set it all up so that Local by Flywheel connects to your Development Environment.

Part. 2 Pushing and Pulling in Local

Note: Please be aware that pushing and pulling in Local is not alike to Git. These pushes and pulls will overwrite all files and databases if selected at your target destination. We recommend connecting Git to Local by Flywheel to prevent risks of error. You can find a tutorial at the “Development with Git” section here.

Part 3: SCSS Files

If your source code has a bizarre number of SCSS files instead of CSS files, that means whoever wrote your website used Sass. Sass is basically just CSS but fancy. It allows you to separate all of your CSS code into different files and use inheritance to create variables and lots of other fun stuff that makes your life easier.

However, the downside of Sass is that everytime you edit the SCSS code you need to bundle those files into a bundle.CSS file that the PHP files can read. What this means for you: time to install more stuff.

There are 2 paths to do this: the easier is to just install Sass. But if your js files ALSO need bundling it may be faster to just skip to the section on js down below because that solution will bundle SCSS files as well (we think).

The following is an excerpt from our client documentation we assume you have a Mac, and have Node.js installed:

Part 3a Setting Up Sass

Step 1: Learn About Sass

Please keep in mind that Sass must be running throughout or after changes to the sCSS files in order for changes to take effect. The original website builders utilized Gulp, a Sass plugin, to manage CSS style sheets. We opted to not do that due to an inability to get the Gulp project dependencies set up correctly.

Step 2: Find SCSS Code

Click on the “CSS” folder in “themes” folder

Local Sites > carebox_dev_env > app > public > wp-content > themes > CSS

CSS is stored in the folder as SCSS as per Sass

Step 3: Executing Sass Functionality

The Following instructions assume you have npm installed.

Open Command Prompt

Type “npm install -g sass”

Enable Sass for editing session

You must cd into the file where the sCSS files that you wish to bundle are

Run command to start Sass

Sass --watch main.sCSS bundle.min.CSS

What this does is while it is running it will watch you edit all of the sCSS files and compile a new CSS file when u make changes to render the changes

Stop Sass

Press ctrl + c to make it stop

Part 4: Bundling JS Files

If you have a bundle.js file in your code, that means you are going to have to find a way to rebundle the js files every time you make an edit. It would be easiest to use the same bundling software that the original developers used. Webpack is a very popular option. However if you have a gulpfile.js located somewhere in your project (like we did) your developers used Gulp.

The following is a modified excerpt from our client documentation. We assume you have a mac and Node.js installed.

Part 4a. Setting Up Gulp

In the original development environment, Gulp was used to bundle both the JS and the SCSS files. They also may have used React. We aren’t entirely sure, but we chose to use Sass to bundle the SCSS due to the fact that the SCSS files are compatible with the latest version of Sass. Whereas, the Gulpfile.js that has the instructions to run the Gulp file is not compatible with Gulp 4. As a result, setting up Gulp is a lot more work than just installing Sass. We recommend you only set up Gulp if you need to bundle JS files.

**For UT Students we would recommend just trying to run the latest version of Gulp at first, then skip to step 7. If you hit an error that your gulpfile.js has errors, uninstall Gulp and try again with the below steps.

npm install --global gulp-cli

Step 1: Learn About Gulp

Step 2: Rollback node to version to 11.15.0

This could take a variety of steps in order to do depending on your current setup. We recommend googling how to rollback nodes on your machine and following those directions. It might take a little debugging though. You need rollback nodes due to the fact that the version of Gulp we are about to install is not compatible with the latest version of node.

Step 3: Install Gulp CLI version 2.3.0

npm install --global gulp-cli@2.3.0

Step 4: In the terminal, cd into your CareBOX file inside “Local Sites”

“Local Sites” > [your website dev environment name] >app > wp-content > themes > CareBOX

Step 5: Install Gulp version 3.9.1

npm install --save-dev gulp@3.9.1

Step 7: Run the gulp command to bundle JS.

In the terminal, type:

gulp

If this command runs successfully it should launch a localhost:3000 page in your browser that never actually loads. Just exit out of that and then ctrl+c in your terminal to get it to stop trying to load the localhost:3000 page and then you should be good to go. Retype gulp after making further changes.

It may fail and tell you that you need to install a dependency. Just google whatever dependency you need to install and find the npm install command for it, run it, and then try again.

Conclusion:

Whatever you do, just remember this. If you have to set up any of the above it's going to take about twice as long as you have planned. So word of the wise: keep your scope small. Better to underpromise and overdeliver. You can always agree to do more if you finish early. But regardless, best of luck!

-T.S. Solutions