Category: Web Development

Home / Category: Web Development


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

Part 1

Caterpillar on Human Wrist

Introduction & Screen Readers

Accessibility is one topic which not many take into account when designing and developing an application, website, or printed media even. The concept of visual and interactive accessibility relates to any medium which the user uses to discover and consume content from, and how different impairments hinder the common forms and designs useless and nonconsumable. Easiest way to explain that last statement is this example: Imagine being unable to read the standard news headline found on newsprint or websites, but still wanting to know what the world around you is doing. How might one approach this if they don’t wish to listen to a TV or Radio? How might one discover headlines around a certain topic that the locals gloss over? Screen Readers and accessible websites. This video can explain the concept and need far better than I ever could, and hopefully also provides a foundation which segues into the important attributes which screen readers utilize in more detail.

Element Hierarchy

Resource
Many developers disassociate the levels and semantics of element hierarchy when designing and developing, opting for H2’s because H1 is too big for example in article titles. Often, I’ve seen cases where the H2s were used for titles, and H4s used for subtitles. Though the overall aesthetic may look better for your needs, this does not comply with the established semantics which screen readers / interceptors read to the end user, furthermore it also messes with Search Engine bots looking for content on your website.

If it’s a more unified overall font sizing you’re looking for, use a normalizer stylesheet such as NormalizeCSS or a css framework such as Bulma.IO which dictates all text the be the same normalized size among supported browsers (implying that you will edit / extend for custom font sizing).

‘Fake’ Elements

Resource
When is a button not a button? Well, aside from the philosophical test which also has us questioning what truly is, and what isn’t, we can discuss again how different element tags provide unique attributes which are useful to screen readers and screen interpreters. Likewise, as the blog explains, these attributes are critical to proper understanding of a screen and the contents on the page. Using fake a tags styled to look like buttons, or divs with backgrounds meant to impersonate an image make interpretation of the page borderline difficult.

Contrast and Colors

Resource
It’s a good thing that most developers admit that they should never design, because in truth it’s not a skill many have in their genes. I suppose the opposite can be said for designers attempting to program, but I digress. Perhaps a different day’s story. When it comes to design, there is a ratio which many choose to ignore because modern aesthetic demands it, contrast ratio.

WCAG Level AA sets the golden standard for how the contrast ratio is defined, that is the difference between two colors (commonly background and foreground) such as text and parent element or borders and container backgrounds. AA compliance is a ratio of 4.5:1, which demotes many of the grey on gray choices of modern design. This is important because too little of a ratio makes text unreadable, and too high of the ratio is semi-literally blinding to even the common user.

Part One Conclusion & Examples

I hope to update this article later in the week with real-world examples and explanations of these details more, along with following up with the next segment which would include aria tags! If you made it this far, thank you for reading and I hope you enjoyed!

An OSD Contribution Update – Part 1

Header Image

While working towards implementing a fix for this bug, it was made clear to me that the bug was a regression, and not evident two months or so ago. This led David to directing me towards his (awesome btw) tutorial on how git bisect works, and how developers use it to determine where in the version history the bug was introduced. I’m glad that this concept existed, for even at work a few colleges and I attempted to replicate the similar behavior by hand, unaware that such tools already existed and was widely available.

Some background details that I had collected prior to me starting the bisect process:

  • I knew that the current master branch contained the issue. According to the comment thread, this issue had arrived around a month or two ago.
  • The Azure Functions validation logic is intact and functioning as expected, so the bug itself derives from refocusing the input after rerendering post-validation, a lifecycle which shouldn’t occur to begin with.
  • A custom extension could be created (and was provided in the bug description) which replicated the error.

First Steps – Identifying a Working ‘Good’ Commit!

In git bisect, you identify a good and bad commit range, which is used to isolate and pinpoint where the commit occurred which causes the bug. I wanted to identify a good commit prior to entering the process where the bug was not present so that the process would go along smoother. I started as early as git commit 834ba9b, and moved my way down the following commits to identify a ‘good’ commit:

  • 249a796 – November 20, 2017 – Still broken!
  • 83d8cbe – October 2, 2017 – Still broken!
  • 08d8f0f – September 25, 2017 – Still broken!
  • a87dd9c – August 21, 2017 – Still broken!

My Brain After This
Broken Down Bus

It was here that I decided there were two choices, continue going down this rabbit hole with the next commit jump being all the way to January 2017, or I admit that perhaps this edge case always existed and in consequence, needs to be addressed with the latest code base. I’ve decided that I want to go down the rabbit hole all the way to January 2016 if it produces a different edge case at least. That will be the introduction to part two, which I hope to publish in close succession to this first post.

Below are some of the issues which I encountered while working out this bug, and what caused what felt like work-week-long delays in between progress.

How far back I can go!

Trials, Errors, Showstoppers along the Way

Before I even started with the bisecting process, I knew that I had to attempt to replicate the bug in the development version of Visual Studio Code. Two hours later, here is what I learned:

  1. The Extension Gallery and it’s respective API do not exist as a part of the developer / open source Visual Studio Code. They exist similar to a feature toggle, which Microsoft activates in the production version, this being due to some licensing concepts and beliefs which is explained in much better detail here.
  2. You cannot sideload an extension easily without the Gallery API, which led me and hundreds of others who created, browsed, or cried for answers relating to this issue to a stackoverflow answer like no other. The code needed to be added to product.json:
  3. Extensions hook into a proxy-esque API (depending on their required context), meaning this process of using git bisect is entirely based on faith that the extensions themselves are not the issue. If they produce the error, your scope broadened 10x.
  4. Because all things must have versions and updates, it’s entirely possible while going forward / backward to encounter where version mismatches causes the extension or host editor to not be compatible.
    Version Mismatch with Azure Functions
  5. It is entirely possible because of the number 4, you will have to create your own extension. This is a battle of itself which I will describe below more.

Custom Extensions To Replicate Broken Edge Case

In the original bug, the reporter provided example code which when run, replicated the issue itself without an official extension. The tradeoff? Well you have to create a local temporary extension that Code will compile and attempt to integrate into its infrastructure. Issue? Well similar to the Extension Gallery being not included with the development version of visual studio code, neither is the node debugger and or compiler. These are extensions which are included by default with Microsoft’s release version. In attempt to mitigate before I get very hacky, I side-loaded the extensions gallery in the same way described above, and then installed node debug and node exec. The first allowed for successful execution of the environment (more on that), and the later is incase I could find a way to bleed / inject my custom function into the live environment.

I was able to follow the Microsoft documentation for creating and launching an extension with my standard version of Code, but that doesn’t help unless I’m debugging against the latest release (1.21.1). A few Github threads specify fixes for this issue so that you can bootstrap the production-built debug instance through your developer instance, but so far results have been less than stellar on MacOS and Linux. My worst case scenario that I think I will try if no further progress is made with the previous approach is to debug the latest (again), but this time focus on the validation handler, referencing commits which change its surrounding scope for example.

Important Update:
Thanks to David, whose eyes and searching skills proved themselves far better than mine, I was able to sideload the custom extension consisting of the following code into the development version of Code with this command: --extensionDevelopmentPath=\....

The extension which replicates the bug itself is:

Dependency Issues with Linux (Fedora 27) While Rolling Back

I encountered many dependency and build process issues on my Fedora 27 box while moving between commits, often cleaning /tmp directory to see if the issue was related to version mismatch. Later after some Googling I found that some of the issues related to NPM’s handling of file systems and permission, which was equally terrifying as I began to experiment while looking for a fix. Who wouldn’t be terrified after this lovely fiasco After about an hour or more of attempts, I moved to MacOS to see if that process would be smoother. If so, I can admit that my linux workstation probably needs a clean-up / reinstall, having served me and thousands of packages / files well for over two years without major issues. After I moved to MacOS on High Sierra 10.13.3, the issue relating to the different build systems was not apparent.

When I first started contributing what I could to Visual Studio Code, I was under the impression that it was written using React. Even while working with the custom drop down component, I was still under the impression there were React Front-end technologies which enabled for the dynamic rendering of various components and functionalities. Only in recent, while debugging and looking for high-level understanding of different scopes, did I realize that Visual Studio Code developed without the front-end JavaScript frameworks such as Angular, Vue, React or even MeteorJS. Without sounding like I just discovered Pluto being once called a planet, this was very left field.

Programmatically Generated UIs is a term I’ve heard while doing research on iOS Development practices, but I never considered a full-blown web application (including all the HTML attributes and so on) being powered in such a way. I remember using basic JavaScript to change the DOM while learning how to do front-end validation for INT222 (now WEB222) at Seneca, but never to generate entire navigation bars or full-blown text-editors; the concept and understanding of said concept is both the scariest, and most interesting discovery I’ve attempted to learn and dig deeper into in the past few weeks. Looking back at the custom drop down source code, I realize that I was so caught up in the state persistence and accessibility concern of the bug I was working on, I never realized just how genius the component’s implemented; in-house, no external frameworks or libraries.

The Flipping of Comfort and Concerns

In every project to date; be-it Enterprise for SOTI, Open Source, or even just Seneca course projects, I’ve never considered a programmatically generated and managed user interface. While looking more into Visual Studio Code’s logic, I instead of becoming familiar with it, began to become more concerned quicker and quicker as I had to search for life cycle handlers which a standard layout or framework would handle. DOM manipulation is one thing, but recreating, redrawing, and DOM-managing the entire component while all being in-house along with storing application state is very much left field compared to my experiences. While looking over the code, I did find two valid and worthwhile reason for such design practice, which I’ll explain below.

The Liberation from Framework Idioms

In the past year working with Enterprise level Angular applications, I’ve come to understand the saying ‘going against the grain’ when it comes to working with frameworks and libraries; they are amazing when you implement within their design and allowance, and an absolute nightmare when the scope goes beyond or against the framework’s design. I see with Visual Studio Code, the happiest of mediums where more time dedicated on design and development, and less on fighting the code and assets which make up your product.

Examples

Adding all event listeners to the custom drop down element

Dynamic styling of the drop down based on context

Creation of the select list HTML element

Deeper Management of Application Logic and Views

Compared to having multiple components, edge-cases and sub-component requirements, you can manage all of which (cleanly) in a single well encapsulated scope. This is only possible because of the (granted, concerning) freedom which programmatically managed interfaces offer, since scopes of the element such as data, state, and interface itself derive from the same scope: in a single language and instance (compared to Angular’s HTML, TS, and SCSS separated file structure). One video that I had discovered last year which explains the benefits and reasoning why even iOS developers going this route compared to creating storyboard layouts:https://www.youtube.com/watch?v=up-YD3rZeJA

Final Thoughts

I’m looking forward to exploring new concepts such as this as I go about Visual Studio Code, and hoping that I never stop being thrown into challenging or adventurous situations where the only way out is to learn and understand it. I’m sure I’ve only uncovered only 5% of the entire concept, still unsure of every reason behind it, and even the proper implementation paradigms in Code; going forward with the bug fixes and improvements I hope will explain more and make me a better developer in the process.

An OSD Contribution Update

For the last three years, I’ve grown a passion for extending technologies towards a direction which makes them more accessible for a wider range of users. It took a while to realize what accessibility truly meant in the world of development, software, websites and health organizations. Through the process, I took a course on behalf of my employer at the time to learn the three levels which make up the Web Content Accessibility Guidelines (WCAG) 2.0, A, AA, and AAA. This course took me through so many spirals of knowledge and issue, all-encompassing different scenarios and acceptance criteria for web development. After taking the course, I started to see software design and accessibility very differently. Contrast between colors, element organization, font-sizing even became subject of my mental focus at first.

When looking for issues and improvement requests in Visual Studio Code, I decided for this round that I wanted to explore and help improve how we handle accessibility within the platform. This led me towards two bugs which relate directly to the newly released custom drop-down component which was apart of the February 1.20 release. I thought this would be a great outlet for contribution since it’s a brand new component to the project, enabling me to also seat myself if possible in that domain and help update and upgrade the component over time.

Monokai Drop-down Selection Theme

This bug was originally an issue directed towards how the Monokai theme handled drop-down selection indicates the currently selected item. After discussing in the issue how to handle the fix, a proposed quick solution was implemented and tested. Changing the list.focusBackground to a different color of the Monokai theme, thus ‘fixing’ the issue.

The reason why I said ‘fixing’, is because this very small, single line fix also produced evidence towards a bigger issue with the drop-down component which would span all custom themes. Essentially, there was no way to promise this improved accessibility for custom themes which set list.focusBackground to a non-common theme color, since the attributes used in many components alongside the drop-down.

Christopher Leidigh known as @cleidighon on GitHub, developer for Visual Studio Code, and also contributor to the new drop-down component provided a non-intrusive update which provided a new attribute titled dropdown.listBackground which is used by the component if it exists. With this update, switching list.focusBackground back to the previous color and using dropdown.listBackground provides the bugfix without breaking the established patterns of decade old themes, and custom editor themes. I have a feeling that this will be expanded later to accommodate APIs and contrast-awareness functions. The final PR can be found here

Escape Key Should Revert Selection to Previous State

Again approaching accessibility improvements and learning more of the drop-down component, I was introduced to this bug. Essentially, it is a request to return the common behavioral pattern of when a user hits escape during text input modification, return to the original state. A simple concept, and I had an idea which is in my work in progress PR which is found here.

Essentially, store the currently selected index when opening the drop-down component, and in onExit and onBlur restore the selected item back to the original state. Simple enough I think. There isn’t any magical React / Redux paradigms occurring here, so I feel pretty confident in my initial approach and, based on Christopher’s initial review of my attempt, we share the same mindset for this update.

Conclusion

Was this a huge contribution / release? No. That I can admit, and if I do have time I’ll try to find a bug to make up for the lack of substance. This round of open source interactions allowed me to discover a few interesting lessons, some of which I consider as valuable:

  • A single one line bug fix can produce a tentacle of other bugs and or politics.
  • Accessibility is a characteristic which can be easily overlooked, and is overlooked often times by the common developer.
  • Working remotely with developers in different time zones can create one of the most interesting plots of disconnect and resource-management that I’ve ever seen. You see their replies in the morning when perhaps they are calling it a night. This grants you HOURS before they’d see your reply, providing space and resources to plan out both your intent and knowledge base towards the issue and the reply. Likewise, it’s very easy to fall into the trap of waiting around for a reply as I did during segments of this release, which is ill-advised if one is seeking continuous progress and movement.

Going forward I really hope to discover more improvements or bugs relating to the drop-down component or various other UI elements, ones revolving around accessibility being preference. Code is so much bigger than I would have ever imagined, and seeing the following response from a well-respected Developer such as Christopher admitting that even he is only scratching the surface lifts my spirits when I find myself lost in endless lines of code and confusion. With each new experience, I look forward more and more towards the next step into Open Source.

I love Bulma, I love contributing to projects instead of spinning up my shoddy implementation of a need, and I love when the two come together in such harmony it’s as if fate meant it. I discovered BulmaPress while looking for Bulma / Non-Bootstrap WordPress themes for a CMS project I’m working on. It looked to be relatively abandoned, sporting an old version of Bulma 0.2.1 and last being updated half a year ago.

Still, this didn’t deter developers including yours truly from forking and fixing or updating; a relatively painless experience since the project was built on-top of the underscores project, providing a solid foundation which only needed the Bulma part to be updated instead of the WordPress theme functions. It took several iterations to get the modern Bulma navigation pattern to work as expected, but once that was in place (you can see the code change required here), the rest fell much quicker.

Instead of keeping the fix to myself, I decided that any updates should make it upstream to benefit other users who discover the project. These fixes included removing the outdated Bulma code (replaced with a CDN), fixing the SASS compiler, and now writing a stable override structure which provides easy modification of Bulma variables.

The SASS was priority in my mind after correcting the navigation since no one sticks with the defaults, almost ever. Writing in CSS is a pain when it’s a full website theme, and once you learn SASS, SCSS, or LESS, CSS functions like assembly in comparison. Literally! For my project, I also needed the SASS configurable since this project would involve multiple different overrides and branding elements too.

As my first contribution got merged in, I became a contributor to the project and was also promoted to maintainer (meaning I could merge, triage etc). It’s a cool experience to see yourself at the top of a contributor board on an abandoned project: https://github.com/teamscops/bulmapress/graphs/contributors. The numbers do seem off, but I’ll let the GitHub magicians assume what they will about code changes. Later on, I’d begin to have questions tweeted or emailed to me on BulmaPress, which was another cool moment because I realized this abandoned project still had love from developers who perhaps like me, needed exactly it.

This is my first time working inside-out on a WordPress theme, my only previous experience being changing the default layout of the theme to support Bootstrap headers for a client two years ago. Working with only foundation, knowing that everything else can change if needed was an opportunity that I didn’t expect from BulmaPress. I had different ‘implement this feature so you can use it’ styled expectations, not so much ‘update this because a lot has changed in recent years’. There is still a lot to update and fix, such as the navwalker used for multi-tiered navigation menus (Which I don’t believe ever worked to begin with according to comments in the code), and fixing the demo domain issue where you which expired in January.

An OSD700 Contribution Update

Interesting concept, it’s a very surreal experience to explore and work on a project while using said project as the tool for development and exploration.

For a good part of the weekend, I’ve put aside time to look into how Visual Studio Code handles and manages the Command Panel, a tool / extension which I use daily for accessing various extension actions, configurations, and accessing files. The reason for trying to undercover the goldmine which is le Command Panel can be found in my attempt to add a color picker toggle to the list, a work in progress pull request can be found here.

Fully Customized VSCode, Command Panel Displayed

Attempt #1

My first attempt towards adding a command to the command panel was based off of how the comment extension accessed the panel. Later I would be pointed to a better example which I address in Attempt #2. In this attempt, I tried to create a wrapper which would expose the ColorPickerWidget class to the command panel, similar to how it is done here.

The idea at first made sense, till I realized that the implementation of CommentLineAction was directed to manipulation of the code close to the cursor. Furthermore, I didn’t need the kbOptions related scope in this case, since the original intent is simply to toggle a Color Picker through the command panel. I should have kept the code as an example here of what Attempt #1 looked like, but I had reverted back to the branch’s version prior to writing this post.

Attempt #2

After much research and discussion over the VSCode Slack Channel, I came to the conclusion that the first attempt should be redone using a better reference: hover.ts, which compared to comment.ts, provided a much better context. Thanks to Eric Amodio (Creator GitLens) for the tip there!

Attempt 2 for Color Picker

Through this process of trial and error, I learned the basics of how the command panel worked: How commands and context are loaded into its elasticsearch-esque data-store, how said commands call different scoped functions and contexts, and how to add my own command into the mix!

Putting EditorActions (Commands) into the Command Panel

A command you see in the panel is really an extension of the abstract class EditorAction, which extends EditorCommand. This extension allows for one to program the context of how the implemented run command, contexts, editor-permissions, and keychords while providing a type inferred structure which is compatible with the original EditorCommand interface.

You can see in the snippet of code linking to my second attempt, the super call in the constructor handles creating a IActionOptions object, which is an extension of the abstract class ICommandOptions. It is this portion of the object which is placed in the Command Panel to provide context, labels, translation and scope. The Comment extension ~/src/vs/editor/contrib/comment.ts shows the alternative way of handling the IActionOptions, which you can see below. I prefer this method due to a much cleaner and easier to read since the scope does not include the functionality, but the command alone.

The final part is to call registerEditorAction which is imported from ~/src/vs/editor/browser/editorExtensions as you may have guessed. The total amount of imports from that file derives directly with the context and actions that your command will need or perform, below I’ve listed the common ones which I encountered when looking through the comment, and hover extensions.

EditorCommand

Location: Github Link
The function which extends Command, and provides the inner-architecture required to bind and remove actions to the command panel. It’s public functions are:

Command

Location: Github Link
Command is the base class which appears to be replacing (based on the commit history favoring it over ICommandOptions for updates / improvements), and is extended by EditorCommand.

ICommandKeybindingsOptions

Location: Github Link
ICommandKeybindingsOptions appears to act as another context-aware object, this one containing an optional weight (of importance / override?) variable which makes me believe that this is used for keyboard chords (ala Emacs) and priority only-after the precondition in Command has been met.

IKeybindings

Location: Github Link
This class is extended by ICommandKeyboardOptions, which provides the correct keyboard-codes for Emac style keychords.

ICommandHandlerDescription

Location: Github Link
As the name suggests, this object handles description of the Command Object, not to sure to be honest what the purpose of this object since all labels are handled at the root of the object which would be displayed.

ContextKeyExpr

Location: Github Link
The ContextKeyExpr is an abstract class which contains the following public functions for working with the cursor:

IEditorCommandMenuOptions

Location: Github Link
This class appears to dictate the context of when an action is available in the command panel, checking against the ContextKeyExpr object it appears.

Making Your Command Execute Specific Scope & Functions

In the class which extends EditorAction, you have to implement the function titled run. This function is crucial, for it is exactly as you’d guess, the code which is hit upon calling your command from the panel. Since my own isn’t 100% complete at the time of writing this blog post, I’ll reference comment.ts again for how a proper run implementation works.

It is still unclear to me why editor.pushUndoStop() is executed twice, perhaps to correct duplicates? Perhaps I still have more to research and understand regarding the command panels data store, for the only hint I found being the code comment itself, Push an “undo stop” in the undo-redo stackfound here

ICodeEditor

Location: Github Link
An interface of the editor itself. Listening for events and acting as the glue between the user’s keypresses and the rest of the system. This is fed into the run command to provide access to context, events and user input. If that doesn’t provide enough weight towards just how powerful this interface is, the current structure spans 409 lines (which does include 5 lines roughly of TSDoc providing documentation to an estimated 81 (409 / 5) functions!

Comment Command Action

Conclusion to this Experience

I can admit there will probably be quite a few mistakes, missed scopes or crucial details that a weekend of research and speculation cannot provide, but in that time I’ve tried to acquire as much as possible, in the process learning a great deal of how Code’s command panel operates, the overall architecture relating to the editor and it’s extensions, and how CMD+T (or CTRL + T on Windows and Linux) brings up a contextually aware panel full of options and usability. I cannot understate just how vital it is to seek guidance from other developers, developers who have already contributed and work to the project and thus, can help guide you through the never-end maze of classes, interfaces, services, observables and architectures which make up such a huge project.

On an architectural footnote, VSCode (and perhaps in response, React) follows a very different order of components, services, and delegation of tasks compared to Angular does. The difference is quite colorful at first, some being obvious compliments such as Observable / RXJS patterns, others being grotesque and difficult to understand. I was looking forward to both ends of the spectrum jumping in, for it allows me to compare and perhaps even evaluate the different development decisions made between my own projects, work projects, Code, and tutorials. I hope that through this, future projects are inherently improved upon in design and implementation from said experiences. Interestingly enough, I’m reading The Art of Unix Programming by Eric S. Raymond, which provides different insight still relevant even this day to the idea of software development and architecture. The parallels between Code and Unix’s philosophy appear more and more the deeper I look, and I’m hoping to gather enough on the topic to write a blog post later in the year explaining such.

.

Building Visual Studio Code

January 25, 2018 | Open Source, Web Development | No Comments

On MacOS High Sierra

Building Visual Studio Code is quite the interesting process, mostly because the dependencies differ in obtainability between operating systems. For this article, I’m going through the process on MacOS High Sierra since it will be primary development machine for upcoming bug fixes, code improvements and contributions to Microsoft’s Visual Studio Code.

Set Up

Visual Studio Code requires the following prerequisites, Git, NodeJS, Python, GCC, Make, and Yarn. Of all the dependencies for this project, Yarn required me to use homebrew for installation, which is supposed to be as simple as brew install yarn if you have it configured correctly. I didn’t, so following the excellent single step found here https://brew.sh helped set up and configure Homebrew on MacOS. Finally, running through the CLI yarn will install all other dependencies over the course of an hour depending on your internet connection.

Building & Launching A Development Instance of Code

After installing all dependencies, the setup guide simply says to run yarn run watch which will compile and build Code. From there, if you see no errors or warnings you’re good to proceed!


Launching via ./scripts/code.sh for Linux or MacOS, or ./scripts/code.bat results in the final compiled application executing!

Going Forward

Right now, I’m looking into bugs relating to Visual Studio Code’s Color Picker, which is a front-end developers best friend when it comes to writing CSS Framework overrides and theme templates. Currently, I’m exploring the following potential bugs:

One pattern that I’m starting to discover among many of the bugs reported, is a lack of administration among the various domains. Bugs have been fixed, merged, etc, the tickets themselves remain open and untouched. More research is being conducted to discover bugs which line up with my interests and end goals, worst case being moving to a different domain of the project, or trying to find a different open source project to contribute to such as Angular Material https://material.angular.io.

City Bokeh by Gabriele Santiago

I’ve been a major fan of Bulma ever since discovering it through the weekend project of developer Hassan Djirdeh (@djirdehh), https://www.cryptovue.com. On top of introducing me to the Bulma CSS framework which I instantly fell in love with, it also introduced me to VueJS, a JavaScript framework which, like Bulma, is capturing the attention of developers quicker and quicker each day. It’s been at least five months since I had first discovered Bulma, and in that time it’s already become my favorite CSS Framework and goto tool for Front-end Web Development. It’s replaced Bootstrap, Foundation, and Semantic UI within the span of months; a task which I wouldn’t consider easy by any means.

Bulma is written entirely using CSS alone, meaning that the developers are reliant on their own code alone if they want to introduce functionality such as a hamburger menu toggle it’s CSS class; an opinion that I highly am a fan of, since it reduces the bloat that I was often uncomfortable with when it came to Bootstrap or Foundation. On Top of that, Bulma is written using flexbox instead of traditional CSS grid mechanics, making it much more accessible and extendable where needed. If you hadn’t heard of the framework or played with it, I highly recommend seeing the documentation and comparing it to your favorite framework: bulma.io.

I often browse the issues and pull requests of projects which interest me for that time, and when an issue caught my attention as a topic which I highly needed, or wished for as well, I’d jump in offering to help in anyway possible. This behavior resulted in a week long discussion with Jim Blue, a contributor who had raised the the bug which caught my attention; the result being the solution which would follow the bulma culture best. is-small, and is-large css classes were created for the hamburger button, allowing for the developer to intentionally double or halve the hamburger button while styling the navigation bar to their requirements.

This small contribution perhaps means little to most developers, but I found the fix to be quite useful since in my own projects, I’ve had two instances (so far) where I had to override the defaults of the hamburger button to follow a new desired width / height, this in consequence requiring the spans having to be adjusted to accommodate the ratio as well. The addition of these classes make it much more accessible, and provide non-intrusive options for when the defaults don’t fit your criteria.

During this process, I learned over the week-long discussions and idea-throwing just how easily it is to misinterpret user experience expectations, even when written in the simplest of terms. The concepts from either side being misunderstood resulted in three seperate ideas and implementations, all for a simple CSS bug. That’s amazing! It’s amazing when I reflect on this, thinking of how much bigger projects with developers all over the globe get only conventions, concepts and rich-text to convey such delicate ideas effectively. The world of Open Source is amazing like this, where barriers which separate communities are simply ideas conveyed through language and language alone.

Visual Studio Code Setup

Visual Studio Code has quickly become my go-to text editor for many languages, even replacing XCode for Swift-centric programs or IntelliJ for light-weight Java programming. This article focuses more on the web development plugins which have provided a smoother experience for the past eight months of my internship at SOTI while learning the ways of the full-stack developer. If you have suggestions or alternatives to the listed plugins, I’d love to hear about it in the comments!

I’ll segregate the list based on the web technology, which will help to separate the primary use case for the plugin via yours truly.

HTML

Emmet

I cannot for the life of me explain Emmet via text properly, so instead I’d recommend this video by Traversy Media if you truly want an overview and in-depth explanation: Emmet For Faster HTML & CSS Workflow. Visual Studio Code bundles this plugin now, but the functionality is available found in almost every IDE and text editor which supports third-party plugins. It has saved me hours of CSS / HTML syntax typing, while also providing fantastic configurability for my coding style.

Stylesheet

SASS

When not writing in SCSS, I write in SASS. SASS as a language is tenfold more efficient than standard CSS, and compiles down to CSS in the end of the day. The need for this plugin is due to the current lack of built-in support for SASS on a stock Visual Studio Code, and this plugin provides syntax highlighting. The official website is well documented, and switching between SCSS and SASS for different projects is relatively seamless due to the similar syntax.

IntelliSense for CSS class names

Depending on the project, I end up with 100+ class names for specific elements or mundane states which are configured differently. This helps by parsing and suggesting through the IntelliSense engine relevant class names as soon as I start typing.

StyleLint

Following a well established style guides enable a clean and maintainable project, but up until this point I had not yet learned Style related properties inside out, front to back. This plugin points out redundant styles, non-applicable calculations / dimensions and other issues that my style sheets contain, allowing for a cleaner and less hack-filled workflow.

TypeScript

TSLint

Similar to StyleLint for style sheets, TSLint enables one to adhere to predefined coding guidelines in their TypeScript files. This has been an absolute godsend when working with others, or even keeping myself disciplined in those late hours where lazy ‘any’ types start to arise. If I could only choose a single plugin to  recommend on this list, it would be this TypeScript linter. It has transformed code bases from mess to organized chaos, and unfamiliar object types to defined and well tested structures.

Code Runner

I find that the usage of this plugin derives from my introduction to Firefox’s Scratchpad. Because of this common habit of prototyping code in a dedicated scratchpad environment,  utilizing Code Runner in a similar fashion only seemed natural. I found prior to my introduction to unit testing, Code Runner also allowed me to isolate and test functions without having to worry about environmental variables.

Git

Git Lens

This plugin mimics the lens functionality found in Microsoft’s Visual Studio, showing last commit detail involving the current line of code. Whether it’s quickly figuring out where a new function is introduced, a style class changed, or comments added, this plugin makes the process effortless and efficient. So far, I had yet to see any lag on the system with the plugin active 24/7, and the experience itself doesn’t leave me wishing the plugin was anymore less obtrusive than the current implementation. To me, it’s a perfect representation of the data I’m interested in seeing as I work with a complex code base.

Editor Themes & File Icons

Material Icons

I found this icon pack to offer the best overall aesthetic when mixed with One Dark Pro or Nord Dark, while also providing a coherent design language which still described the folder structure and file types with ease. Overall, this is one of the first plugins installed on any workstation.

One Dark Pro

Having come from Atom before, I actually found their standard One Dark theme quite attractive during the early hours in contrast to Visual Studio Code’s dark theme. I still have some gripes with the default background – which, I find is simply too bright on the standard Dell 1080P matte monitor. Still, an excellent theme which deserves all the recognition that is has, and looks utterly fantastic on my 4K screens.

Nord

Ever since I had discovered Nord, I had discovered a truly amazing color pallet which seemed to have found itself supported 99% of every tool that I’d ever use. From IDE to GTK themes, Nord is supported or being developed with upcoming releases occurring weekly. I highly recommend looking into the repository and projects by Arctic Ice Studios, which is located here: https://github.com/arcticicestudio/nord. For the latest of hours, I typically switch to the settings found here for ‘Nord Dark’, which simply darkens the background and menus.

Settings

Settings Sync

This plugin has become an utter godsend when it comes to working on multiple machines and operating systems while keeping all of my settings, plugins and configurations synchronized. By keeping everything synchronized through a secret Gist, I can focus on learning and optimizing my workflow instead of matching functionally from one workstation to another.

Conclusion

In the end of the day, I’m constantly trying new plugins and workflows when I find an annoyance or void in my current, so this list is really a snapshot as of recent workflows and settings which work well for my setup. By tomorrow, it could change easily and with that, luckily my settings would synchronize among all devices. This is the beauty of Open Source, that you can mix and match until your heart’s content. I love that fact more than words can describe, for it means to me that you are never thrown into the cage with only the plugins provided by the jail staff.