DEV Community: Drew Town

5 Tips For Asking Better Technical Questions And Getting Faster Answers

Drew Town — Wed, 20 May 2020 16:41:15 +0000

Read more of my articles on drewtown.dev or follow me on Twitter 🐤

After 12 years of working professionally in systems administration and development I have learned some helpful ways of asking technical or development questions that will get you better answers, faster.

When asking a question most of the time you are looking for an answer, unless you are waxing philosophically. So, set yourself and the person you are posing the question up for success. Or, as the venerable Dr. Cox would say, "help me, help you.”

Set The Tone

No matter who it is, if it is the first time today you are talking to this person, start with a greeting. Simply starting your conversation with, "Hey Susan, how are you today?” Always keep in mind that this person will be taking time out of their day to help you with your problem. So, treat them with empathy, professional courtesy, and be friendly out of the gate.

Opening with your question or hitting them with a wall of text before saying hello is a surefire way to make sure this person won't be starting off on the right foot.

Provide Context

Assume the person you are asking your question to has absolutely no context about what you are asking them about. This is by far the most common mistake I see when people are asking questions.

When you are deep into a problem, you have built up a lot of mental models and context about the current situation. So, when you ask "How do I fix this?" to a colleague they do not understand that you are working on a problem regarding slow network latency between the app server and the Redis server in the staging environment.

When you are posing your questions you must help the person you are asking of the question of quickly build up the necessary context to help you.

Being able to provide this information is a skill that must be practiced. Before you hit send in your chat app look at your message and ask yourself, if someone sent me this message would I even know what they are talking about? Would I be able to solve this problem with the information I provided?

Save yourself time by thinking ahead to the information they will need to help you solve the problem.

Don't Bury The Lede

So far we have discussed setting the tone and providing relevant context, but it is also important to not surround your question with useless details. Don't whine, or try to stir up sympathy by providing a long unnecessary story.

Your question should only include relevant details, necessary background and the actual question you are seeking an answer to. Don't make the person try to find your question in a wall of text or interpret your story as a question.

Don't Propose Solutions, Tell Them What You Want To Do

When asking a question it is best not to propose a solution as a question. When you propose a solution to your own question, you are limiting the scope of thought to your solution rather than allowing alternative solutions.

Instead of saying, “How can I cache my query in the database?” Ask, “I working on a slow query that is causing pages to load slow. How can I speed this up my page?” Maybe the solution is to better tune database caching. But the conversation might instead flow to storing full page caches in Varnish, or using a CDN, or questioning the query, or studying the indices in the database.

When you propose a solution as a specific question you limit the potential solutions. Instead, ask your question as something you are trying to do.

Show Your Homework

Always take the time to discuss potential solutions you have already tried. When you do this, you eliminate potential solutions that you've already tried but haven't panned out. Also, you show the person you are asking that you've put a bit of time and effort into the issue.

You don't need to put an excessive amount of detail into this. But just showing that you tried a solution may eliminate potential solutions or help the other person better direct their thoughts.

Display External User Avatars Using Strapi's Custom Routes as a Proxy

Drew Town — Thu, 14 May 2020 16:41:00 +0000

When using Strapi you may run across a scenario where you need to return data not stored in Strapi's database. Suppose you need to fetch a social media user avatar, a stock quote, or other data available from a third party API. We will use Strapi as a proxy to request the data and return the information to the client app, avoiding any potential CORS problems.

While we will be using a user avatar as an example, the implementation presented in this article will also be application to any data that needs to be requested via a third-party API.

When registering a user on another one of my sites, picke.rs, I wanted to give the user an option to use an avatar they had registered with another service as their picke.rs avatar without requiring the user to find and upload an image from their device. We can use their email address and the unavatar service to try and locate a social image for the user.

Why Custom?

You may have noticed the Strapi guide about fetching external data. If your data does not need to be real-time or stored in Strapi's database, that will be a better route to follow.

In this example we want the results to be real-time and requested only when necessary. Therefore, we have no need of a model to store the data in the database and we can simplify the structure presented in Strapi guide.

Creating The Route

Create the file api/avatar/config/routes.json in your Strapi project. You will need to create the avatar and config folders within the api folder.

{
    "routes": [
      {
        "method": "GET",
        "path": "/avatars/:id",
        "handler": "avatar.find",
        "config": {
          "policies": []
        }
      }
    ]
}

This route defines the HTTP method, the path, and which method will handle the request.

The path has a dynamic id defined which will be passed to the handling method via the ctx. We'll use the id set via the url submitted by the user in order to query the API.

Handle The Request

Create the file api/avatar/controllers/avatar.js in your Strapi project. This is where we will create the find method.

const axios = require("axios");

module.exports = {
  /**
   * Retrieve a user avatar.
   *
   * @return {String}
   */

  async find(ctx) {
    if (ctx.params.id.length < 4 || !ctx.params.id.includes("@") || !ctx.params.id.includes(".")) {
      return ctx.badRequest("Invalid email address");
    }

    const { data } = await axios.get(`https://unavatar.now.sh/${ctx.params.id}?json`);
    if (data.url.includes("fallback")) {
      return ctx.send({ url: null });
    }

    return ctx.send(data);
  },
};

In this method we provide some very basic validation to return early if the requested email address does not appear it could be an email address.

Next, we use Axios (you can use any method or library of your choice to make the API request) to make a request to unavatar which is a handy little service to query for avatars across multiple social media networks.

For this case, if unavatar cannot find a social media avatar for the supplied email address, we return null instead of the fallback image. If you'd prefer to use the unavatar provided fallback, then return the returned data without the fallback check.

The ctx parameter is injected by Strapi and it is what contains information about the request such as the route ID we defined in the routes.json file

Updating The Roles & Permissions

When the route and method have been created and the Strapi server is restarted Strapi will add the new find method to the available permissions in the admin's Roles & Permissions section. We'll want to enable this for all the necessary available roles. If only unauthenticated users will call this method, then only enable it for public if other roles will call this method then enable it for those roles as well.

Calling From The Client

Now in our client we can call the route /avatars/me@example.com in a Vue application the method would look something similar to the following.

methods: {    
    async downloadAvatar () {
      if (this.login.length < 4) {
        this.avatarLink = null
        this.useAvatar = false
        return
      }
      const { data } = await this.$axios.get(`/avatars/${this.login}`)
      this.avatarLink = data.url
      if (data.url !== null) {
        this.useAvatar = true
      }
    }
}

Using Strapi Policies To Create Editable User Profiles

Drew Town — Tue, 05 May 2020 13:18:41 +0000

Strapi's roles & permissions plugin will get you a long way in registering, sign-in and managing users in your application. Unfortunately, Strapi does not provide a built-in strategy for allowing users to manage their own personal information via a user profile, instead leaving those decisions to you, the developer.

We will use Strapi's policy customizations to extend the Strapi API. The policy will allow authenticated users to update their user profile in a secure manner.

Extending The User Content-Type

Display names, subscription status, and user image are a few examples of the information we may want to allow the user to edit. In contrast, we will exclude e-mail address, role and other sensitive fields from user editing. In this example we will tackle, display name and if they subscribe to the weekly newsletter.

Using Strapi's "Content-Types Builder" select the User collection type. Select "Add another field", choose Text and give it a name of displayName. Next, add another field and this time choose Boolean and give it a name of newsletter.

Implementing The Policy

Create the file extensions/users-permissions/config/policies/userUpdate.js in your Strapi project. This file is where we will define the policy that Strapi will utilize when it receives a PUT request to the route /users.

module.exports = async (ctx, next) => {
  // If the user is an administrator we allow them to perform this action unrestricted
  if (ctx.state.user.role.name === "Administrator") {
    return next();
  }

  const { id: currentUserId } = ctx.state.user;
  // If you are using MongoDB do not parse the id to an int!
  const userToUpdate = Number.parseInt(ctx.params.id, 10);

  if (currentUserId !== userToUpdate) {
    return ctx.unauthorized("Unable to edit this user ID");
  }

  // Extract the fields regular users should be able to edit
  const { displayName, newsletter } = ctx.request.body;

  // Provide custom validation policy here
  if (displayName && displayName.trim() === "") {
    return ctx.badRequest("Display name is required");
  }

  // Setup the update object
  const updateData = {
    displayName,
    newsletter
  };

  // remove properties from the update object that are undefined (not submitted by the user in the PUT request)
  Object.keys(updateData).forEach((key) => updateData[key] === undefined && delete updateData[key]);
  if(Object.keys(updateData).length === 0) {
    return ctx.badRequest("No data submitted")
  }

  ctx.request.body = updateData;
  return next();
};

Later on we will dig deeper into what each part of this policy is doing. But for now, let's continue setting up Strapi to use this new policy.

Setting Permissions in the Strapi Admin

Verify that an authenticated user has access to the me and update actions via the roles & permissions plugin in the admin under the user permissions section. When checking the update option select our newly create userUpdate policy in the advanced settings. By selecting the policy from the policy select dropdown we'll ensure that each request made is checked by the policy before the controller receives the request.

Selecting these actions will allow a user to to make GET requests to /users/me and PUT requests to /users.

Note: Authenticated, in this case, means that we sent the request with an authorization header that includes a valid bearer token returned by the login route.

const res = await axios.get('http://localhost:1337/users/me', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
})

Retrieving The Current User

The roles & permissions plugin includes a route /users/me that allows an authenticated user to retrieve information about themselves. If you are using a front-end with store such as Vuex or Redux, you may already have this information handy in your front-end application. We will use the data from this route in order to pre-populate our form fields for editing.

Creating and submitting a form on your client application is outside the scope of this article.

Now that we've verified we can access information about the authenticated user, we can allow a user to change some information about themselves using a PUT request to the update route that utilizes our new policy. Let's take a closer look at what this policy does.

Digging Deeper Into The Policy

Let's break this policy into a few chunks to analyze what it is doing.

Parse The Request Data

First, we verify who the user is, whether they are an admin, or they are a regular user trying to edit their own information.

  // If the user is an administrator we allow them to perform this action unrestricted
  if (ctx.state.user.role.name === "Administrator") {
    return next();
  }

  const { id: currentUserId } = ctx.state.user;
  // If you are using MongoDB do not parse the id to an int!
  const userToUpdate = Number.parseInt(ctx.params.id, 10);

  if (currentUserId !== userToUpdate) {
    return ctx.unauthorized("Unable to edit this user ID");
  }

If the user is an administrator, let the request go through as we assume they have all the permissions to perform any action on any user.

We are using object destructing to extract the authenticated user's id from the Strapi context and the ID parameter from the URL parameters. The ctx (context) variable passed into the policy is provide by the Roles & Permissions plugin and will include information about the currently authenticated user such as the id\ we are extracting.

If you are using MongoDB do not parse the ID to an int. MongoDB uses a UID user ID pattern.

Since we are using the plugin's existing controller, it is expecting a URL parameter for the user we are editing. Meaning a put request will need to go to the route /users/1 or /users/23 depending on the user being updated. Therefore, we need to verify the user is editing their own user information and not another user's information.

Extract The Data

  // Extract the fields regular users should be able to edit
  const { displayName, newsletter } = ctx.request.body;

Next, we extract the displayName and newsletter from the request body that the user submitted.

It is important to not blindly accept all parameters from the user as they could maliciously include additional fields such as role and elevate themselves to admin privileges.

Validation

  // Provide custom validation policy here
  if (displayName && displayName.trim() === "") {
    return ctx.badRequest("Display name is required");
  }

Within the policy is an excellent time to perform any additional validation. Even though Strapi has some validation built-in, such as string and boolean fields must match their respective types, you may not want to let users to have a display name of "Admin" or a series of spaces for example. In the policy you can perform your own simple validation or pull in a validation library of your choice.

Massage The Update Data

  const updateData = {
    displayName,
    newsletter
  };

  // remove properties from the update object that are undefined (not submitted by the user in the PUT request)
  Object.keys(updateData).forEach((key) => updateData[key] === undefined && delete updateData[key]);
  if(Object.keys(updateData).length === 0) {
    return ctx.badRequest("No data submitted")
  }

  ctx.request.body = updateData;
  return next();

We setup the updateData variable using ES2015 object property shorthand. Our variable names submitted by the user's request match the names we setup in the Strapi content builder so we can quickly initialize the update object. If your names don't match, you will need to use the standard object assignment.

Filter out any values that are undefined (not included in the PUT request), and if the user did not submit any valid data, we can short-circuit and return a badRequest letting the user know.

Finally, replace the ctx.request.body with our sanitized updateData and return next() to let Strapi know the request has passed the policy test and the controller can proceed.

Sending a request from the client

We've now allowed authenticated users to request data about themselves and send an update request with a policy applied to the request. When you are ready to send a request from the client, you can send an update like the following example using Axios.

const res = await axios.put('http://localhost:1337/users/1',
{
  displayName: "John Smith",
  newsletter: true
},
{
  headers: {
    Authorization: `Bearer ${token}`,
  },
})

Introducing Picke.rs - A Podcast Picks Explorer and Manager

Drew Town — Fri, 03 Apr 2020 14:36:27 +0000

Picke.rs was born out of an idea I had when listening to a few podcasts. That section at the end where they talk about things they like or “picks.” Often I would hear something that sounded cool; a new podcast, some interesting article or a backpack which I can never seem to find one I like. But I, like I’m sure many others, listen to podcasts mainly on the go.

I often would forget about what I just heard or even where I heard it. A place where I can see all the recent picks, picks by podcast, or even the individual who made the pick would help me better track those cool and interesting things they were talking about.

Thus, Picke.rs was born.

Back-end

I decided to not write my back-end for this project and instead try one of the many headless CMSs available today. I chose Strapi for the task. While still a young project it is progressing rapidly, has a well thought out admin portal, everything is extensible, and the documentation is thorough and complete.

Another aspect I liked about Strapi is that it is self hosted. While this might be a drawback for some. The hosting options are straightforward with one-click deployments for Digital Ocean, Heroku and others. The self-hosted option helps me keep costs down without adding too much of a burden.

Am I glad I used a pre-built CMS instead of writing my own? You bet! I could have written the same thing in Rails, ASP.NET, Laravel or any other framework, but for what? Instead of worrying about writing my own models, controllers, authentication and everything else that a flexible CMS gives me for free out of the box.

Getting The Data

Getting the data has been the hardest part of this project. Some podcasts use JSON to structure their episode data 🎉. Some podcasts use very structured markdown, which is ok. While still podcasts use very laissez-faire markdown, that changes frequently.

I’m use a Node.js script that fetches and parses the data that is specific to each podcast. Because the format of episodes is different, I’ve found it more helpful to build a set of utilities and helpers that can be utilized in to each individual scraper.

If you have a podcast that you would like featured on the site help me, help you. Provide clean, consistent JSON or markdown. It should be easily available and include the name of the picker, their Twitter handle if they have one, the name of the pick and a URL.

If this interests you, get in contact with me, and we’ll chat.

Front-end 💻

For the front-end I used Nuxt.js. Before this project, I had always been hesitant to use Nuxt. A framework sitting on top of a framework with extra conventions always felt redundant to me. I shook off my preconceived notions and tried it for this project.

So far the experience has been great. Everything has a place, server-side rendering (SSR) works wonderfully and the module system is very help for getting up and running quickly.

That’s not to say it isn’t without its quirks. The error messages can be frustratingly obtuse. On occasion there is an error that messes up SSR and the error message "Mismatching childNodes vs. VNodes” will leave you crawling through your code trying to figure out what went wrong.

Style System

If you have read any of my previous articles, you know I am a big TailwindCSS fan. Sensible defaults, built-in style system, perfect for a component based front-end.

Images

For each of the picks I am using Puppeteer to capture a screenshot of the page. In order to more easily process and serve the images in various formats and sizes I am using Cloudinary (referral link). Strapi has a Cloudinary provider to upload the images via the CMS and serving them as the necessary size is as easy as change a URL parameter.

CDN

For the rest of my CDN needs, I am using Cloudflare. It is free, convenient and ubiquitous. There isn’t much more I can say about Cloudflare that hasn’t already been said.

What do you like about Laravel?

Drew Town — Thu, 27 Feb 2020 18:05:39 +0000

I moved away from PHP frameworks years ago and missed the whole rise of the now very popular Laravel framework.

If you use Laravel what do you find most compelling about it? Community? Ecosystem? Other? Why Laravel over Rails, Keystone (or other based on Express), ASP.NET Core or others?

I tried asking on Twitter earlier but didn't get a response so I'm hoping the DEV community can give me their thoughts.

I wrote a Thank You Page and You Should Too

Drew Town — Mon, 06 Jan 2020 13:16:25 +0000

The number of personal blogs has skyrocketed in the last few years. Just a few years ago, Medium, Tumblr, Blogger, or Wordpress were the go-to blogging platforms. They were easy for anyone to pick up but frequently came with a few serious drawbacks. In 2018 or 2019 we saw personal blogs get a breath of fresh air. Everybody was setting up their own self-hosted blog and in many cases migrating existing content off of the popular blogging platforms. There are a few reasons that come to mind why this is the case.

Owning your own content has proven incredibly valuable. Medium and other blogging services that create paywalls are frustrating to readers and create ambiguity about who owns that data. There are a few high-profile blogs, such as FreeCodeCamp, that have removed their content from a slow, reader-hostile platform and relaunched on their own platform. When you control the content and the experience, you can create your blog the best way for the writers and the readers.

Another force driving the personal blogging scene is just how much easier it is to create a personal blog because of all the hard work put in by the open-source community and the services that support them. What previously would have meant spinning up a LAMP stack on a virtual private server is now taken care of by pushing a Markdown file to a git repo which runs a webhook to tell Netlify to trigger a fresh build and redeploy static HTML, CSS and JS to a CDN. They give this workflow to you and what it requires is gluing some software together that already plays well together.

So to all the library authors and service providers that make this blog and many more like it possible…

I originally got this idea from Nick Taylor who created a great Thanks page on his personal blog. And like all great developers I borrowed his idea for myself.

It’s not required, no one expects it, but it is a nice gesture to acknowledge the hard work done to make all developers’ lives easier.

Thank you!

Writing Better Technical Documentation

Drew Town — Mon, 16 Dec 2019 13:23:10 +0000

Find this post and more like it on drewtown.dev or follow me on Twitter

Writing technical documentation for a project is a task that everyone agrees is a good idea but often is skipped over for more exciting work. Or, if it gets completed, it is often of poor quality and rarely gets updated. There is a way to fix these problems though; write clear, concise documentation that removes all the prose and gets to the point in clear and defined language.

Oddly enough, some of the best technical documentation I’ve run across comes from board game rulebooks. Let’s take some time to look at how Ticket To Ride lays out an entire set of rules in 4 pages of text.

Purpose and Objective

A common part of technical writing I see that is often missing is the overall aim and purpose of the document. A blurb or paragraph that defines what the document is attempting to accomplish is critical in preserving the context in which the author wrote the document.

The purpose or objective is your introduction to the user and setting up the context so they know what they will read about. Depending on the context of the document, this may be the reasoning behind a policy or a quick introduction to the topic.

The object of the game is to score the highest number of total points. Points can be scored by:[…]

For a game rule book, the objective will guide the users and set up the context for all the other rules. Without providing an objective the other rules may lack clarity of meaning if the reader doesn’t know what they are working towards.

For a technical document, let’s look at GitLab’s password policy. We can see what the authors were trying to accomplish when they laid out this document: Secure passwords that follow defined recommendations.

Passwords are one of the primary mechanisms that protect GitLab information systems and other resources from unauthorized use. Constructing secure passwords and ensuring proper password management is essential. GitLab's password guidelines are based, in part, on the recommendations by NIST 800-63B. To learn what makes a password truly secure, read this article or watch this conference presentation on password strength.

Not every document will need such a verbose purpose statement. Adjust the introduction to your article to define the required background for the document and prepare your users and your future self with the necessary context to know why the document was written how it was.

Defining language

One of the most important parts of writing a technical doc is to use clear, unambiguous language that cannot leave the reader wondering about the meaning. Defined in 1997, RFC2119 has been used to provide clear, purposeful language for IETF documents and we can use the same concepts for other types of writing.
Words such as must, should, and may as outlined in the RFC leave no room for interpretation.

On his turn, a player must perform one (and only one) of the following three actions.

Each player must take a turn when it is their turn. There is no ambiguity. The rule leaves no room for questioning.

The player draws 3 Destination Tickets from the top of the deck. He must keep at least one of them, but he may keep two or all three if he chooses.

Again, the rule is explicit. Any player of this game will know what they must do and what they may do based on these rules.

When the deck is exhausted, the discards are reshuffled into a new draw pile deck. The cards should be shuffled thoroughly, since all the cards have been discarded in sets.

Finally, the word should can provide recommendations. There is no requirement to do it, but you will want to.

We should apply similar patterns to all technical documentation. Must, may and should and their opposites must not, may not and should not are the best way I’ve found to convey clarity, intent and purpose from me the writer to you the reader of my technical documentation.

Keep It Short

I haven’t met many people who love to write technical documentation and even less that enjoy reading it. Keep the prose to a minimum and focus on providing important information in as compact a format as possible.

Writing long paragraphs or providing extraneous information will derail the readers. If you even get the thing written…

Organize The Document

Hierarchical organization of documentation, like HTML, provides a natural outline for writers and readers. Headers, sub-headers, and sections make it easier for readers to find relevant information.

Don’t make your users read huge walls of text to find the information they need. Lay out the document into clear, logical sections that are easy to scan and read.

Read Good Documentation

As I mentioned in introducing this article, board games are often great examples of technical writing. So grab your favorite board game, take out the rule back and study.

Alternatively, there is no shame in stealing the format or techniques of another project’s documentation either. Vue.js and Redis are both respected for their documentation but have different styles and tones. Choose a project where you like the documentation and use that as a guide for writing your own documentation.

Use a Writing Aid

If writing isn’t your strong suit, or even if it is, a writing tool can easily improve the overall clarity, structure and grammar of your documentation.

My favorite tool is ProWritingAid (referral link) for writing help. Other free tools exist as well, such as Hemingway Editor, Grammarly, Grammar Lookup and LanguageTool just to name a few.

Get feedback

It is extremely difficult to write documentation in a vacuum. We should consult users of different levels and abilities who are using the documentation to understand their clarity and understanding of our writing.

Often I will write documentation that is clear to me but skips steps or makes assumptions that would not be clear to a person coming into a project cold. Finding someone who does not have all the built-up context around what you are writing about is crucial to make sure your document is understandable by everyone.

Explain Like I'm Five (ELI5) Vuex

Drew Town — Fri, 25 Oct 2019 16:28:01 +0000

A question that I see come up from new users to Vue is, “What is Vuex?” Or, “Can someone ELI5 (explain like I’m five) what Vuex is?” and usually the response is something like “Vuex is a flux pattern for storing and retrieving data from a centralized global object store”. While technically correct, this answer always leaves me scratching my head and wondering what five-year-olds this person is hanging around? When I was five, I was more excited by Tonka trucks or playing soccer than learning about programming patterns.

When this question came up on Reddit, I spent some time to figure out about how I could explain Vuex to a five-year-old. An answer without the jargon and straight to the point. I feel a good analogy for Vuex is a vending machine.
If you’ve ever used a vending machine, you know that a user can buy items using buttons. The machine also needs to be stocked; someone needs to deliver those goods to the machine, and it needs a mechanism to get the user’s choice into their hands.

Let’s go over the different Vuex concepts and see how we can best relate them to the vending machine.

State

The Vuex concept of state is fundamentally what is in stock at the vending machine. This might be anything for chips to cookies to strings. Or even integers, arrays, or objects.

Vending machines can seemingly carry any number of items under the sun the same holds true for Vuex. Vuex can hold any JavaScript type. Keep in mind though that Vue’s reactivity caveats also hold true for Vuex.

Getters

Getters are how you access the contents of the vending machines. If you would like to buy the cookies, you insert your money and punch the buttons to get your item.

In Vuex getters are more powerful than simple vending machine buttons. Instead of getting back one item, you could select only the chocolate chip cookies. It would be possible to combine various pieces of your state to create something that didn’t even exist before.

Getters are a powerful way to shape your data to retrieve only items you want or to build new items from the data that exists in state.
If you are familiar with Vue’s computed properties, they are comparable to Vuex’s getters.

Mutations

When a vending machine is new or getting low, someone needs to come around a stock it full of goods. Mutations are how we fill up our Vuex vending machine.

When we receive our Vuex vending machine, we don’t want to change the contents as that may break Vue’s reactivity. You should make sure all of your fields, or items for sale, are set up ahead of time.

Actions

Sometimes when you go to fill your vending machine, you may not have all the items you need. Instead of leaving the vending machine to go get more items to fill it up, you call a friend (async request) to retrieve the items and bring them to you.

Once your friend arrives with the goods, you can now fill the vending machine with a mutation.

You can find this post and many more over on my personal blog drewtown.dev or consider following me on Twitter

Favorite Git Interactive Tutorials or Videos?

Drew Town — Mon, 21 Oct 2019 19:10:58 +0000

I'm looking for some well done interactive git tutorials or video series for a co-worker. Does anyone have any they particularly liked?

Improve Blog Post SEO with Gridsome and Vue Meta

Drew Town — Sat, 05 Oct 2019 06:05:39 +0000

Gridsome generously includes Vue Meta which has become the de-facto standard for updating the <head> tag in Vue projects. Combining the power of Vue Meta with various aspects of the Gridsome GraphQL API we can create relevant page titles, descriptions and create rich social media cards for blog posts that use Gridsome.

Getting started

As long as you have a working Gridsome site there is nothing you have to do to get started! From any of your Gridsome pages or templates

Adding meta info to pages

As Gridsome's pages are generally static we can use the basic Vue Meta syntax to add a title. In our site's pages/Index.vue we can add a metaInfo object in our JavaScript.

export default {
  metaInfo: {
    title: "Hello, world!"
  }
}

Now when we visit the home page of our blog we will see the tile of our tab has changed to Hello, world! - Drew Town Dev. By default, Gridsome will append your site's name from gridsome.config.js file using the siteName value.

module.exports = {
  siteName: "Drew Town Dev",
  // ...other config
}

It is possible to override this by setting Vue Meta's titleTemplate property which could be set in your Layout Default.vue if you prefer a different title template. For example, switching to a pipe instead of a dash would require titleTemplate value of %s - My Travel Blog

Adding meta info to templates

Templates are where the real power of Vue Meta comes into play. We can use the method syntax of Vue Meta to dynamically change values. The method syntax will allow us to dynamically set the title and the meta description of the page for starters. Additionally, we can detect if a post has various properties, such as a cover image, which will allow us to add extra tags to inform Twitter or Facebook that they can display our links as rich cards.

In this example, we will use information about our post from a Gridsome page query to add extra information to the head meta tags.

export default {
  metaInfo() {
    return {
      title: this.$page.post.title,
      meta: [
        {
          name: "description",
          content: this.$page.post.excerpt
        },
        {
          property: "og:title",
          content: this.$page.post.title
        },
        {
          name: "twitter:card",
          content: this.$page.post.image ? "summary_large_image" : "summary",
        },
        {
          name: "twitter:creator",
          content: "@drewtown_chi"
        },
        {
          property: "og:description",
          cotent: this.$page.post.excerpt
        },
        {
          property: "og:image",
          content: this.$page.post.image || ""
        }
      ]
    };
  }
}

The title tag can be set as a direct property on the returned object as it is expected by Vue Meta. The other meta tags must be returned as an array of meta objects via the meta property.

The content can be set using the this.$page.post values, static values, or event ternary expressions in the case of the twitter:card tag. In this example, we assess whether an image exists or not to help Twitter determine which type of card to use for the post.

Wrapping up

There are many tags and structured data types such as recipes, events, books and many more that can be used to help guide users to your content and boost SEO rankings.

Using Vue Meta with Gridsome is the best way to make use of the various tags available with the least amount of effort required.

When To Use Vuex Getters In a Vue.js Project

Drew Town — Tue, 27 Aug 2019 13:38:15 +0000

If you enjoy this article please consider following me on Twitter or visiting my website.

One of the features of Vuex is its ability to parse and cache values from the store's state for quick retrieval via getters. Vuex getters are equivalent to Vue's computed properties in that they both are reactive to changes in dependencies and cached for improved performance. A question I often see from beginners when learning Vue and Vuex is when to use getters in their project. There is often a misunderstanding that Vuex must be used for all data retrieval from the store and a tendency to overuse getters. Often time retrieving the state from the store and performing operations on that state within components is a better solution with less boilerplate required.

The line between when to use access the state directly and when to use getters is a thin gray line.

When accessing the state is good enough

My general rule of thumb is that whenever I need the entire value of the variable from Vuex's state, I will retrieve it directly from the state. Some examples where you would want the entire value may be a boolean, a string, a whole object or an entire array. When you are retrieving the entire variable from the state it makes sense to retrieve the entire value by accessing it directly from the state.

export default {
  computed: { 
    isOpen() {
      return this.$store.state.isOpen; 
    }
  }
}

There is little value gained from wrapping the retrieval of these values in a getter. The computed property in the component will cache the result and will also watch the dependency, in this case, the store's state, for any changes. You receive the benefits of the getter without the boilerplate required by Vuex. By creating a getter in these cases you've essentially created two different access points into the store that returns the exact same value.

The inclination of beginners starting to use Vuex is to use it for everything and use all of its features. At first, it seems smart. All your state, mutations, actions, and getters in one centralized place which should make it easy to reason about. You'll quickly realize that adding unnecessary boilerplate is one of the great follies of the Flux pattern that Vuex is based on. The excess code required is tiresome for the value extracted in certain cases such as the one outlined above.

Use Vuex where it is the strongest and best option but avoid overusing it because it is available.

When to use getters then?

Most of the time getters are the best option when you need to access state and filter or manipulate the data in some way. Getters are even better when you need to access state and use the same filtering and parsing in multiple components.

Getters provide a great interface for containing and reusing data logic in a centralized place.

Let's take a look at a to-do application that needs to provide different views. Certain views may only need to show a list of all to-dos where others may need to sort them by the due date attached to the to-do item.

getters: {
  openTodos: state => {
    return state.todos.filter(todo => !todo.done);
  },
  sortedTodos: state => {
    //remember sort mutates the original array so, copy it first with a spread.
    return [...state.todos].sort((a, b) => a.dueDate.localeCompare(b.dueDate));
  }
}

Implementing the filtering and sorting logic in Vuex allows you to centralize and organize data manipulation across the application. This helps keep components less concerned about how to manipulate the data and allows for easier refactoring. When logic is changed or data is updated there are fewer places to update reducing the work required to update the code.

Using variables in getters

Another good use for getters is to retrieve object items from an array by their id.

getters: {
  getTodoById: state => id => {
    return state.todos.find(todo => todo.id === id);
  }
}

Because getters can accept a variable via the method style access getters are a convenient way to centralize and organize access to data even when you need to supply parameters. Rather than having the find logic spread across many components and files a single method can be used to contain all the required logic.

Conclusion

Getters are a great tool but not every problem is a nail. Use them often when needing to extract parts of the state in the store or manipulate data before retrieving it. Centralizing the logic will reduce the amount of code reuse and duplication at the cost of adding some boilerplate. In those cases, the benefit greatly exceeds the cost.

Tailwindcss is My Favorite Coloring Book

Drew Town — Sun, 11 Aug 2019 14:34:31 +0000

I am, by nature, a tinkerer. When putting a design together rarely am I satisfied on my first attempt. Rarely, am I satisfied with my design until iteration 3, 4 or even 5. Let's see how a limited set of choices can help you create a cleaner page with less CSS and less mental overhead for designers and developers.

Tailwindcss has a well-crafted design system of utility classes. If you are unaware of utility-first CSS it is a system of hyper-focused classes that do exactly 1 thing. mx-1 or shadow-lg are responsible for doing 1 thing, increasing the horizontal margin or adding a large box-shadow. These classes can be combined to create cards or buttons or any other aspect of your page.

The Design System

Utility classes provide the guidelines to your design system. The design system allows you to tinker by changing values but only to a limited set of alternatives. The creators of Tailwindcss like to express this as a "constrained set of choices."

A constrained set of choices limits your ability to adjust the margin from 1rem to 1.05rem as that is not a choice within the design system provided. Why is that good? If you need 1.05rem shouldn't you be able to use that value as your margin? Seldom has such fine-grained control over such small details lead to a better design. You've introduced a small detail that may only appear in 1 place, or worse still, may need to be remembered and used in other places.

Instead, Tailwindcss provides a thoughtful design system of limited choices. The choices provided are flexible but still force you to work within the lines.

Consistency is Key

One key to a professional-looking design is consistency. Having to decide about spacing or shadows or font sizes while trying to build a new design will add a lot of mental overhead. Tailwindcss takes those decisions out of your hands and has created a design system that allows you to be flexible, tinker.

The limited choices available helps both designers and developers be more consistent and agree on a design language without needing a full blown design system.

Remove Choices, Reduce File Size

Having a guide such as Tailwindcss will always reduce your CSS bundle size. Taking the choices out of designing will prevent designers and developers from adding 9 versions of red, all which look the same. Or, adding 12 different box-shadow styles where 4 would do.

It is a dual benefit, reduce cognitive overhead of making design system choices and also prevent CSS bloat. When there are only 4 well-known choices for a box-shadow it is harder for developers and designers to go rogue and introduce their own. Trust and use the system.

Alternatives

The constrained design system isn't unique to Tailwindcss. A similar system could be implemented using SASS variables. This would be a workable alternative but would need an immense amount of work to recreate. Additionally this is something that Tailwindcss has already done very well and provides a ton of flexibility with the configuration system.

Get out there and start coloring.

You can check out my other posts about Tailwind here on Dev.to or on my personal blog drewtown.dev or follow me on Twitter