s that are named based on the kind of component you are using. For example, is the entity that houses our “Hello world!” text. All A-Frame primitives are some form of entities that combine a subset of components. **Component **is the reusable chunk of data that gets added to entities to bring them to life. So if is the HTML entity we add to our site, the value and geometry components are like the CSS to turn that entity into something meaningful. **System** is the management system that ties components together across all of the entities they belong to within a scene. So if we again refer to the geometry component, the system for that component is what allows geometry to be shared by , , and primitives, controlling the shapes of the objects and how those shapes appear in space in relation to one another. Understanding ECS is vital to conceptualizing the A-Frame API because A-Frame is essentially a giant collection of starter entities and components organized by various systems. You can then use these systems to build more complex and engaging components or entities to make your own environments richer and more interactive. ## Next Steps We’re barely scratching the surface on what VR can do today on the web. Even though VR itself is a brand new and growing platform, truly immersive web experiences are already possible with browsers like [Supermedium](https://supermedium.com/). These VR-first browsers provide a platform to showcase the power of frameworks like A-Frame. If this article piqued your interest in really diving into WebVR and A-Frame, A-Frame provides a guided tutorial series called [A-Frame School](https://aframe.io/aframe-school/#/1) to walk you through building your first WebVR application. Once you think you’ve got something unique to share, there are a few places to promote your work. Supermedium offers a [directory](https://webvr.directory/) for compelling WebVR projects, as well as sites such as [WITHIN](https://vr.with.in/). VR right now is very similar to the early days of the web: fun, expressive, and weird. There’s no need to try to aim for professional or production quality. Rather, we’re in the nascent stage where expression and creativity thrive, pushing people to test the limits of what is capable while the technology is still being fleshed out. There’s no better time to get ahead of the curve with the most bleeding-edge user interface than in AR/VR on the web with A-Frame. *Originally published at [softwareengineeringdaily.com](https://softwareengineeringdaily.com/2018/06/29/how-to-get-started-in-vr-with-a-frame/) on June 29, 2018.* ]]> 2018-06-29T09:25:00+00:00 https://www.adamconrad.dev/blog/what-you-need-to-know-about-wcag-21/ Wed, 27 Jun 2018 14:11:00 +0000 https://www.adamconrad.dev/blog/what-you-need-to-know-about-wcag-21/ 2.1.4 Character Key Shortcuts (A) * 2.5.1 Pointer Gestures (A) * 2.5.2 Pointer Cancellation (A) * 2.5.3 Label in Name (A) * 2.5.4 Motion Actuation (A) * 1.3.4 Orientation (AA) * 1.3.5 Identify Input Purpose (AA) * 1.4.10 Reflow (AA) * 1.4.11 Non-text Contrast (AA) * 1.4.12 Text Spacing (AA) * 1.4.13 Content on Hover or Focus (AA) * 4.1.3 Status Messages (AA) * 1.3.6 Identify Purpose (AAA) * 2.2.6 Timeouts (AAA) * 2.3.3 Animation from Interactions (AAA) * 2.5.5 Target Size (AAA) * 2.5.6 Concurrent Input Mechanisms (AAA) ## What do the different conformance levels (A, AA, AAA) mean? As seen in the WCAG 2.1 document, there are a large number of recommendations for accessibility. It would be unrealistic to expect site owners to adhere to them all, so **each success criterion is given a priority for how important it is to satisfy**.  Level A criteria are the most important, followed by AA, and then finally AAA criteria. Each level builds on the other, so it is necessary to satisfy all of the Level A requirements first before trying to satisfy AA or AAA requirements. This is because the W3C [requires full conformance at each level to be recognized as compliant](https://www.w3.org/TR/UNDERSTANDING-WCAG20/conformance.html#uc-conf-req1-head). > For Level AA conformance, the Web page satisfies **all the Level A and Level AA Success Criteria**, or a Level AA conforming alternate version is provided. Each section starts with Level A requirements, and builds up to Level AAA, with each requirement adding onto the previous one. For example, Section 3.3 is on input assistance. 3.3.1 and 3.3.2 are Level A requirements. 3.3.3 builds on 3.3.1, which is Level AA. The highest level, 3.3.5 and 3.3.6, base success around much more involved criteria, and thus achieve a rating of Level AAA. ## What conformance levels do I need to pass? The obvious answer would be to aim for AAA compliance, which is the strictest and most complete standard. The Level AAA standard will create an environment that maximizes your audience reach by providing support for the widest audience of disabled persons. Practically speaking, **aim for Level AA conformance**. This is the highest realistic conformance level to achieve. The W3C recommends this level as well: > It is not recommended that Level AAA conformance be required as a general policy for entire sites because it is not possible to satisfy all Level AAA Success Criteria for some content. One example of Level AAA conformance that cannot be satisfied is [WCAG criterion 2.1.3 for keyboard shortcuts](https://www.w3.org/TR/WCAG21/#keyboard-no-exception). If your application is only available on mobile, such as the Uber app, there is no real keyboard, so it cannot be navigated by keyboard shortcuts, and will not pass this success metric. This, of course, is not a practical requirement because Uber is designed for use on mobile and should not have to try and cater their strategy towards a requirement like this.  Now that we have an idea of what level we need to aim for, here are the new success criteria in the updated guidelines and how to pass them. ## New WCAG success criteria ### Level A: The bare minimum #### 2.1.4 Character Key Shortcuts (source) ##### What it means Keyboard shortcuts aren't just for power users like vim developers. They are also super useful for the blind, who have no reason for using a monitor or mouse. Therefore, it is a good idea to implement some basic keyboard shortcuts to navigate your site without the need for a mouse. ##### How to pass * **If you have shortcuts, make sure you can disable them** * **The shortcut can be mapped to a different key than you provided by default** * **The shortcut can only be used on a component on in focus.** You can't accidentally trigger the shortcut if it isn't actively on the part of the page that should receive that shortcut. #### 2.5.1 Pointer Gestures (source) ##### What it means Things like touch gestures have many ways of interacting. Single point gestures include tapping or clicking. Multipoint gestures include things like pinch-to-zoom. Path-based gestures include things like swiping or sliding. Your application should account for all of these.  ##### How to pass If you use multipoint or path-based gestures, the **actions that are triggered by those gestures should have a single point fallback**. In other words, if you use the swipe event to mark something as complete, you should also have a touch or click gesture to mark that item complete as well. #### 2.5.2 Pointer Cancellation (source) ##### What it means Actions can be triggered with, for example, a click. Those actions should be reversible. ##### How to pass * **Don't use the down-event** (e.g. `keydown` or `mousepress`) unless it is essential * **Show a popup or alert to undo the previous action** * **If you use a down-event, an equivalent up-event should be available to undo that action** #### 2.5.3 Label in Name (source) ##### What it means Images can be used inside of a label to describe content. The component housing those images should have a text fallback of that image content. ##### How to pass * **If you use an image to label something, the naming attribute should have the text of that image or a description of that image as a fallback.** [Accessible name and description mappings](https://www.w3.org/TR/accname-1.1/#accessible-name-and-description-mapping) include attributes like `alt` for `` tags, [captions, transcriptions, and descriptions](https://webaim.org/techniques/captions/) for ` 2018-06-27T14:11:00+00:00 https://www.adamconrad.dev/blog/how-to-find-excellent-refactoring-opportunities/ Thu, 14 Jun 2018 21:13:00 +0000 https://www.adamconrad.dev/blog/how-to-find-excellent-refactoring-opportunities/ # An example in refactoring Here's the (obfuscated) code I was working with to begin our journey: ```javascript const addEvents = (events, label, segment) => events.push([label, segment]); const main = () => { const [upcoming, past] = partition( arr, date => today.diff(date, 'day') <= 0 ); const events = [] if (upcoming.length > 0) { addEvents(events, 'upcoming stuff', upcoming); } if (past.length > 0) { const byMonth = groupBy(past, date => moment(date).format('YYYY-MM'); ); const months = Object.keys(byMonth).sort().reverse(); months.forEach((month, idx) => addEvents(events, `${idx} months ago`, month); } return events; } ``` This code is pretty simple - I've got two arrays of dates: upcoming dates, and past dates (including today). I just need to let the world know what's coming up and what is in the past, so it's not a simple push to an array because each chunk is split off by month (except for the future, which is just labeled future stuff), and each section is really a tuple of label and date. So what immediately got me tweakin' on this code? ## Single Responsibility Principle By now the SOLID acronym is engrained in my brain. If you don't know what it is, thoughtbot wrote a [great intro about what SOLID is](https://robots.thoughtbot.com/back-to-basics-solid) so definitely check that out. The most obvious one that people seem to remember is the first one, Single Responsibility Principle. It's probably the easiest because the definition really says it all. Your class/function/whatever should do one thing and do it well. In this case, I see a bunch of stuff, so my first thought is to break this function up into multiple functions. How do I know how to break it up? Stuff like `if` statements are literal blocks of code. Since everything is essentially scoped to blocks in JavaScript, anything inside of a bracket is a good candidate to break out into its own function. I'm also going to cheat and skip a step, because `if` statements also provide another subtle hint: **the `if` keyword can usually be refactored into a guard clause.** Why? Because it is already guarding some code against being run within your function. If we rewrite the `if` in guard clause notation (meaning, exit early before the function has a chance to run), along with the SRP refactoring, we get: ```javascript const addEvents = (events, label, segment) => events.push([label, segment]); const addUpcomingEvents = (events, upcoming) => { if (upcoming.length === 0) return; addEvents(events, 'upcoming stuff', upcoming); }; const getPastMonths = past => { return groupBy(past, date => moment(date).format('YYYY-MM')); }; const addPastEvents = (events, past) => { if (past.length === 0) return; const months = Object.keys(getPastMonths(past)).sort().reverse(); months.forEach((month, idx) => addEvents(events, `${idx} months ago`, month); }; const main = () => { const [upcoming, past] = partition( arr, date => today.diff(date, 'day') <= 0 ); const events = []; addUpcomingEvents(events, upcoming); addPastEvents(events, past); return events; } ``` ## Mutation is ugly Already this looks way better. `main()`'s single responsibility is populating the array of `events` and returning them. Each extracted function has one responsibility based on its function definition. So I guess we can call it a day, right? The next smell I see is this pattern: ```javascript const myPoorFriendArray = []; // a world of hurt, warping our pristine, empty friend blackBoxFunction(myPoorFriendArray); moreTorture(myPoorFriendArray); theGauntlet(myPoorFriendArray); // we chew him up and spit him out, never knowing the horrors he experienced return myPoorFriendArray; ``` Ya feel me on this one? Our boy `myPoorFriendArray` is now an honorary X-Man: mutated from his original, empty form, into some chimera of various parts of the code. [Kanye said it better than I can](https://www.youtube.com/watch?v=fSJoDuU328k), but this is the stuff I _DON'T LIKE_. Maybe you come from an OO world like Java and mutation is just a regular, everyday occurrence. If you're woke and you come from a functional background like Elm, you can see that mutants are bad. We don't want no X-Men fighting for us on the coding battlegrounds (sorry Gambit, love you). So what's the fix here? 1. **Send the empty array in as an argument to our first add function** 2. **The function will take in the empty array and make a copy** 3. **The copy is filled out and returned** The argument is not mutated, and we remove state dependencies. If you've done any functional programming, terms like _stateless_ and _immutability_ are everyday terms, and that's what we're striving for. Our stateless code doesn't have [side effects](https://hackernoon.com/code-smell-side-effects-of-death-31c052327b8b), a nasty code smell that makes bugs more difficult to track down because state persists across functions. Without state, what you put into it is what you get out of it each and every time. Making your functions predictable, and thus less likely to include errors you didn't test for. Here's what this change looks like: ```javascript const addEvents = (events, label, segment) => events.push([label, segment]); // we didn't touch the middle functions... const main = () => { const [upcoming, past] = partition( arr, date => today.diff(date, 'day') <= 0 ); return addPastEvents(addUpcomingEvents([], upcoming), past); } ``` Now we're getting somewhere! But for the savvy reader, something should still seem off. Can you see what's still wrong? ## Negate the state **We didn't really remove the state from the add functions.** Yeah, we gave it a starting point in our `main()` function, but the `addEvents()` function is still adding events to a singular `events` array which is getting passed around like a rag doll. How do I know this? `Array.prototype.push` is a mutable function. It provides an interface to add stuff to an array and returns the number of elements in the enlarged array. How do we do this in an immutable way? `Array.prototype.concat` is the immutable equivalent of `push()`. It takes an array, combines it with another array, and those two are combined into a newly-allocated array. So we can modify the above slightly to be: ```javascript const addEvents = (events, label, segment) => { if (!label) return events; return events.concat([[label, segment]]); }; ``` Now we never touch our inputs. `events` remains as pristine as it was the day it arrived in this humble function, and instead we use `concat()` to combine `events` with the new array we've made, which is the array of our tuple (a point of clarification: tuples don't exist in JavaScript, but I'm using that term to describe our 2-item array to make the distinction clearer here). Now I'm in audit mode: where else do I need to follow this pattern of not touching the arguments and ensuring I return an `Array` type? ## Provide type safety If you aren't using TypeScript, this is a great way to practice some proactive type safety to ensure that your function returns objects of the same type regardless of the output. That means don't return an `Array` if you have stuff, but return `undefined` or `null` if you exit early (like in a guard clause). Oh crap, I'm doing that. Looks like another opportunity to refactor! ```javascript // unchanged but illustrating that all functions, including this one, always return an Array const addEvents = (events, label, segment) => { if (!label) return events; return events.concat([[label, segment]]); }; const addUpcomingEvents = (events, upcoming) => { if (upcoming.length === 0) return events; return addEvents(events, 'upcoming stuff', upcoming); }; const getPastMonths = past => { return Object.keys(groupBy(past, date => moment(date).format('YYYY-MM'))).sort().reverse(); }; const addPastEvents = (events, past) => { if (past.length === 0) return events; return getPastMonths(past).reduce((acc, month, idx) => { return addEvents(acc, `${idx} months ago`, month), events); }; }; ``` Lots to unpack here. So in `addUpcomingEvents()` all we did was make sure we return an `Array` and not `undefined` (ending with just `return;` is shorthand for returning an `undefined` object). We do this because `concat()` returns an array, so we want to make sure all `return` statements provide the same type of object in any given function. Next I did some refactoring of `getPastMonths()` to handle the sorting an reversing, because the `groupBy` function _technically_ returns an `Object`, and a way for it to return an `Array` is to grab the `Keys` (which is an `Array`) and do our necessary transformations to that array object. Finally, `addPastEvents()` starts out the same as the upcoming function by ensuring our guard clause returns an `Array` type. The next part is a bit wilder. Originally we were taking an array and iterating over it using `Array.prototype.forEach`. The problem is that this iterator doesn't return an `Array` like we need it to. It simply gives us a platform to view every item in our array. We also know that in the end, we want one array object that adds in all of the past events. **When you think about needing to combine things into one and return that combined object, think of using [`Array.prototype.reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce).** In this case, I knew I needed to add the events (by month) into our `events` array, _and_ return that newly combined array, using `events` as the starting point. The reduce function takes two arguments, a `callback` on how to combine stuff, and an optional `initial` object to begin with. The `callback` is probably the most confusing part - what is this nested `return` trying to do? The `reduce()` `callback` argument has two arguments of its own: an `accumulator` object, which is initialized to our `initial` object (if you leave it out, it defaults to `undefined`), and the `current` item that is being iterated on. There are two additional optional arguments: the `index` of the item you are iterating on, and the original `array` object you called `reduce()` on. Since we need the `index` argument to label our months, I added that in. So with all of that said, the `reduce()` function is basically saying: > For each past month in my array, add it (with its label) onto my accumulated array, which is the cumulation of every previous iteration, starting with my initial `events` array. ## The final result  It was at this point I called it a day and was satisfied with my refactoring for code review I mentioned in the beginning. The final product looks like this: ```javascript const addEvents = (events, label, segment) => { if (!label) return events; return events.concat([[label, segment]]); }; const addUpcomingEvents = (events, upcoming) => { if (upcoming.length === 0) return events; return addEvents(events, 'upcoming stuff', upcoming); }; const getPastMonths = past => { return Object.keys(groupBy(past, date => moment(date).format('YYYY-MM'))).sort().reverse(); }; const addPastEvents = (events, past) => { if (past.length === 0) return events; return getPastMonths(past).reduce((acc, month, idx) => { return addEvents(acc, `${idx} months ago`, month), events); }; }; const main = () => { const [upcoming, past] = partition(arr, date => today.diff(date, 'day') <= 0); return addPastEvents(addUpcomingEvents([], upcoming), past); } ``` To summarize, the major things we covered in this refactoring are: 1. **Simplify functions down to a single responsibility** 2. **Eliminate side effects by using immutable functions and not modifying arguments** 3. **Ensure type safety by verifying all return statements provide the same type of object** This gives us code that is easier to read, less prone to bugs, and easier to test. Is there anything else you would refactor? Did I miss something? [Hit me up on Twitter](http://twitter.com/theadamconrad) and let me know what else could make this code better. ]]> 2018-06-14T21:13:00+00:00 https://www.adamconrad.dev/blog/if-youre-really-worried-about-the-github-acquisition-heres-what-to-look-out-for/ Mon, 04 Jun 2018 21:13:00 +0000 https://www.adamconrad.dev/blog/if-youre-really-worried-about-the-github-acquisition-heres-what-to-look-out-for/ You might have heard that at the end of last year we became a part of Microsoft, but our services are still provided under a separate Terms of Service. We’re excited about leveraging Microsoft technology and resources to offer more valuable features and services to you. And I've been on LinkedIn for the last 2 years. I'm neither frustrated nor thrilled. LinkedIn is just as much of a recruiter Zombieland as it has always been. You don't have to trust Microsoft when they say they don't want to change GitHub, but they are not offering any indication that they want to mess with it. # Myth: GitLab and Bitbucket are safer options The other issue I see is that if there is an unwavering hatred for Microsoft, that we must all leave for better pastures. The two biggest players in the space that are still independent are GitLab and Bitbucket. Are they _really_ all that much better than GitHub? ## They're all for-profit businesses The most remarkable thing to me in reading the public's reaction is that people make it seem like GitHub was an open source non-profit company. That because they were the premiere company to publish your open source code, it must mean they were pure in intentions. They're very much a for-profit and primarily make money off of storing private repositories. GitLab and Atlassian are no different! In fact, now that GitHub is part of Microsoft, they're a public company just like Atlassian. Even though the business models for each are somewhat different in how they make money off of the code storage, the fact is each of those companies is closed source, with specific legal terms to designate what is owned by the contributors, and what is owned by the storage company. And they're _all_ trying to make money (and there's nothing wrong with that). ## You can still deploy your code to mega-corps Even if you go with GitLab or Bitbucket, where are you going to deploy your code? Because unless you plan on buying your own servers and scaling like we did in the 90s and 2000s, you're going to use one of a few big players: 1. DigitalOcean. A company whose debt is mostly [financed by megabanks](https://www.crunchbase.com/organization/digitalocean#section-locked-charts) like HSBC and Barclays. 2. Heroku. A company now owned by Salesforce, a publicly traded company worth nearly $100BB. 3. Amazon Web Services. A company with a bigger market cap than Microsoft. 4. Azure. Which is owned by you know who... So even if you self-host your code for the sake of using git with your team, you're still handing over your code to another massive company when you go to turn the lights on for customers. And you may have already done that deed with Microsoft. ## Look at the terms The GitHub terms of service only mention open source [in section D.6](https://help.github.com/articles/github-terms-of-service/#d-user-generated-content): > This is widely accepted as the norm in the open-source community; it's commonly referred to by the shorthand "inbound=outbound". We're just making it explicit. This isn't even in the ownership section, which clearly states: > You retain ownership of and responsibility for Your Content...we need you to grant us — and other GitHub Users — certain legal permissions, listed in Sections D.4 — D.7. These license grants apply to Your Content. If you upload Content that already comes with a license granting GitHub the permissions we need to run our Service, no additional license is required. You understand that you will not receive any payment for any of the rights granted in Sections D.4 — D.7. The licenses you grant to us will end when you remove Your Content from our servers unless other Users have forked it. You can continue to read the rest of those sections, but the real key nugget that you're probably worried about is the legal permissions that apply to you: > We need the legal right to do things like host Your Content, publish it, and share it. You grant us and our legal successors the right to store, parse, and display Your Content, and make incidental copies as necessary to render the Website and provide the Service. This includes the right to do things like copy it to our database and make backups; show it to you and other users; parse it into a search index or otherwise analyze it on our servers; share it with other users; and perform it, in case Your Content is something like music or video. > > **This license does not grant GitHub the right to sell Your Content or otherwise distribute or use it outside of our provision of the Service.** The rest of those sections simply state that if you post public code it can be viewed by anyone, if you contribute to a repo it's bound to the repo's declared license, and when you upload code it comes with "moral rights," meaning you have the right to seek attribution and credit for the code you have published. So how does this compare to ownership and IP for GitLab and Atlassian? [For GitLab](https://about.gitlab.com/terms/#subscription): > 4.3 Customer and its licensors shall (and Customer hereby represents and warrants that they do) have and retain all right, title and interest (including, without limitation, sole ownership of) all software, information, content and data provided by or on behalf of Customer or made available or otherwise distributed through use of the Licensed Materials (“Content”) and the intellectual property rights with respect to that Content. And [for Atlassian](https://www.atlassian.com/legal/customer-agreement): > 7.4 Your Data. “Your Data” means any data, content, code, video, images or other materials of any type that you upload, submit or otherwise transmit to or through Hosted Services. You will retain all right, title and interest in and to Your Data in the form provided to Atlassian. Subject to the terms of this Agreement, you hereby grant to Atlassian a non-exclusive, worldwide, royalty-free right to (a) collect, use, copy, store, transmit, modify and create derivative works of Your Data, in each case solely to the extent necessary to provide the applicable Hosted Service to you and (b) for Hosted Services that enable you to share Your Data or interact with other people, to distribute and publicly perform and display Your Data as you (or your Authorized Users) direct or enable through the Hosted Service. Atlassian may also access your account or instance in order to respond to your support requests. **TL;DR: you own your code.** In fact, if there was one company in that three that I am worried about, it's Atlassian. **Atlassian can collect, copy, store, modify, and use your data.** This isn't spelled out with GitLab or GitHub. So don't think the alternatives are any better for you now that Microsoft owns GitHub. # Assuming it's all good, what can go wrong? So if you're convinced that you don't need to jump ship, the truth is things _could_ go wrong. Here are the things to look for when the deal ultimately goes through and the acquisition is 100% complete: 1. **Look out for a GitHub conversion announcement.** Just because they've announced an acquisition does not mean the services have completely rolled over to Microsoft. In fact, the current terms of service for GitHub are dated May 25th which is pre-announcement. If things change and either GitHub or Microsoft announces the rollover is complete, make sure to read the changes carefully. If they change their terms, they'll make you accept or reject the new terms. 2. **If they introduce new terms, see who owns them.** As I mentioned earlier in LinkedIn's conversion announcement, they stated that they still owned their own separate terms of service. This will likely be the case for GitHub as well. If that isn't the case, you'll have to read Microsoft's terms as well as GitHub's. Like class inheritance, whatever you read on GitHub is layered on top of what Microsoft is applying to their software licenses. 3. **If the terms change, specifically check Sections D.3-D.7 for change in ownership or rights.** That's the core section that deals with who owns and distributes the code. If this becomes more restrictive or unfavorable to your community, that would be a good time to re-evaluate your source code hosting strategy. Is this acquisition a big deal? Yes. Is it a bad deal for you? Probably not. Keep calm and code on, but if the terms change, read them carefully and re-evaluate if they are no longer favorable to your interests. ]]> 2018-06-04T21:13:00+00:00 https://www.adamconrad.dev/blog/how-to-improve-on-naming-contexts-in-domain-driven-design/ Wed, 30 May 2018 23:25:00 +0000 https://www.adamconrad.dev/blog/how-to-improve-on-naming-contexts-in-domain-driven-design/ How would I describe `Question` and `Answer` to a friend in one word? First of all, we can look at the description I gave in the beginning. In addition, we remember that contexts are nouns, so when I'm parsing those first descriptive sentences, I see words like **forum** and **site**. Another technique is to bring these models into reality. Where do you see Q&A in the real world? At tech talks, for example, it's usually at the end of a presentation where the speaker has a discussion with an audience. Using the noun technique in the previous sentence, potential context ideas are **presentation** and **discussion**. Now we can apply the domain-driven part of our design to ask ourselves: > What domain does this belong to, and are there any conflicts or ambiguities we need to worry about? For presentation, this belongs to the domain of things like public speaking and business. The problem is, presentations are also conflated with the MVP (Model-View-Presenter) pattern. It is also a specific format for PowerPoint. Given that this word has specific connotations with programming jargon, we can rule this one out. That leaves us with **discussion** and **forum** as our context for our Q&A models. Honestly, either will work here, but one hint is that forum relates more to this particular domain than discussion does, so I think we'll go with forum. Now we can repeat the process for `User` and `Organization`. Since these aren't on the same level, we could argue that they shouldn't be in the same context, but we have to give them _a_ context because there really isn't a point in making a 1-to-1 mapping of models to contexts for an application this small. But we also see a natural mapping here: people belong to organizations all of the time, whether it's a company or a volunteering outfit. How do we describe people in an organization? We say they're organized by some hierarchy and are usually grouped into teams or divisions. That gives me a few nouns: **hierarchy**, **grouping**, **team**, and **division**. I can already see that team and division are immediately out since that is an example of how organizations are split and don't fully encompass the user-organization relationship. Grouping is good, but the word *group* itself does creep a bit too close to computer terms such as `GROUP BY` or the C# `grouping` keyword. So I'll go with **hierarchy**.  Nice work! We have a clear designation between two contexts that make sense. One thing to point out is that **contexts can be renamed or changed later**. It's not important that we anticipate the use of these contexts as we add models. Sure, `Hierarchy` might limit our flexibility, as it could be a stretch to add in helper models like `Address` into this context, but you can worry about refactoring later. ### Example 2: Twitter Twitter is a microblogging service that allows people to express their thoughts in a very limited space. All messages (called "tweets") have a 280 character limit and are broadcast to followers. Followers can then interact with their connection's messages by liking or sharing (via "retweeting") content that they think is valuable to their own networks.  What did you come up with? Let's again apply the same heuristics from above to decide what our contexts will be. The first thing that stands out to me is the intimate tie between `User` and `Tweet`. It's the absolute core of this platform. Simplifying the noun technique, my first thought was that this _is_ the **microblog**. However, given that Twitter has increased its word count from 140 to 280 characters, I feel like the *micro* portion of this is basically irrelevant, but the **blog** portion aptly contextualizes this relationship. Plus, it's a natural context for future potential models like `Comment`. Next, there are the user-related interactions: following/followers is largely abstracted away since it's a `User` to `User` relationship. `Like` and `Share` are new models, and do have similar mechanisms that feel like they could be grouped. What did I just call these things? **Interaction**, that's one (in fact, I also used it in the opening paragraph). I also used **network** which would describe the following/follower relationship, but again, networking is computer jargon and that could collide with a lot of other concepts we are working with. I think **interaction** is a good one:  This one was a bit easier given our previous look, but again, I really want to stress that **there is no right answer**. All we are attempting to do here is make it easy for you to figure out the naming, but at the end of the day, there's no actual penalty in naming or grouping these however you like. In Phoenix, there is certainly some cost with talking between contexts, but it's not an insurmountable issue. ### Example 3: Google Drive Google Drive is a cloud file storage provider. You can access files from anywhere in the world on any device, provided you have a Google account. In addition to reading files, you can collaboratively write to files with other users who have permission to read (and write) these files. Further, you can collaborate via tools like comments and sticky notes to provide feedback even if you cannot directly write to the file. Google Drive does not provide universal file capabilities and is mainly focused on reading/writing for documents, spreadsheets, and slideshow presentations.  This one is a bit more complex. We have quite a few more models here with a bit more ambiguity for how we can split things up. Let's start with the easiest one that all exist on the same level: `Document`, `Spreadsheet`, and `Presentation`. How did I group those in the above description? I called them all **files**. Normally we'd red-flag this context because it's too computer-specific of a domain, but remember, this service is _very_ computer focused by its very nature, so it's actually okay that we give this a context like this. The next layer up we have our `IO` which handles permissions for file read and write access controls and `Comment` which is a special kind of write. Finally, we have the `User` at the very top, which touches everything. Now your gut might tell you that reading, writing, and commenting are **interactions** just like in the Twitter example. But we can't do that for a few reasons: 1. The methods for determining read and write access are encapsulated within `IO` - they are permission grants to unlock certain functionality, but `IO` in of itself is not an interaction 2. Remember, `User` has access to all of these models. Even though this UML diagram lays everything out in a hierarchy, it's not a simple three-tiered relationship, so in a way, we _interact_ with our files as well by virtue of owning them. Let's offer a different narrative. We mentioned earlier that we can collaborate with other users to perform actions. The noun here is **collaboration**. Additionally, those actions are governed by **permissions**. Which do we choose? This is probably the toughest one of all. Collaboration implies an innate connection with others, even though you can manipulate a file without any other users. Whereas permission makes sense with both user interaction and `IO` but seems to leave `Comment` out in the cold. The key clue we have is that **`Comment` is a subclass of `IO`, so we can lower the priority of making `Comment` work for our context**. In other words, since we know permission is a sensible context for both `User` and `IO`, it stands to reason that **permission** will be a good context name because `Comment` is a type of `IO` in this domain.  This provides lots of ability to expand with both file types and ways of handling things centered around the `User`, such as authorization and authentication. Both contexts also pretty cleanly separate the levels of hierarchy between data models. ## Wrapping up Let's summarize our heuristic into three simple steps: 1. **Map the domain.** We used UML diagrams to lay out the hierarchy of our models to provide visual clues for possible contexts. 2. **Horizontal or vertical alignment provides clues.** If something falls along the same plane or area of your diagram, you can bet it's a context. 3. **Describe that alignment in one word, preferring the noun with the more specific domain.** This is the hardest part, but the idea here is to take the description of our application and pick out the nouns (and sometimes verbs) that associate our related models. From there, we simply prune the word that has the clearest message with the least ambiguity. Naming contexts is hard. It can be made easier if you follow these guidelines the next time you write an application using domain-driven design. Make sure you don't stop with just your first iteration. Growing applications require consistent refinement. Sometimes you'll need to split off a context into multiple contexts, while other times you'll need to consolidate contexts. Don't be afraid to go in either direction. Finally, don't be afraid to be wrong, because there is no definitive right answer either. Good luck and happy naming! ]]> 2018-05-30T23:25:00+00:00 https://www.adamconrad.dev/blog/how-to-load-images-to-cut-page-time/ Thu, 24 May 2018 18:25:00 +0000 https://www.adamconrad.dev/blog/how-to-load-images-to-cut-page-time/ 0) { imageCount--; observer.unobserve(entry.target); preloadImage(entry.target); } } } var applyImage = function(img, src) { img.classList.add('js-lazy-image--handled'); img.src = src; } if (!('IntersectionObserver' in window)) { loadImagesImmediately(images); } else { observer = new IntersectionObserver(onIntersection, config); for (image in images) { var image = images[i]; if (image.classList.contains('js-lazy-image--handled')) { continue; } observer.observe(image); } } ## How it works This script works by looking for images that have the class **js-lazy-image**. Those images must have a data attribute called data-src which has the location of the image, just like the normal src attribute would be filled out. The script then counts the number of images with this class, and when the viewport intersects with an observable area that includes the image, the source of the image is loaded from it’s data attributes, and the image renders on the screen! Here’s an example of how you would call lazy loaded images: As you can see, this works almost exactly like a regular image, but you just need to make sure to add on the special JavaScript class and add a **data-** prefix in front of your src attribute. And that’s all it takes to go from this:  To this:  ## How the script works — section by section Still curious as to how the script works? Let’s break it down by section: var images = document.querySelectorAll('.js-lazy-image'); var config = { rootMargin: '50px 0px', threshold: 0.01 }; var imageCount = images.length; var observer; Here we initialize our variables. Remember that class we added to our images? This is where we collect our images. The configuration will be used later with our observer class (don’t worry if you don’t know what that is, we’ll get to that in a second). Finally, we store the image count because we’ll be using that a few times throughout our script. var fetchImage = function(url) { return new Promise(function(resolve, reject) { var image = new Image(); image.src = url; image.onload = resolve; image.onerror = reject; }); } Our first function deals with grabbing our images. We make use of [JavaScript Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) to asynchronously load our images. If the Promise was resolved successfully, we load the image with the URL for our image source, otherwise we display an error. So where is this called from? Glad you asked… var preloadImage = function(image) { var src = image.dataset.src; if (!src) { return; } return fetchImage(src).then(function(){ applyImage(image, src); }); } This image preload function grabs the image source from the data attribute we tacked onto our image tag. If it doesn’t find a source object, no problem, we just stop right there. Otherwise, we fetch our image, and if things go great, we apply the image to the DOM like so: var applyImage = function(img, src) { img.classList.add('js-lazy-image--handled'); img.src = src; } Our function simply finds the image we’re about to reveal, adds on a class to let our script know it has been handled, and then adds the URL to the image’s src attribute. if (!('IntersectionObserver' in window)) { loadImagesImmediately(images); } else { observer = new IntersectionObserver(onIntersection, config); for (image in images) { var image = images[i]; if (image.classList.contains('js-lazy-image--handled')) { continue; } observer.observe(image); } } This is the meat-and-potatoes of our script. The core functionality that enables our lazy loading to happen quickly and efficiently revolves around the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API). This API allows us to track changes to the viewport against target elements asynchronously. Traditionally you would have to do something like this with the [Scroll Event](https://developer.mozilla.org/en-US/docs/Web/Events/scroll) which is both slow and called constantly. To combat this performance hiccup, you might using [debouncing or throttling](https://css-tricks.com/debouncing-throttling-explained-examples/) to limit the number of scroll event requests. But with Intersection Observers, this is all handled for you. Remember the config variable at the top of our script? This is the configuration for our Intersection Observer. It tells us that when we are within a margin of 50px (vertically) from our image, that is when we want to activate our observation callback. The threshold, as you might guess, is the tolerance for what percentage of the object must be observed in order for the callback to be invoked once the margin is reached. In our case, we chose 1%, which is immediately upon bringing the image tag into view. So now that we have that background, we can see how this if statement works. If we see that Intersection Observers are a part of the window object, we know we are in a browser that supports this functionality. As of right now, [Intersection Observers are available on all major browser except IE and Safari](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#Browser_compatibility). So if you are on IE or Safari, you will load the images immediately. If you aren’t, we create a new Intersection Observer object with the configuration we provided in the beginning, as well as a callback function to trigger when our target observation is reached. Finally, we have to tell the Observer exactly what it has to observe for the callback to be initialized. In this case, we are observing all of the images that haven’t already been handled, which are the images that haven’t been applied to the DOM yet (via the applyImages function we saw earlier). So what does loading images and the observation callback look like? var loadImagesImmediately = function(images) { for (image in images) { preloadImage(image); } } For loading images immediately, it’s pretty straightforward. We simply preload all of the images and put them on the screen like we normally would. var onIntersection = function(entries) { if (imageCount === 0) { observer.disconnect(); } for (entry in entries) { if (entry.intersectionRatio > 0) { imageCount--; observer.unobserve(entry.target); preloadImage(entry.target); } } } Our intersection callback is a bit more involved. If we have loaded all of our images that have our lazy loading CSS class, we’re done and we can disconnect from our Observer object. Otherwise, for every observer entry in our IntersectionObserver, we want to activate our images. We do that by ensuring we have reached our threshold. **intersectionRatio** is the property we need to see if our target image element is visible within the threshold we defined in our configuration. If it is, the property returns a 1, otherwise it returns a 0. So if we have landed within our necessary ratio, we have one more image to add to the DOM, which means we can remove 1 from our count of images remaining to load. We can therefore stop observing this image because it’s going to be loaded onto the page. Finally, we use our previously-defined preloadImage to execute our now familiar process of adding the image URL onto the image tag and loading the image into the DOM. ## Next steps **Lazy loading images is a quick and painless way to drastically improve the performance of your pages that use a lot of imagery.** From there, be sure to [compress your images](https://adamconrad.dev/the-fastest-way-to-increase-your-sites-performance-now/) and use the correct image format so you keep a small footprint. Tools like [MachMetrics](https://www.machmetrics.com/) are a great way to track your performance improvements over time, as well as provide additional suggestions on how to continuously improve the performance of your application. What other quick wins do you have for speeding up your site? Leave a reply in the comments below! *Originally published at [www.machmetrics.com](https://www.machmetrics.com/speed-blog/how-to-lazy-loading-images-script-slash-page-load-time/) on May 24, 2018.* ]]> 2018-05-24T18:25:00+00:00 https://www.adamconrad.dev/blog/here-is-the-full-list-of-my-50-remote-job-sites/ Tue, 15 May 2018 23:25:00 +0000 https://www.adamconrad.dev/blog/here-is-the-full-list-of-my-50-remote-job-sites/ 2018-05-15T23:25:00+00:00 https://www.adamconrad.dev/blog/the-fastest-way-to-increase-your-sites-performance-now/ Wed, 25 Apr 2018 04:25:00 +0000 https://www.adamconrad.dev/blog/the-fastest-way-to-increase-your-sites-performance-now/ At this point, you've already exhausted even the most advanced compression optimization techniques. And while these programs do all of the work for you in a matter of seconds, the truth is you may need to scrap your images altogether if they are in the wrong image format. How do you know if they're in the right format? Follow this simple questionnaire and then save your image into the new file format (and then repeat levels 1 and 2 to compress your new images!). #### Does it look like a photograph? Use a JPG JPGs were meant to be used with photographs. If you have avatars of your team, photographs of your office, or other real-life images, make sure they are in the JPG format. #### Does it look like a computer-generated graphic or drawing? Use a PNG Everything else can be a PNG. Other formats may provide better quality, but if you're serving a web or image application, a PNG will do and is universally read by every kind of application. The one exception to this would be icons... #### Does it look like an icon? Use an SVG Icons are also computer-generated, but the difference is that icons are generally used alongside typography. If you think the image will be used in a menu, on a button, or is meant to symbolize something, it's probably an icon, and icons will benefit from being SVGs because they can be scaled along with your type and lose 0 fidelity. They will look just as crisp as your fonts and will be much smaller as SVGs as well. #### Are you supporting the latest browsers and don't care about Firefox? Use WebP, JPEG 2000, and JPEG XR Finally, there is a push for next-generation image formats. JPG and PNG have been around for more than two decades, and it's about time we have some new formats that innovate to maintain image quality without bloating our applications. Even better, they don't require you decide between image type. For example, WebP works great for both photographs and computer-generated images. The downside is that support is fragmented across devices and browsers. [WebP](https://developers.google.com/speed/webp/) was made by Google, so it's naturally designed only for Chrome and Chrome mobile. JPG also has evolved formats, but [JPEG2000](https://jpeg.org/jpeg2000/index.html) is only supported by Apple (Safari and Safari Mobile), while [JPEG XR](https://jpeg.org/jpegxr/index.html) is only supported by Microsoft (IE and IE Edge). What about Firefox? There is no next-gen format for this browser, but they do have a [2-year-old bug ticket](https://bugzilla.mozilla.org/show_bug.cgi?id=1294490) to implement WebP and it is assigned, but who knows when this will land. ### Level 4: Source sets & fallbacks If you've chosen the correct image and you've compressed the heck out of it, you'll want to make sure it's being served on the right device in the right aspect ratio. I alluded to this back in Level 2, but if you have concerns about Retina displays like MacBook Pros, or even x3 quality for the newest iPhones, you'll want to ake multiple copies of your image in all of these formats. Going back to the previous example, if you serve avatars in a 64x64 JPG format, you'll also want to make copies of dimension 128x128 for Retina _and_ 192x192 for Retina x3. The best way to do this is to **start with a larger image and scale down, rather than scale up**. You know those crime dramas where they ask the hacker to "_Zoom! Enhance!_"? We all know that doesn't work in real life, and that same thing holds true for your images - you can't add clarity where there was none in the first place. Instead, start with the original source image (say, 512x512) and scale down to 192, save a copy, then 128, save another copy, then 64, and save that last copy. This will result in a less blurry, albeit still lossy (because you are removing information in the form of pixel fidelity) set of images. With all of these duplicate, scaled images, how do we tie this all together? The image attribute known as `srcset` comes to the rescue: ``` ``` `Srcset` is pretty amazing. It will always default to the original `1x` magnifier like a normal image tag would. However, if it does find the other images, it will apply them to the given aspect ratios for your device. In other words, if you are viewing the photo on a 2015 MacBook Pro, the browser will select `avatar-md.jpg`, but if you are on an iPhone X, it will select `avatar-lg.jpg`. And if you're in a military bunker using IE8, it will fall back to `avatar-sm.jpg`. `Sizes` is another property for responsive images but it relies on the width of the device rather than the pixel density. The format is the same: ``` ``` You specify an image, space, the size the image should be displayed, with a `w` descriptor for the `srcset`, and then, using the `sizes` attribute, specify the media queries at which point the various sources should be used. The only downside? **`Srcset` is not supported in IE**. It _is_ supported in IE Edge, and the `sizes` attribute is supported everywhere. In my honest opinion, this isn't something to worry about because all of the Retina devices using IE are already new enough to support IE Edge. Anything that still requires IE11 and down likely doesn't have a Retina display anyway (unless it is connected to an hi-density external monitor) so you likely won't run into this problem being a real blocker for you. ## Something is better than nothing This is not an exhaustive list of image optimization techniques nor is it meant to be a prescriptive formula. **Even if you only run ImageOptim on all of your images in your application, you could be saving upwards of 60-80% of what your users have to download.** Images, audio, and video, _not_ your source code, will comprise the largest space for your application by far. Effectively choosing, compressing, and displaying your images will have a marked impact on both application size and performance for your end user experience. The best part is it only takes a few downloads and a few more seconds to run your images through a very easy set of tools that will provide an instant improvement without sacrificing quality. ]]> 2018-04-25T04:25:00+00:00 2022-03-29T14:01:00+00:00