Category: Web Development

Home / Category: Web Development

Some Thoughts from a WordPress User

As a developer, I find a lot of the ‘magical’ moments occurring from discovering new technology, platforms and applications which challenge the norm, or go beyond the tried and true to carve a path both familiar and unfamiliar to the user. While reading either Reddit or HackerNew (cannot remember origin sorry!), I saw a comment comparing popular CMS platforms to a modern abstract interpretation: Flat-File based CMS; namely, GRAV. I decided that I’d take a look. I wanted this look to be brief, similar to how one may compare this look to a spike in a sprint, where some time is spent identifying the viability of investing further efforts and time into the task.

I should preface this by explaining what is a Flat-file based CMS, and why it caught my attention compared to the hundreds of offerings to your typical LAMP stack. CMS Wire described a Flat-file CMS platform as:

[A flat-file CMS is] a platform that requires no database. Instead, it queries its data from a set of text files.


Because there’s no database involved, a flat-file CMS is supremely easy to deploy and super lightweight in terms of size. Some flat-file CMS even run on as little as five core files.

Flat-file content management systems allow for heightened speed, simplicity, mobility and security. Plus, they are an approachable solution for the less technical and underfunded.

Here are the key benefits of a flat-file CMS:

Quick Deployment: installation can be done with an FTP client alone.
Site Speed: thanks to the absence of database queries, sites load a lot faster.
Lightweight: flat-file platforms are typically very small in size.


Mobile: because they’re so small in size and because they have no databases, moving flat-file projects from server to server is a breeze.

The lack of database I found unique since this opens up potential performance benefits and NoSQL styled archiving through your own file storage; I’m a sucker for those which oppose the expected, so I was all in for trying this CMS type out. I decided to approach this overview similar to a user, instead of a developer who’d be integrating API’s and various other snippets into their project, to better understand how it compares to the average user of WordPress which powers the current site you are reading this on.

Installation and Setup

Every good developer follows the README and instructions, after attempting all implementation ideas first. I was no better, having overlooked the three quick-install directions for this already portable application. They are:

  1. Download either the Grav core or Grav core + Admin plugin installation package
  2. Extract the zip file into your webroot
  3. Point your browser at your local webserver: http://yoursite.com
Unzipped File System (default)

I downloaded the Core and Admin plugin package, and encountered two issues within seconds of attempting step three, they were:

  1. Renaming the folder after extracting would have been a better idea than moving all ‘public’ files outside the folder (essentially moving the folder structure up a tree node), because one of the hidden files that I neglected the first time which was critical was .htaccess.  
  2. Tested in my GoDaddy Playground domain (the-developers-playground.ca/grav/), I had to enable a few PHP modules and versions which I’m led to believe are commonly enabled by default. Not an issue, but not easily accessible to those navigating around various hosting provider’s interfaces and default configurations.

Once fixing those two, the setup process for creating your website and administrative account was smooth and quick. When finished, you’ll see the admin interface similar to this which alludes to a successful setup!

Default Administration Dashboard

Features

I’m currently playing with Grav v1.5.5, and version v1.8.14 of the Admin plugin.

Themes

What are the available themes like for GRAV? Well, if I had to summarize for those more aware of Drupal, WordPress and ModX’s offerings: stark. This is expected, I have no arguments or expectations about the available set being so low; it’s a brand new platform without the world-wide recognition of WordPress and other mature Content management systems which drives adoption and addon creation. At the time of writing this, there are 102 themes supported ‘officially’ in the addons portal -I am sure there is at least this amount in unofficial and unreleased themes as well scattered throughout GitHub. A few characteristics of the official themes that I’ve noticed are:

  1. Some are ports are popular themes and frameworks from other CMS offerings
  2. There are bountiful amounts of Foundation, Bootstrap and Bulma powered themes
  3. Many of these themes are geared towards three mediums:
    1. Blogs
    2. Websites
    3. Dynamic Resumes and Portfolios
MilliGRAV theme on the-developers-playground.ca/grav/

I certainly don’t have the qualifications to judge CMS themes, but I can say that if you are not in the mood of creating your own, there are plenty to choose from and extend as needed – You’ll see below that I chose one that I hope to extend into a dark theme if time and ambitions permit, but that’s another story for a different day. It appears new themes are published and updated weekly, which I think implies a growing ecosystem. I tried out the following themes, and currently have the Developers Playground instance  using the very last in the list below:

You can see the official ‘skeletons’ over here https://getgrav.org/downloads/skeletons, which provide a quick-start template and setup for various mediums. A nice addition for those unsure how they want to use GRAV just yet.

Plugins

If I wanted to be snarky, I’d say that I’m surprised there are still PHP developers in 2018. That would be ignorance and bias for the record, since PHP is still quite the lucrative language to know; almost every non .NET blog is powered by LAMP stacks even to this day -somewhere around 60% of the public internet is powered by PHP and WordPress, right? The saying goes something like that at least. That also means, that there should be a plugin ecosystem growing with GRAV, right? At the time of writing this article, there are 270 plugins in the known GRAV community. These wonderful modules include:

  • YouTube
  • Widgets
  • Twitch
  • TinyMCE Editor
  • TinySEO
  • Ratings
  • SQLite
  • Slack
  • Smartypants
  • Music Card
  • LDAP
  • Lazy Loader
  • Twitter
  • GitHub

The list goes on and on, but I listed a few that I found intriguing. I plan on playing with a few and making the currently static root for the-developers-playground.ca into a GRAV site, which will link to my experiments and work while utilizing some of the plugins.

Portability & Git Sync

So, why did I find intrigue in a Database-less CMS? Well portability for one. If all you need is Nginx or Apache with the correct (and standardized) modules enabled, you can have everything up and running with no other dependencies or services to concern yourself over. It means that I can develop locally, and know that when I update the production side all of the data will be the same, alongside configurations, styles, and behaviors. On top of those benefits, it also meant that I could version control not just the platform, but the data using typical developer semantics.

There are multiple workflows which allow for version control of content, similar to Ghost and Jerkyll which caught my attention. If you want lightweight, you can version control the /user/pages folder alone, and even utilize a plugin such as Git Sync to automatically pick up webhooks from your favorite Git Platform upon each commit. That’s one way to get those green squares, right? I see this incredibly advantageous because it allows for a much more flexible system which doesn’t dictate how items are versioned and stored, and instead treats the overall platform and it’s content similar to how a Unix system would; everything is a file.

You can find all the details for utilization, development, and contributions over here: https://github.com/trilbymedia/grav-plugin-git-sync

Closing Comments

Once issue I noticed quite frequent in both the themes and plugins, is the reliance on the [insert pitchfork.gif] JQuery library for the vast majority of the UI heavy lifting. Moreso, the documentation and Discord channel appears to be quite helpful, so first impressions lead towards a developer-friendly environment where you can build out your theme and plugins when the community ones don’t fit your needs.

I noticed that many of the themes can be overwritten safely (meaning you can update and not break your custom styling), which gave me the sense that there’s plenty of foundation to work off of instead of starting from a blank slate. I like that, because I really enjoyed the aesthetic of MilliGRAV, but longed for a darker theme such as my typical website. I may experiment porting my color theme over and seeing how well that goes in my next experiment with GRAV.

All-in-all, I really enjoyed doing a quick sporadic walkthrough of this content management system and can see myself using it in the future when I want to migrate away from WordPress for clients and myself; perhaps even start clients there if  they have less requirements and needs. I even see it coming up even sooner for static sites that need an update, and CMS integration such as rayzplace.ca which is in dire need of a refresh. GRAV would fit perfectly there.

Bonus!

I decided while reviewing the article to build out two Dockerfiles which revolve around GRAV, one being a templated default started that you can run locally, and the other which copies from your custom GRAV directory to an apache server for development and testing. Both employ using port 8080, and could be configured for HTTPS if you want to further extend them! Default Grav (non-persistence) + Admin Dockerfile provided by the GRAV developers: https://github.com/getgrav/docker-grav

After further investigation, it appears the link above also describes a workflow similar to what I was going to suggest utilizing volumes. I’m removing my link and advocating theirs, which works.

References

https://www.cmswire.com/digital-experience/15-flat-file-cms-options-for-lean-website-building/
https://getgrav.org/

Hosted by GoDaddy, Leveraging Let’s Encrypt and ZeroSSL

At the start of 2018, Google made a major push to rank and direct users to HTTPS websites in effort to be more web-safe; a fantastic way to push for such security onto as many websites as possible, aimed at those who care about there search rankings, privacy, and consumers. This also meant that at the time of writing this article, I was already at least eight months behind on this -and GoDaddy was the persistent parent who always reminded me of the HTTPS push, alongside their one-click-install SSL certificates sold on top of their hosting packages. In 2018, who wants to invest hundreds for SSL just to spend as much (if not more) in the next?

I decided to try out Let’s Encrypt on both my WordPress blog site, and a static website which serves purely HTML files (for the manner of this test). Before we go about this tutorial, I figured that we should establish what defined a secure site and explain the motive of Let’s Encrypt, which I’ll be utilizing alongside the ZeroSSL tool. Though I can see where self-signed certificates are useful for high-end corporations and platforms, for your average website or application, Let’s Encrypt should be perfectly suited, and here is why I gather such opinion.

What is HTTPS / SSL?

How-To-Guide describes the differences between HTTP and HTTPS as the following:

HTTPS is much more secure than HTTP. When you connect to an HTTPS-secured server—secure sites like your bank’s will automatically redirect you to HTTPS—your web browser checks the website’s security certificate and verifies it was issued by a legitimate certificate authority. This helps you ensure that, if you see “https://bank.com” in your web browser’s address bar, you’re actually connected to your bank’s real website. The company that issued the security certificate vouches for them.

When you send sensitive information over an HTTPS connection, no one can eavesdrop on it in transit. HTTPS is what makes secure online banking and shopping possible.

It also provides additional privacy for normal web browsing, too. For example, Google’s search engine now defaults to HTTPS connections. This means that people can’t see what you’re searching for on Google.com.

If it wasn’t obvious because of the above, the following websites and applications should be avoided if they don’t support HTTPS as of now:

  • Shopping portals
  • Banking applications
  • Social media platforms
  • Applications which consume sensitive data

If it’s any incentive, Apple’s application programming manifest defaults to HTTPS requests, and attempts to make a non-secure API call must also override this default; often failing the application in the app store approval process if not corrected.

What’s Let’s Encrypt?

Found on Let’s Encrypt’s website:

The objective of Let’s Encrypt and the ACME protocol is to make it possible to set up an HTTPS server and have it automatically obtain a browser-trusted certificate, without any human intervention. This is accomplished by running a certificate management agent on the web server.

Working with GoDaddy & SSL Certificates

If you are using GoDaddy (as I am in this tutorial), one crucial item you need is access to your account’s full cPanel interface. The web hosting LAMP stack should come with the platform access by default, as opposed to the WordPress hosting tier which grants no such means. Without, you may be stuck having to purchase a Certificate from GoDaddy who will kindly also install it for you onto your website. But, what does that cost look like? Because this tutorial is revolving around a blog site, and a static website, I’m not going to tread anywhere beyond the standard consumer offerings; ones which hobbyist and developers would utilize.

According to 10/15/2018, the GoDaddy offerings are the following for SSL Certificates and installation:

Tier# Sites CoveredCost / Year
One WebsiteOne$70.00
Multiple WebsitesUp to Five$154.00
All Subdomains of a Single WebsiteOne, all Subdomains$311.50

There is one benefit that I see coming from GoDaddy’s offerings (which, if I may add is freely available on many other providers listed below), is that it’s a year-long valid SSL certificate, which greatly outlasts Let’s Encrypt standard 90 days. Not knocking the company, simply the product’s cost PER website.

ZeroSSL

ZeroSSL is a fantastic interactive tool which runs on top of Let’s Encrypt, allowing for even easier SSL certificate generation and management. I find it utterly helpful with managing and describing the steps required to obtain a valid LE certificate for your various domains.

Here is a step by step which follows the video titled ‘Install Godaddy SSL Certificate for Free – LetsEncrypt cPanel installation’ found in the ZeroSSL link below. I highly recommend following the video, since visually it makes a lot more sense compared to the steps below.

  1. Log in to cPanel.
  2. In a seperate tab, open zerossl.com.
  3. Click on ‘start’ button under ‘Free SSL Certificate Wizard’.
  4. Enter in your domains, you will be prompted to also include a www- prefixed variant.
  5. Select both checkboxes, click next.
  6. Select next again, which will generate account key.
  7. Download both the cert and private key for safe keeping.
  8. Hit next, where you are asked to verify you own the domain:
    1. Download the two files provided
    2. In your cPanel, open the file manager and navigate to the domain of choice.
    3. Create a folder in the domain titled .well-known
    4. Create a folder inside called acme-challenge, upload the two verification files to this directory.
    5. Once uploaded, click on the files in the ZeroSSL listings to verify. If you are able to see the keys coming from your domain, the next step will verify and confirm ownership successfully.
    6. Hit next to confirm
  9. Download the certificates generated in the last step, or copy them to your clipboard.
  10. In cPanel, navigate to Security->SSL->Manage SSL Sites
    1. Select your domain
    2. Add the first key (the certificate, which when copied contains two keys separated by the expected ---. Take the second key and put that into the last field (Certificate Authority Bundle).
    3. Copy the private key from ZeroSSL and put into the middle corresponding field.
  11. You should see green check marks which verify that the values provided are valid, and if so, click the ‘Install Certificate’ button. This will install the SSL certificate for that domain.
  12. Test by going to HTTPS://<YOUR_DOMAIN>, if you get a half-lock under HTTPS, see the topic below which describes what has to be done for a static site or WordPress site to be truly HTTPS compliant.

If the above worked, then you have a valid SSL certificate installed on your domain which will last 90 days! But, this is currently only accessible when a user types in ‘HTTPS’, so how do we default it? Adding the following lines to the bottom of the domain’s .htaccess file will reroute all traffic to HTTPS gateways!

Static Websites

The following need to be updated on your Static site (which should also apply to the vast majority of server-side rendered websites):

  • All links and references, moving HTTP-> HTTPS
  • All images, external content coming from CDN(s) need to be updated to use HTTPS
  • All JavaScript libraries and files need to be referenced using HTTPS too!

From there, you should be good to go! I tested the above using my latest little project ‘The Developer’s Playground’ which can be found here: https://the-developers-playground.ca!

WordPress

Woah, blogception!

For WordPress, I found the Really Simple SSL (https://wordpress.org/plugins/really-simple-ssl/) plugin mitigated many of the common issues that would arise from a previously HTTP configured installation. It will correct image references, link references, and common semantics which makes browsers such as Firefox or Chrome complain about the site’s integrity. It really is, Really Simple SSL!

If you are using Google Analytics, you’ll have to update the domain’s via unlinking and reconnecting (depending on how you’ve connected the platforms), or by configuring via settings within the console.

The website I used for testing and confirmation of this process is the same one you are probably reading this on, which is raygervais.ca! Notice that lovely lock in the URL?

Conclusion

This post I don’t find to be the best in structure or information, but it does provide one item which I was looking for when trying to understand and implement SSL on my GoDaddy based sites; how to do it. Finding ZeroSSL wasn’t as easy as I would expect, and included searching through various forums and tickets, with no direct link or resource pointing to it from the search itself. Hence, I wrote said post.

Once you go through the process twice, you’ll see just how easy it is to setup Let’s Encrypt on your domain, and have a valid secure site!

Sources & Reference

From a Developer’s Perspective

“NodeJS and Windows don’t work well.”
“I Need to run with Root Permissions to globally install vue on my MacBook Pro!”
“NodeJS broke my Linux Servers FS Permissions.”
“NodeJS can’t be found in my PATH!”

I’m sure you could list ten more items before finishing the next paragraph, but it’s clear to see that when discussing NodeJS, you cannot couple such powerful feature sets without the risk of also introducing issues with your own system or as I like to call it, ‘file-clog’ from the thousands of globally installed modules you make available to each project.

I found myself frustrated with this constant battle, be-it on ANY system that I was using. Eventually, they all became too cluttered and unlike a USB key which you could pull away and forget about, it was hard to clear out the jank without exposing your rm -rf habits to critical file systems. This is where I came up with the convoluted but totally awesome idea: Can I run NodeJS projects through Docker, and discard the container when I am done?

Turns out the answer is yes!

Aside from the above, why would anyone really look into this approach? Well, let me provide a few examples:

  • Your AngularCLI install is out of date, and any attempts to update also messes with your TypeScript version installed in the project or on your system.
  • Your testing framework creates files which aren’t cleaned up after, which results in artifacts on your system which are out of date by the next run.
  • You don’t want to muddy up your PATH with dozens of modules or leave it as stock as possible.
  • You want to leverage similar workflows on multiple computers using a single setup script/configuration.

The two workflows differ due to end-goal, I’ve included NodeJS’ fantastic workflow for ‘dockerizing‘ your application for production and orchestration, alongside my own development workflow. Whereas NodeJS’ simply need minor refinement (such as using multistage Docker builds to reduce final container size -stay tuned for my exploration and updates to that in the tutorial repo outlined below!), my workflow is still a work in progress.

My end goal of reducing .node_modules found on my computer is still not 100%, but it removes the need for global CLI’s and tooling to be existent on my file system, alongside Node itself. I imagine at this point into the post, you’re wondering why would I bother trying to complicate or remove the NodeJS dependencies in my workflow; to which I simply say: why not? In my mind, even if the workflow gets deprecated or shelved entirely, I’m glad that I got the chance to try it out and evaluate the value it could provide.

Dockerfile – My Workflow Tutorial – Development

My workflow leverages Linux symlinking with your application folder purely for the ability to edit your project in the IDE or text editor of choice, instead of in the container. This, coupled with many CLI’s having auto-build enabled by default creates a powerful and automated development engine. Scripted portions allow for simplistic automation of the redundancies such as mounting the code directory to /app, and all that is left is for you to run in the container (which the script lands you in):

Leveraging the Seneca Application in the Offical-Node-JS-Way Folder

One critical item which you need to do is enable in the Docker settings the shared volume location for your work/development directory. Without this, the script will fail to copy a symlink version of your project. On Windows 10, this is still an uphill battle where permissions and file system securities make this a not-as-smooth process. See the following link for an explanation why the bash script determines your OS and changes location prefix:

Running run.sh puts us directly into the container with our code in /app

The beauty of this method, in my opinion, is that it allows for consistent environments (such as what Docker is intended for) both for development and testing, with the absolute minimum of clean up or exposure to your filesystem. Because of the system link to your project folder, files modified in your editor or in the container reflect the other. This leads to node_modules also being a residual artifact that my next version of this workflow aims to remove from the equation. Once you’ve shut down the container -and thus, removed the link to your project(s), a container-cleanup is as simple as:

Or to kill all running containers

Then to finally remove the image

Or to remove the image(s)

Development Server working via Port 8080, utilizing a Node module such as Nodemon would cause rebuild and refresh (client-side) per code change. Damn useful!

And boom, you are now back to a clean filesystem with your project safely and cleanly in its own place, the only remainder being the .node_modules folder in the project itself which you can delete manually.

Dockerfile – NodeJS Tutorial – Production Build

The official way that NodeJS recommends using Docker is for containerizing your final application, which I highly recommend once you get to said stable state. It’s fantastic for having all your final dependencies and compiled source code running in a container that can be handed off to the cloud for orchestration and management.

Running build.sh to pull Docker image

I used this method quite often when deploying MEAN-based microservices at SOTI, and also for my own projects which are then orchestrated with Docker Swarm, or Kubernetes.

Configuration and listing of Docker images

The benefits with this workflow include being able to utilize Docker’s multi-stage build process so that the node_modules prior to being bundled in the application exists in a staging container which is never included in your final image, and instead, only the final output is bundled.

Local test of final application container

Taking their tutorial, I wrote two scripts titled build.sh and run.sh (pictured above), which automate some more of the process. Taking an old, lightweight application written for OSD600 and leveraging Express as a dependency, you can see how powerful this option for bundling and containerization is!

Closing Thoughts on V1

Well, I hope you get the chance to utilize this workflow and improve upon it. I’m looking forward to seeing what you can do with this little experiment of mine, and also how it may better maintain the health of your host operating system while exploring the hundreds of JavaScript frameworks and libraries which are created daily!

I decided to label this Version1, implying that when I have the chance to revisit the process I’ll update and improve it. In that vein, I also did some thinking and decided to compare or share some thoughts on both processes:

  • Following the NodeJS way is far too costly since it would recreate the container each time, the current workflow at least keeps all global cli’s to the container itself, and Node itself is contained as well to the image.
  • Likewise, following the NodeJS direction would remove some of the modularity I was aiming to keep, so that it could be used on one, three, ten projects all the same.
  • I had Toto’s Africa on repeat for a good hour or so while drafting this, apologies if you can notice any rhythmic mimicry to the first verse at points in the writing.
  • Updates to this will come, but for now I am content with the current workflow despite shortcomings and complexity.
  • Docker’s documentation is by far one of the best pieces of technical writing I’ve ever been exposed to. It’s that good.

Tell me, what is your Docker workflow? How do you use Docker outside of the norm?

Tutorial Repository

References & Research:

https://nodejs.org/en/docs/guides/nodejs-docker-webapp/
https://github.com/raygervais/OSD6002017

Troubleshooting:

http://support.divio.com/local-development/docker/how-to-use-a-directory-outside-cusers-with-docker-toolbox-on-windowsdocker-for-windows

An OSD700 Contribution Update

So here we are, potentially the last contribution to occur for OSD700 from this developer before the semester ends and marks are finalized. No pressure.

For this round, I wanted to tackle a feature request which I thought would be beneficial for those who utilize the date picker component (a common UI element). The concept is to dynamically remove and add years to the overall date picker based on the min and max date configurations. Sounds rather simple, right? I thought so, but I also had to admit my lack of experience working with the code which dynamically generated the calendar and years portion to this degree before. The inner workings are vastly complex and data driven, which in itself is an interesting design.

The process so far while working on this has been an off and on “hey I get this”, and “I have no idea what to do with the current concepts”. You can see throughout my work in progress the various off and on’s when it comes to understanding, implementing and asking for advice / suggestions which gets us to where we are now. Currently, as I’m writing this, with the help of mmalerba and WizardPC, I have the dynamic year portion working as desired; some artifacts needed to be addressed such as the displayed year range in the header needed to be updated, the years-per-page seem to overlap on the final year if over 24 years gap between min and max, and a potential ‘today’ variable which isn’t always the current date.

There have been many revisions to the code base that I’ve been playing in, often rearranging logic and algorithms to accommodate the four edge cases which are:
1. With no Min / Max provided: the Multi-Year Date Picker behaves as current implementation
2. Only min date provided: Year offset is set to 0, making the min-year the first entry
3. Only max date provided: Year offset is set to a calculated index which equates to max-year being the last entry
4. Both min and max provided: Follows same logic as case 3.

The process of making the first edge and second edge case were relatively painless, this in part also due to the advice and comments left prior to me even writing my first line for this feature set. I’ve included below this that revision and various revisions I had attempted (skipping over the minor changesets) until I finally had the working version a few days later. You can see the progress in my WIP pull request here.

Revision #1 (Min Date Working as Expected)

After I clarified that this was indeed what we wanted for the second use case (min provided), now came the harder algorithmic portion for use case 3 and 4. What I’m working around looks like the following:

Revision #2 (A lot closer to expected logic)

The snippet below was the logic which should be followed, at first I thought nothing of it, but I realized that (yearOffset – Math.floor(yearOffset) would 100% return 0.

Revision #3 (Snippet)

Final Working (Pre Syntax Cleanup)

Words cannot describe the waves of frustrated “this will never work” monologues and “this is progress” relived exhales occurred during the past week while working on this feature, nor can words describe the amount of dancing-while-no-one-is-around that I did when I finally reached the current implementation. Based on the use cases mentioned above, here is a visual for each:

Case 1: No Min / Max Date Provided

Case 1: Min Date Provided

Case 1: Max Date Provided

Case 1: Both Min / Max Date Provided

I simply cannot explain the thought process which came to the final conclusion, more so I am able to explain the biggest flaw I had in my own thinking. I over thought quite a bit, and more so became overwhelmed with the thought that I would not complete this or the code base was too complex (I will, it’s not). I suppose the time of day I typically worked on this bug didn’t cater well to the mentality while approaching the code, nor my mindset of ‘one more item due’. Once I took the weekend to correct that, and to slowly relearn the task required and the changes (instead of breaking the scope into much bigger unmanageable portions in attempt to ‘get it done’), thoughts and attempts became much clearer.

Whats left? Well, at the time of writing this post I still have to fix the headers, isolate, identify and fix any edge cases which the algorithm doesn’t take into account, and also clean up the code of any useless commented out code. I believe that it can be done, and after the progress today I can happily say that I’m more optimistic than I was on Friday to complete this feature request. I’ve loved contributing, learning what I can through toil and success and also feeling the “I can accomplish” anything high when the pieces finally click. Once I settle down in my new role, I hope to keep contributing both to Angular Material, and new projects which span different disiplines and interests.

A OSD700 Contribution Post

For the final release, one of the issues I wanted to focus on was this, which I figured would be an easy contribution toward the project and a check off of my final release requirements. After reviewing the comments on the issue, I was under the impression that I had to learn a new accessibly standard titled aXe. aXe was going to be the driving force behind this post, but to my fortune it’s more of a testing engine than a standard; testing instead web applications and pages against the WCAG 2.0 AA rulesets.

Evaluating the issues with a page relating to WCAG AA compliance is made easy with the aXe engine: https://axe-core.org/, and even displays in the results how to better improve or fix rulesets such as contrast and sizing. So, I was on familiar ground. A ground which many never bother to consider since they avoid the cracks and spots of mud as they walk along. I decided to use the engine’s results as a guide towards patching the cracks, cleaning up the mud. One has to wonder, what is the consequence of such patches?

I first looked into the Material Design stepper specification and accessibly pages, where items such as contrast and sizing were addressed in a stark-yet-not-half-assed manner. The rules made sense, but they still did not comply with WCAG AA requirements and better yet, disregarded many of the colour rules to forward a flat aesthetic. The website the documentation is running on fails multiple guidelines, meaning that this correction would come from ideas, discussion, and if accepted, deviation from the very guideline which established the design of the project. Damn.

Before

After

I left a comment which described the most transparent way of fixing the A11y issues with the stepper, opting to darken the text to meet the bare minimum of the compliance guidelines. It was as I was typing the comment and proposed changes, that I realized just how little people would care for such a change, or how quickly I’d be thrown off the boat for attempting to go against the design specification.

The change that I proposed is very small, bringing up the alpha layer of the RGBA font / background colours from 35% to 54%, which brings us to the compliant 4.5:1 contrast ratio. I figured this was better than changing the colours themselves which, good luck doing so since we are playing with #FFF and #000 through and through. Kids, this isn’t your Dad’s CSS.

In the past few weeks, I’ve been horrendous when it came to OSD700’s work, often appearing dark f or a week in span, my work for the course at a standstill in that time. Three days after posting the comment which I hoped would stir discussion, still not a single response. Perhaps I need to give them a week as well, moving onto a different issue as my secondary while waiting for the pitchforks or textbooks to fly in with fury once maintainers and developers alike stumble on it.

Regardless, one can only throw his paper plane into the sky and wait for the wind to determine it’s direction.

It’s hard to believe how quickly this semester has come to a close. Some of us including me even had countdown calendars, and yet the days escaped even quicker than we could count. It feels like just last week I started my second dedicated foray into Open Source technologies, and yet in the next two weeks it’ll be the end of such adventure (for now, that is). Similar to what I did when I completed OSD600, I thought I’d recap and share my thoughts as I complete OSD700, and perhaps also allude to the progression and experiences between the two which is only possible through fantastic instructors such as David.

From 600 to 700

The Rise of JavaScript

In David’s OSD600, I learned quite a bit about modern-day JavaScript practices and how they applied to current Open Source trends. Looking back now, I gather a few reasons why JavaScript completely swept over and took the FOSS realm by storm:

  • Thanks to Electron and HTML, making cross platform desktop applications is now as simple as writing a web application. I believe this is imperative in the popularity of JavaScript applications since working with GTK, qt, WPF, and Cocoa (just to name a few) can be disjointed and utterly mind jarring at times. If you know HTML and CSS, your application can share unified styling and components on all major platforms.
  • JavaScript has grown in the past decade to be one of the most flexible languages I’ve ever seen. Learning advanced JavaScript development means learning new patterns, new paradigms, new programming concepts such as callback / closure centric logic wrappers, and with the addition of Node for the backend, a semi-robust alternative to the languages of yesterday.
  • I’ve observed a radical shift both from SOTI and from developers I’ve talked to regarding their change of perspective between dynamically typed, interpreted languages such as Python, JavaScript and compiled languages such as C#, C++, and Java. Many whom admitted disdain for JavaScript were now advocating its usefulness for prototyping and rapid application development without the need to compile or grand environments being provisioned. Of course, you have individuals in both camps, some who claim that NODE and JavaScript are still too immature to be taken so seriously in enterprise, of which I do see some their points being incredibly realistic. Tried True > Bleeding Edge.

From Student to Intern

Likewise, it was through learning JavaScript in OSD600 that I had the confidence to learn Angular and it’s primary language, TypeScript. From there, the entire MEAN (MongoDB, Express, Angular, Node) JavaScript centric stack and all of it’s toil and glory. Flash forward three months later, and this new experience actually landed me into my first enterprise Internship with SOTI Inc, where I was a front end Angular developer. Using David’s knowledge and lessons, I learned quickly how to excel and push forward the tasks much bigger, much more complex than my potential, and became the lead front-end developer (still an intern!) of the SOTI Insight team.

I don’t think a single day goes by where OSD600 hasn’t had an impact on my current work in the best way. Looking back now, without that class I can say that I would not be in the position I came to, nor would I have the experience and drive which came from that class.

The Transitioning to 700, Thoughts Post-600

The same can be said for many who took David’s OSD600, and for those who in OSD700 are also finding their callings. With 700, instead of being shown around the nest and how various communities work we were thrown directly into the sky, told to choose a place to land and from there build our own nests alongside the given communities we chose. Here, some chose Visual Studio Code, Brave, Chart.JS, Angular.Material, ngx-bootstrap, Python even!

The experiences differ per person, but I don’t *think* any of us walked out with less than when we walked in. Instead, we walk into the last few classes with contributions and pull requests to our name, a steady stream of work relating to us showing up on most search engines at the very top (talk about good publicity for a developer!), and a confidence and skill set which isn’t easily obtained that will push our careers further than ever before.

Lessons and Thoughts Which Stood Out This Semester

Debugging through Different Directions

I’ve written about some of the debugging methods I’ve painstakingly learned over the past four years, a post which was directly inspired by David’s lessons and articles on the topic. Being the ever-learning, humbly experienced developer that he is, David shared with us his strategies for debugging applications built on top of the Electron framework; a lesson which the very next day even affected the nature of my tasks at SOTI in the best possible way.

Whereas I discussed in my post a lot of the common debugging issues and or missed areas which younger students that I tutored or myself often struggle with, David went straight into explaining how to bend Chrome and modern technologies to our will. He explained Dogfooding, Dependency Injection concepts, and navigating your way around a huge code base looking for a single event listener using modern day tools. Never before had I looked at the Chrome DevTools specifically with such admiration of what was possible through a web browser. It’s amazing how much effort and work is put into such tools and applications that the everyday person will never think about nor discover.

I took some of the tricks that David had displayed and applied it next day while debugging an item at SOTI. To my disbelief, no one else on the development team (which at that time was comprised of 4 senior JavaScript developers, 6 software developers) had heard of the debugging-on-DOM-Node-event trick, or even conditional breakpoints accessible through Chrome’s DevTools. Yet, it was exactly these two tricks (plus a few others) which finally allowed me to discover the flaw in the code; the line which broke the business logic.

Becoming a Small Community in The Class

Throughout most of our courses, we’re always anticipating to make friends in the classes we frequent and build relationships or networking potential with our peers. This means that when we see each other in the halls while rushing towards the next test, we’ll nod, see how it’s going, strike a conversation, or perhaps press forward since the Prof isn’t going to wait for you. I found this scenario through my few years at Seneca to be very predictable, to be the standard of meeting individuals who are in the same field as you.

In OSD600, and even more so in 700, I found David guided us towards something much bigger and more concrete. As per his intention, the class of OSD700 became a community where thoughts, stories, events and coding struggles were shared and enjoyed. Interesting developments or thoughts were shared on the Slack channel weekly, often by Sean who somehow managed to always have a new link or article to share! We attended a Rangle.IO event as a portion of the class, and even got to tour the Mozilla Toronto Office (MoTO) with Michael Hoye. The twitter tag #SenecaSocksCrew was created initially as a chance to get awesome looking VueJS socks, but later kept alive to become a symbol. An anchor for all of us to come back and relate to, to keep in touch and also to plan out new events together after the semester ends.

David got what he wanted, which was to join a class of extraordinary people into our own open source community. The community at the moment consists of the following incredible developers, who I’d recommend looking into for both their work, their blogs, and their continued plans to change the world:

Presenting your Best and Worst Work


This is an interesting one, because as the title suggests some days aren’t meant for presenting the goldmine of work you produced. Instead, we were encouraged to present any and all of it. What this meant was explaining our thinking, our trials and where we want to go next with the task at hand.

This was one topic which took me away from the comforts of a polished end result. Never before have I had to talk about failures, and work in progress to such degree, admitting that at the time of your presentation that there is still work to do, things to fix, and a long road ahead. It took a lot of time for me to adjust, to admit alongside my pampered and finished tasks that some were the polar opposite, coal in a cave full of unknown code waiting to break or be found. It was incredibly stress-inducing to me to go up in front of my peers, and explain why an item isn’t working, similar to a progress report. I’ve always been a perfectionist, so the introduction of this style of presenting was one which pulled me very left field, but also gave me the slowly-worked-to chance to learn from the presentation style and own up to the tasks in their unfinished entirety.

Contributing To the Everyday Persons Workflow

This title seems odd, even for me who wrote it. What I really mean by this, is that our contributions should be aimed at making the biggest splash it can for others. This doesn’t mean sending thousands of lines of code changes in a single Pull Request, instead it means making the project one bug less, one language translated more, one requested feature added, etc. David really tried to emphasize this as many of us looked at lines of code as the metric between an ‘A’ and ‘B’ graded release, instead of how this ‘very small’ change would improve the workflow of developers all over the world using said project, or how this bug fix will help clients and developers alike to push the project forward by removing technical debt for example.

It took awhile for me to learn this, since previous courses and egos always considered the better programmer to be the one who writes quality code, in bountiful amounts. My first few fixes were mere line changes, which though they qualified as a ‘release’, to me they felt like the shortest fragment of a ‘patch’. Over time, this changed as David stressed how these fixes were improving the lives of both the users and developers, beit bug fixes, new features, or even accessibility improvements (my niche I suppose). I saw that contributing didn’t have to be verbose, but instead helpful.

Where Do I Want To Go From Here

This isn’t my last blog post, nor is it my last blog post relating to OSD700. But, I figured this would be a nice place to put my ambitions and thoughts towards how I want to steer 2018. Not in any order of priority or execution:

– Learn VueJS / React
– Learn Python 3, Rust, GoLang
– Write a Full Stack Web Application from the Ground Up
– Write a Mobile Application from the Ground Up (iOS? Android?)
– Become a Mozillian!
– Become a Node Certified Developer
– Become a Linux Certified Administrator (maybe?!)
– Continue contributing to FOSS communities
– Continue working on Musical Adventures, release some of it!
– Continue being a member of the SenecaSocksCrew community

Going forward, I’m hoping to learn more lessons and also expose myself to newer technologies which contrast or conflict with my own current experiences and vices, my logic being that it will round me out as a programmer better than falling into a specific niche. I imagine my new career title will play well with this concept, going from Front-end Developer to Cloud Platform Engineer. 2018 is only a quarter of the way through, and there is still much that is possible before we see the end.

Or, How to Break Every Travis Build Your Commit Creates!

An OSD700 Contribution Update Part 2

Preface

This week, having thought I had climbed and conquered the smallest imaginable version of Everest, I climbed into my favorite chair, put on headphones, and let hours pass by while finishing Haunted Empire. My phone went off during this time, but unless it was a call or message, I thought nothing of it. I finished the book, pleased with the epilogue and wondering if had it been updated with the current exploits and affairs of Apple, would the ending remarks differ.

Mountains of Coding Guideline

Upon returning to the world, I was greeted with the results of my climb of Everest; a new mountain of style corrections and lint errors to be corrected. I thought I caught the majority in my previous climb? Why did my IDE (Visual Studio Code at the time) not catch the issues? Was this the first opportunity which would impact the impressions the maintainers of Angular Material have on me? On my contributions? I had to first discover why these slipped past my editor.

ESLint vs TSLint

Before going into the issues which I had to correct, I wondered why the codebase didn’t display the wonderful red lines (depending on your theme) which similar to writing your thesis, implies a mistyped item. In my case, the red lines would have displayed most of the issues listed below, but I never knew we were playing hide and seek during this playful hour. See, the reason for this game I found after a few minutes of experimenting and digging, was that my installed ESLint plugin did not bother with TypeScript files, and likewise for some reason my local instance didn’t have the TSLint plugin installed at the time. That second point really drove the entire issue, since installing the plugin instantly brought back my favorite frenemies and revealed any issues relating to my TypeScript files.

The lines returned, pointing out the flaws in the components I had worked on relating to the preconfigured rules for Angular Material, and that is also how I learned about their code style more so than the previous contribution. Below I’ve outlined some of the items which are easier to gloss over, and my thoughts as well.

Spaces vs Tabs, and Spacing Count

Angular Material indentation requirements is 2 spaces per indentation. Despite every source file containing this indentation style, Visual Studio Code still used 4 spaces as the defacto standard while the project was open.

Perhaps I am supposed to configure this beforehand, but the fix itself was as simple as toggle the indent settings at the bottom, CTRL + P / CMD + P, and using the reindent lines command to correct. Without getting into the whole space vs tabs argument, always ensure that your editor / IDE is configured to comply with the coding style of the project, regardless of what that specific compliance is. I’d love to push for a indentation standard which can be applied in ESLint / TSLint which editors such as Atom or VSCode can then extend into their linters. Maybe a summer project idea?

Formatting, Trailing vs Leading

We all pick up habits from people, projects, and our idols in ways both which we are aware of, and unaware of. I didn’t realize how much I favored leading commas until David pointed it out while I was working on the Thimble Editor a year ago. This habit came from my previous COOP with Technicalities, where experience there dictated that leading commas were a good design choice to be following in every project. I must have picked up and endorsed this coding practice for the vast majority of 2016 to 2017.

Using Thoughtful Examples

So this one is more of an opinion compared to style guide, but I do believe in the point which was conveyed and the requested change. Essentially, while working on https://github.com/angular/material2/pull/10666, I used the same example content as the StackBlitz, meaning I had the following data to work with:

At first, I thought that this was appropriate since if you typed D, then Dog and Dragon would be displayed while the C option group disappeared, implying what was expected workflow wise. Expanding from there, if the user typed Dr, Dog would follow C and disappear since it no longer complied with the conditional statement. It was a to-the-point example which I thought carried the concept across in this StackBlitz fork I had done.

Kristiyan, one of the maintainers of Angular Material, requested that instead of using this dataset, I use the United States (or a bigger data set), so that the users and document readers could play with the example and see more results being filtered down, brought back, or removed from the criteria entirely. It made sense, why demo a filterable list with only four elements when you could with fifty elements instead? I forked my original StackBlitz and then updated the data list to the new topic. I learned few items from this task which I’ve listed below, and if you want to see the final StackBlitz, you can find it here.

  • The USA has 50 states (yay geography teachings!)
  • Compared to Letters D, F, G, H, L, P, R, and U which have a single state, M and N have a damn huge number of states. An unbalanced amount if I may say so. 16 damn states between the two, which is double the amount per letter of the other set.
  • I really don’t know my geography (Jack can attest to this, who enjoys pointing out this flaw when ever we somehow brought up travel).
  • This is a much better example, both in content and concept. Filtering through states seems like such a common use case for some compared to sorting through 4 separate animals. It’s tangible, relatable.

Integrating Prettier Into More Workflows

I heard of the Prettier formatter a few months ago while working on a school project, and never really thought of how valuable it would be until after this small bit of debacle. It made me think, how much time is wasted on formatting per commit and how we spend N amount of time trying to correct it. Why not let the machine format or warn of bad formatting prior to the git commit so that everything which goes through the wire is already in the best state. I wonder this not for just Angular Material, but ALL established projects which has hundreds of contributors or more. The current offerings by such a formatter is impressive, but I was equally impressed with the upcoming support for Python, Swift, and Java. Likewise, all of the major editors are already supported (Atom, Emacs, Sublime Text, Vim, Visual Studio, VS Code, IntelliJ Platform).

Next?

Currently, both of the issues I intended to tackle for this release have pull requests by yours truly, and both pull requests have some E2E issues which I’m addressing in between writing this article. You can follow both issues here:

I really wanted to snag a third small item into the list, but time was not on my side for the past two weeks with other items and priorities had to be addressed firstly. At this rate, my current plan of attack for the final release (damn time is moving quick) is to pick similar sized issues which can be done in a few hours, and see how many are possible with valid fixes, good code, and not breaking every possible end to end test I can imagine.

An OSD700 Contribution Update Part 1

In this day and age, you live in one of two camps, you either love or hate autocomplete. Autocomplete (which differs from autocorrect due to contextual opposites of operation) is the answer to the mundane long dropdown lists, providing a means to both filter and evaluate a value without scrolling through the entire component (and then some!). For my second foray into Angular Material, I decided I wanted to go further with the documentation while also browsing for enhancements or usability fixes. This led me to the an issue request for documentation explaining how to incorporate option groups, which revolves around a far more complex observable pattern and design pattern (yay!), I’m guessing.

Humphrey mentioned while presenting previous documentation work that these forms of contributions also fall under my intended focus on accessibility, which I’m glad he said because it resolves my concern I had with accessibility not being related to usability. I agreed wholeheartedly. My goal since getting into programming was always to make technology as accessible and usable to the largest populous as possible, and I’m proud that I’ve been creating a path which does exactly that in small ripple-like motions. I believe that, if the technology is inaccessible to developers who devote 90% of their day to such, then how can we possible push forward without tricks which will bite us tomorrow?

I digress. Back to the task at hand.

Getting Started

Compared to the stepper component from my previous work, this autocomplete was a whole new component and workflow that I had to learn. I first started with the provided StackBlitz example from the issue itself, just to understand the underlying semantic patterns and components which make up the overall functionality. Link for those following along here.

In the StackBlitz example, we see the following hierarchy of components below. I’ve include in my explanation of each component some literal HTML code examples taken straight from material.angular.io, my argument being that they’d help to understand the semantic levels of each component and how one acts as an container to the other.

Components

Material Input

Documentation
The mat-input is a custom directive which allows for standard html input and textarea elements to work with the material form field container. The easiest way to think of this directive is to describe it as a upgrade to the original input element. Let’s go from 1.0, to 2.0 which includes form validation, error message styling, and responsive modern design. This is the component that we’d input our text into (duh), and also manipulate the autocomplete / filter.

Material Autocomplete

Documentation
Extending the material input even further, the autocomplete component provides a list component which can be filtered. This component acts as the container and main driving functionality when extended with coupling mat-option components for each list item.

Material Option Group

Documentation
Older
This component acts as a container for an array of mat-option components, allowing one to group multiple under a single heading / text.

Material Option & Material Select

Documentation
The list component used by mat-autocomplete, these act as the list item 2.0 of the HTML semantic world. Used in both the mat-autocomplete and mat-select components as display items, the material option is a very powerful component.

Updating the StackBlitz Example

When I first discovered the bug and the corresponding StackBlitz example, I thought that the component itself was broken and that I had a lot more work than what the issue had described. I was relieved while looking into the code (for the above analysis) to see this code snippet which implied that completion would show true progress and remaining work.

I corrected the issue using common sense with option groups, meaning my logic (which is below and in the link) focuses on filtering the option groups themselves, instead of the individual options (following what the issuer’s logic described). I love functional programming, and even small traces such as these makes me so happy to come up with since I think they are where many languages are heading; utilizing powerful paradigms sans the verbose 100+ lines of code to achieve such.

Thoughts on the Current Documentation and Next Steps

In a word, complete. Realistically, the work that’s required of me is minimal, simply expanding the code snippet to a full blown example which is tangible to others. After confirming that the logic is all there, and the autocomplete works as expected, this is another case of directing the readers and users towards a proper implementation so that they can push it further in their own code. Compared to the stepper, this component’s API and documented attributes is very thorough and explained using multiple examples. Working with such makes it even easier since I have a good foundation to base my work off of.

Next steps is putting the work into a pull request, verifying the expected behavior of the component. Stay tuned for a follow up coming soon!

An OSD Contribution Update – Part 1

Tutorial Header

Getting Onboard

Documentation is a topic that often splits developers into two or more camps, those who write and those who don’t; an irony since both camps rely heavily on documentation with external libraries to utilize and understand it’s respective API. So, when is documentation considered ‘good’? When does the documentation fulfill the needs of the developers, and convey the key functionality without proposing self discovery of unknown APIs? This is what I wanted to explore while contributing to Angular Material (https://material.angular.io/), https://github.com/angular/material2. I found a great issue which was requesting for more documentation for their material stepper, https://github.com/angular/material2/issues/10381 and I thought it would be a great introduction to their community while providing a changeset which benefits more than just developers or current users of Material. Updating documentation helps everyone, and in a few examples from my task I’ll explain my thoughts on why I think so.

Current State of Stepper Documentation

As the issue suggested, the documented examples for the stepper component was lacklustre… sparse even. The API was listed in beautiful English, but no interactive examples were present which displayed the various states, attributes and data-flow which the component offered. The recommendation by mmalerba was to provide better examples between various state flags, icon matching, and expansion of the original example.

Current State of Stepper Example

One item that I had noticed was the button to ‘toggle linear’ mode for the stepper never actually toggled the state, but instead set the state to true (meaning linear is enabled) and nothing else. No toggling (enabling / disabling of linear state), just moving to a single state. This was the first item I wanted to address since as a user, I’d want 1) visual feedback and 2) the option to toggle and switch between states in the example. All the foundation was already there for such an update, and it became my first commit into what would be the Angular Material project.

Creating Examples for Edit and Optional Steps

For the documentation, I saw that there were no tangible examples of the edit and optional attribute Inputs of the Material Stepper, a need which needed to be met. This is where my Pull Request started, with implied intent that I’d add more if mmalerba or I found more appropriate examples which could be utilized for the stepper component to display even deeper functionality.

I can say that reading the documentation gave me a thorough understanding of the components API, and that creating the examples which will be used to explain said API was also a easy task, but that is because I’ve worked with Angular and UI Frameworks such as Material for almost a year now non-stop. To the beginner, to the one who’s experimenting with Angular Material for the first time, this documentation and API is daunting. Despite the well written content, proper examples help to truly establish a thorough understanding of the framework in my opinion.

For either example, the process was the exact same. Copy the foundation (Stepper Overview Example), and modify the attributes, title, and toggle logic to accommodate the specific example itself on one of the steps. This way, the examples mirror each other instead of presenting the reader with different context every time. The changes are borderline single line changes, but abstracted away to their own components for clarity:

Meeting Contribution Guidelines’ Compliance

This is the first project I have worked on Open Source wise which has a predefined commit message structure (which I totally love!) to make the development process both more uniform and accessible to those doing the review. It took a few commits to truly embed into my habits the proper structure, which looks like this (taken straight from CONTRIBUTING.md):

The documentation did not provide any Pull Request related specifications, so I did my norm and hoped for the best -making it clear that it’s possible I overlooked, disregarded, or even added too much to a specific area. Really, I gave them the putty and asked for hands to show me how to mold it to their liking.

Mold it they did, leaving comments on the code review which suggested a better practice, more uniform styling or removal of unnecessary code blocks. More on that can be found here. All of the first round of code review were stylistic changes, which I was happy to fix since it also showed a gap in my understanding of their accepted coding guidelines.

Thoughts so Far

Spinning wheel of Light

This is the first contribution I’ve worked on which primarily dwelled on documentation, my niche being more of that relating to accessibility or editor features. I like to think this is equally, if not even more, monumental because it makes the code base itself and the components which are offered to developers more accessible; enabling their work with far less friction so they can further push the technologies farther. Mmalerba has been incredibly helpful so far, and also very accommodative to a new contributor who does not know his way around the code base or expectations when testing and documenting their changes.

Furthermore, it’s awesome to pick up a technology that I feel proficient with for a change, instead of having to learn (which is great, don’t get me wrong) a new one including all the bells, whistles, errors, and painful realizations that you should have started weeks before. I’m confident that I still have hundreds if not thousands of hours to learn on Angular alone, but I also see it as a tool which I can already start giving back to in any way possible.


This is a follow up to my previous post, describing some examples and public issues which touch upon heading semantics and color contrast.

Four Individuals infront of Glacier

Headings

Admitting to Your Mistakes

South Wind Motel

As you would have guessed, even I found the issues discussed above in past work from two websites which I used to claim where the best I was capable of at that time. Even more so, now that I know of these issues (which I discovered while looking for examples), the urge to fix and improve upon is there. In the South Wind Motel Website, I improperly used a H1 for the hero component, which would be fine had I made that hero display ‘Accommodations’ instead of a tagline. This is how the page reads to screen interpreters right now (without worrying in this example of divisional area tag sementatics):

South Wind Motel Heading Fail
South Wind Motel Heading Mistake

This may look like a minor issue, but the pattern repeats on each page with different taglines, some often not granting proper title-like context such as Property or Trail, which become increasingly more vague. Still, you have to start somewhere I suppose.

Silver Maple Motel

A website done a year after South Wind’s was finished (which was a weekend project during Christmas break in my defence), Silver Maple corrected many of the layout and ‘aesthetic’ issues I had with South Wind’s. In doing so, I created a different pattern of heading misuse. Here are the obvious ones that a simple inspect element unveils:

  • I used H1s due to their styling and size as icons. Meaning every standard icon on the page is a H1, without text or proper hierarchy in the slightest.
  • The proper titles use H5, unsure why I went so low down the spectrum, but we jump from an icon of H1 to H5 titles
  • The parallax images and their respective titles are H3s, which really should be H1s since they define the separation of page contents and topics. Likewise there is inconsistent blurring in attempt to mitigate contrast issues which I’ll discuss in a later article.

Two Examples of Similar Common Mistakes in the Wild

AndroidPolice

I love this website, it has been my goto source of news for all things Android since 2011, and I have to this day always held high regard for the content and it’s writers who publish there. While inspecting the site, I only saw one major offence (in my opinion, I could be forgetting a rule since there are so many) when it came to header use. The navigation bar uses a H1 for the AndroidPolice logo, and the article titles start at H2. This means that ever page is interpreted this way:

Android Police Headings Mistake
Android Police Headings Mistake

This may be a very minor issue, perhaps not an issue at all (depending on the ruleset, I am in no mood to read through the documentation this year just to confirm the smallest, most minute of a detail with a overall non-offending site), but I found it interested in how headings were used to imply hierarchy directly from the site’s title.

PC World

Simply put from a quick inspection of an article (I imagine said patterns are throughout, since all CMS use templates to remove the grunt work): H1 for title (great!), H3 for subtitle / annotation…. not so great. Realistically, the guidelines do not imply a need for subtitles to have a heading, and I imagine this was used to leverage the H3s styling. Kudos for following expected heading semantics otherwise, every other title falls under the H2 use, making the page be interpreted in the following way:

PC World Headings Mistake
PC World Headings Mistake

Color Contrast

I decided to take a stroll through Modern Flat Web designs, and see if I could find any practice which was an instant red flag. I’m using https://speckyboy.com/flat-web-design/ which currates 50 ‘Perfect’ examples of modern web design, a perfect list to try and pick a few apart. Will I succeed? Read on!

Design Interactions without Code

Website Interactions Without Code Color Contrast Mistake
Website Interactions Without Code Color Contrast Mistake

Damn that’s a bright hero component, it’s eye catching and yet blinding at the same time. The hero’s text is very readable, until you notice the cursive text which I almost missed the first time glancing through. It’s the same #FFFFFF as the bigger text, so how did I glance it over so quickly? How did it not catch my gaze? Well because the contrast ratio of that specific background color (#3EC7C2) and the text (#FFFFFF 29px font size) is 2.07:1, which fails both WCAG AA, and WCAG AAA demands. For large text, the ratio must be 3:1 or greater, which this one still does not comply with. Not off to a great start from the first page alone, and the contrast compliance didn’t improve throughout the page either for most of the colorful elements. Sad, and we just began.

CraftsmanAvenue

Funnily enough, the design and overall approach here is much more subtle and well established. I decided to test the mission statement found at the top, which has a text color of #887771 and a background page color of #FAF7F6, together they form a contrast ratio of 4.00:1, so close. Many of the elements are basic hues off from WCAG AA Color Contrast compliance, so I moved on, feeling hopeful.

Stash Flat Icons

Blinding Image
….

Presenting, modern aesthetic. Colors so close together in the spectrum that you don’t need to test using a color ratio tool to identify compliance. I can barely read the list items, I dare you to without squinting. It was at this point that I decided we had a good assortment of color related examples which all could learn from.

Learning from These Items

While doing writing this follow-up, I found two really helpful links for headings and HTML semantics which I’ve posted below. I think that if every front-end developer went through and truly understood, it wouldn’t take long at all to reprogram our already-logic-driven minds to the true semantic structuring of headings. I cannot say how we can improve these types of color contrast issues, aside from being mindful and questioning if aesthetic such as flat demands such low contrast elements beside one another. Even in enterprise, it’s not unheard of for design to be beautiful, but inaccessible to many.

H1: Headings Are Important

Common Heading Mistakes