Forem: Alok Prateek

Make any Jekyll site into a PWA

Alok Prateek — Mon, 05 Aug 2019 23:39:32 +0000

A Progressive Web App, or PWA, uses modern web capabilities to deliver an app-like user experience. Any website can be made into a PWA.

The basics

Turning a basic website into a PWA is easy and has a lot of benefits, but first, let us know more about them in brief.

At its core Progressive Web App is just a way to optimize your website for better, faster delivery. As a developer we should learn to take advantage of these new possibilities, regardless of what our content is.

My own site is just a bunch of static HTML, and my blog is based on Jekyll, and they are still perfectly valid Progressive Web App. If you run anything on the web, you can definitely benefit from this.

The beauty is that PWAs offer the best of both worlds - deep linking and URLs from the web, offline access, push notifications and more device specific features from native apps - while still staying completely platform-independent. Just the web. If an older browser does not support it, it will not break; it just falls back to the default: a regular website. And yes there are few services out there that can make your PWA into an app, that you can just publish to the app stores.

There are some serious advantages:

A faster, more secure user experience
A better Google ranking
Better usability
Better performance
Offline access
Home screen shortcut like native apps

Even if you don’t expect your users to “install” your PWA (e.g. place a shortcut on their home screen), there is still a lot to be gained by making the switch. In fact, all of the steps necessary to make a PWA will actively improve your website and many of them are considered as best practices.

How do I do it in Jekyll?

We will begin with the manifest and move to the JavaScript parts. Jekyll uses a build system based on partials that we will take advantage of.

The second part of the series will take a look on how we can make any static website a PWA and the third part will deal with using device specific features in a PWA.

We will partially take advantage of PWA-Builder to do many things in this tutorial.

The Manifest

A manifest is just a JSON file that describes all the meta data of your PWA. Things like the name, language and icon of your app go in there. This information will tell browsers how to display your app when it’s saved as a shortcut.

{
  "lang": "en",
  "dir": "ltr\rtl",
  "name": "This is my jekyll PWA",
  "short_name": "myPWA",
  "icons": [
    {
      "src": "\/assets\/images\/touch\/android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image\/png"
    }
  ],
  "theme_color": "#1a1a1a",
  "background_color": "#1a1a1a",
  "start_url": "/",
  "display": "standalone",
  "orientation": "natural"
}

This is usually called manifest.json or site.webmanifest, and linked to from the <head> of your site as

<link rel="manifest" href="manifest.json">

Regarding what fields can be there in a manifest file see MDN.

For Jekyll we will do few changes to manifest.json so that we can make changes directly from _config.yml and prevent jekyll to render it using default layout (which might insert the json into html for some themes).

The <head> portion will come in the partial that builds the head of every page. Usually it would be located in _partials.


---
layout: none

---

{
  "lang": "{{ site.language }}",
  "dir": "{{ site.lang_direction }}",
  "name": {{ site.name | smartify | jsonify }},
  "short_name": {{ site.short_name | smartify | jsonify }},
  "icons": [
    {
      "src": "\/assets\/images\/touch\/android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image\/png"
    }
  ],
  "theme_color": "{{ site.color }}",
  "background_color": "{{ site.color }}",
  "start_url": "{{ site.url }}",
  "display": "standalone",
  "orientation": "natural"
}

And in the _config.yml we might already have these following fields, if not we can always add it there.😅


name: "mysite"
short_name: "ms"
url: "https://mysite.com"
language: "en"
lang_direction: "ltr"
color: "#abc123"

So your manifest is set up. Now we move to next part.

Register the service worker

Now we need to add the JavaScript that registers the service worker into the partial that forms the <head> of your every page. As before it would usually be located in _partials.

We need to add the following piece of JavaScript in <script> tag.


if ("serviceWorker" in navigator) {
  if (navigator.serviceWorker.controller) {
    console.log("An active service worker found, no need to register");
  } else {
    // Register the service worker
    navigator.serviceWorker
      .register("{{ site.baseurl }}/serviceworker.js", {
        scope: "./"
      })
      .then(function (reg) {
        console.log("Service worker has been registered for scope: " + reg.scope);
      });
  }
}

Service Worker

Now we move to the next step. We need to create the serviceworker.js at the root of your site.

It will have the following JavaScript:


const CACHE = "pwabuilder-offline";

const offlineFallbackPage = "index.html";

// Install stage sets up the index page (home page) in the cache and opens a new cache
self.addEventListener("install", function (event) {
  console.log("Install Event processing");

  event.waitUntil(
    caches.open(CACHE).then(function (cache) {
      console.log("Cached offline page during install");

      if (offlineFallbackPage === "ToDo-replace-this-name.html") {
        return cache.add(new Response("Update the value of the offlineFallbackPage constant in the serviceworker."));
      }

      return cache.add(offlineFallbackPage);
    })
  );
});

// If any fetch fails, it will look for the request in the cache and serve it from there first
self.addEventListener("fetch", function (event) {
  if (event.request.method !== "GET") return;

  event.respondWith(
    fetch(event.request)
      .then(function (response) {
        console.log("Add page to offline cache: " + response.url);

        // If request was success, add or update it in the cache
        event.waitUntil(updateCache(event.request, response.clone()));

        return response;
      })
      .catch(function (error) {        
        console.log("Network request Failed. Serving content from cache: " + error);
        return fromCache(event.request);
      })
  );
});

function fromCache(request) {
  // Check to see if you have it in the cache
  // Return response
  // If not in the cache, then return error page
  return caches.open(CACHE).then(function (cache) {
    return cache.match(request).then(function (matching) {
      if (!matching || matching.status === 404) {
        return Promise.reject("no-match");
      }

      return matching;
    });
  });
}

function updateCache(request, response) {
  return caches.open(CACHE).then(function (cache) {
    return cache.put(request, response);
  });
}

Now you're all done with the JavaScript part.

Looking forward

Push these changes to your Jekyll site and voila! It is now a PWA.😁

I intentionally missed the part where we map the icons to the config to keep things simple, if you need help with that, drop me a comment below and I'll show you how.

Also HTTPS is essential for the site to be a PWA. Most likely you might already have heard of it and maybe using it, so I didn't stress on it.

[OPTIONAL] You can check the status of your PWA by Lighthouse Audit.😄

Make your app

Yes!

If you have reached so far why not go a step further?

If you want you can build your apps to be uploaded to Microsoft Store, Play Store and App Store via PWA-Builder.

First you'll have to enter the url of your site and click enter. It will rate your PWA out of 100. If you followed this guide you'll get 95. Not bad. 😅

You will see a bright purple button on top right, a page will come with instructions to download the apps and proceed further. If you need help, you can always drop a comment below.😀

Until next time!

Cheers!🍻

[HELP!] Name for a collaborative writing tool

Alok Prateek — Sun, 21 Jul 2019 22:46:15 +0000

I'm trying to build a collaborative writing tool, I'm searching for names but I feel whatever I think is all taken.

Can you help me with this?

I would be grateful for all those who suggest. 😁😄😄😄

And all those who suggest, will get an early access of the tool, as soon as the UI is ready.😄

Right now I only have the backend ready, but can't decide a name so I can come up with branding and start building the frontend.😅

AWS Terms

Alok Prateek — Thu, 18 Jul 2019 20:44:07 +0000

There are many terms in AWS that use confusing names for simple things.
Even working with AWS for over a year, I really miss out on some terms. That's why I wrote this article. Typing whatever I remember. I am studying these for my AWS exam, which I will take in a few weeks!

So here are the terms:

Terms

Access control list (ACL): A firewall/security layer on the subnet level
Auto scaling: Automates the process of adding or removing EC2 instances based on traffic demand for your application
Buckets: Root-level “folders”
CloudFront: Content delivery network (CDN) that allows you to store your content at “edge locations” located all around the world, allowing customers to access your content more quickly
CloudTrail: Allows you to monitor all actions taken by IAM users
CloudWatch: Service that allows you to monitor various elements of your AWS account
Consolidated billing: Allows you to view, manage, and pay bills for multiple AWS accounts in one user interface
DNS server: A database of website domains and their corresponding IP addresses
DynamoDB: NoSQL database service that does not provide other NoSQL software options
Elastic Compute Cloud (EC2): A virtual computer, very similar to a desktop/laptop computer
Elastic Load Balancing (ELB): Evenly distributes traffic between EC2 instances that are associated with it
ElastiCache: Data caching service used to help improve the speed/performance of web applications running on AWS
Elasticity: The ability of a system to increase and decrease in size
Fault tolerance: Property that enables a system to continue operating properly in the event of the failure of one or more components
Firewall: A type of software that either allows or blocks certain kinds of internet traffic to pass through it
Folder: Any “subfolder” created in a bucket
High availability: Refers to systems that are durable and likely to operate continuously without failure for a long time
IAM users: Individuals who have been granted access to an AWS account
Identity and Access Management (IAM): Service where AWS user accounts and their access to various AWS services are managed
Lambda: Serverless computing that will replace EC2 instances, for the most part
Object availability: Percent over a one-year time period that a file stored in S3 will be accessible
Object durability: Percent over a one-year time period that a file stored in S3 will not be lost
Object lifecycle: Set rules to automatically transfer objects between storage classes at defined time intervals
Object sharing: Ability to make any object publicly available via a URL link
Object versioning: Automatically keep multiple versions of an object (when enabled)
Organizations: Allow you or your company access to manage billing and access to multiple AWS accounts in one user interface
Principle of least privilege: Giving a user only the rights/access to the AWS services and resources they need to do their job and nothing more
Publishers: Human/alarm/event that gives SNS the message that needs to be sent
Relational Database Service (RDS): SQL database service that provides a wide range of SQL database options to select from
RedShift: Data warehouse database service designed to handle petabytes of data for analysis
Roles: How different AWS services are granted permission to communicate and share data
Route 53: Where you configure and manage web domains for websites or applications you host on AWS
Scalability: The ability of a system to easily increase in size and capacity in a cost-effective way
Security group (SG): Firewall/security layer on the server/instance level
Shared responsibility model: Defines what you and AWS are responsible for when it comes to security and compliance
Simple Notification Service (SNS): AWS service that allows you to automate the sending of email or text messaging notifications based on events that happen in your AWS account
Simple Storage Service (S3): Online bulk storage service you can access from almost any device
Storage class: Represents “classification” assigned to each object in S3 (standard, RRS, S3-IA, Glacier)
Subnet: A subsection of a network and generally includes all the computers in a specific location
Subscriptions: Endpoints to which a topic sends messages
Topics: How you label and group different endpoints to which you send messages
Trusted Advisor: Service that “advises” and helps you optimize aspects of your AWS account
User credentials: IAM user’s username and password for logging in to AWS
Virtual Private Cloud (VPC): A private subsection of AWS you control and in which you can place AWS resources

Do tell me what I've missed! It will help both me and the community. :-)

Introduction To Accessibility

Alok Prateek — Tue, 16 Jul 2019 23:11:20 +0000

Accessibility is a term you keep hearing, but may not fully understand. This is in part because the word itself can be a bit confusing. The root word, access, makes the concept seem tied to things like passwords. If users can “access” your site, accessibility is checked off. If only it were that simple.

Web accessibility is really about a user’s ability to access your site’s content, regardless of any physical or mental impairments. The inventor of the internet, Sir Tim Berners-Lee, put it perfectly:

“The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect.”

A truly accessible website is inclusive of every potential user. It covers differential abilities of all shapes, sizes, and permanence. Users who are blind have their own needs, as do users with a broken hand. There’s also overlap among accessibility groups. Users experiencing concussion symptoms can benefit from features designed to make a piece of content more accessible for users who experience seizures. Accessibility is a multi-faceted topic.

There are six basics principles that make web better for everyone!

Have correct text size

Users of the Internet have varying eye sight levels (due to injury, disease or age factor) and it's important to have a decent font size so that everyone can read your website without strain.

Browsers come at with a default font size of 16px. We should try to not go below that at least. Take 16px as your smallest base and build your text hierarchy upwards.

At the very minimum set your font sizes in em unit so that users can zoom in your website to increase font sizes.

Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality.

w3.org

Better Color Contrast

Users of the Internet have varying eye sight levels and it's important to have a good contrast so that everyone can read your websites without strain. My dad has deuteranopia. He can't see all colors as I do, which i discovered when I was in middle school. These days I use a plugin that checks for color issues. More on that later.

This is why there is a recommended guideline just to prevent this issue. It requires that,

The visual presentation of text and images of text has a contrast ratio of at least 4.5:1.

w3.org

Make text content easy to read and understandable.

Some sentences are just highly compounded and complex that require the reader to put in extra mental focus to figure out the overall meaning of the sentence. It might still be understandable by many people. But there are people with disabilities, including reading disabilities, even among highly educated users with specialized knowledge of the subject matter. It may be possible to accommodate these users by making the text more readable.

Here is the required guideline:

When text requires reading ability more advanced than the lower secondary education level after removal of proper names and titles, supplemental content, or a version that does not require reading ability more advanced than the lower secondary education level, is available.

w3.org

In short,

Avoid difficult and less common words
Write short sentences
Don't use more than two conjunctions in a sentence
Bullet points help wherever applicable

Labelled Form Controls

Yes, we know that once a while we see a checkbox that is too small to be clicked. A normal size checkbox could have been just fine for you to click easily. But important thing to understand here is that even the normal size checkbox can be difficult to click for some people. Specially the ones with weak motor skills i.e. Ability to do a pre-determined movement with maximum certainty.

This is one of the reasons why there is a recommended guideline to associate a <label> element with the <input> element (with all form controls in general). This makes the label also a clickable part of the form control. So you don't have to pin-point the form control.

Present instructions or labels that identify the controls in a form so that users know what input data is expected.

w3.org

Again, note that this is just one of the reasons why form controls should be correctly labelled. There are more benefits to it, Which I will come to in the next part

Labels or Instructions

Unfortunately, the developer decided to put it as the placeholder of the input. Placeholders vanish as soon as any text is entered in the input field.

What's wrong in it? Nowadays many input fields in the forms are auto-filled by browsers for us. In such a situation, if the user wants to cross-check the filled values if they are appropriate, they have no way to know what's really asked in a particular input field! The same issue also applies to a user with short memory who started filling the form and then wants to verify the fields mid-way. So always label your input fields such that the label/instruction is accessible to the user at all times.

Present instructions or labels that identify the controls in a form so that users know what input data is expected.

w3.org

Adjustable Timings

Ensure that users with disabilities are given adequate time to interact with Web content whenever possible. People with disabilities such as blindness, low vision, dexterity impairments, and cognitive limitations may require more time to read content or to perform functions such as filling out on-line forms.

w3.org

Websites are filled with things like alerts, notification etc that show for a short duration and then go away. Here are few things you can do to make them more accessible:

Make them stay longer.
Show how much time is left before they go away.
Pause their timer when hovered or focused.

In the past few points, you went through some examples of web content. The motive of those examples was two-fold:

To display few ways in which websites are generally found inaccessible.
To bring forth the fact that what you find okay for yourself, can be inaccessible for someone else. So the best we can do to make our websites accessible to most people is - Follow the recommended guidelines. Hope it was a learning experience for you. If it was, please pass this on to every other developer, designer, marketer, any you know who works with websites.

Let's make the Web a better place!

Did I miss something? or You can share some more better tips?
Please leave your views in comments!

Blog API on Github Pages

Alok Prateek — Sat, 13 Jul 2019 22:00:51 +0000

We are going to see how to build an API for static websites powered by Jekyll, so you can consume static data via any web/mobile application.

We will also see how we can use the API for JSON feed.

Steps

Output data as JSON

If you just need to output some data as JSON you can easily do that using the jsonify filter.

All variables in the front matter of your site will be accessible via site variable so we took our YAML array site.whatever and convert it to JSON with the jsonify liquid filter.

Now let's try with a more practical example. What if you want to get the JSON output of all your posts in a JSON file. That's also not hard using Jekyll. You can do it following these two steps:

First create the output file with a name, let's call it output.json.
Next open the output.json file and add the following code:


---
  limit: 10
---

{% for post in site.posts limit: page.limit %}
    {
         "id": "{{ post.id }}",
         "date"     : "{{ post.date | date: "%B %d, %Y" }}",
         "title": {{ post.title | smartify | jsonify }},
         "content_html": {{ post.content | jsonify }},
         "url": "{{ site.url }}{{ post.url }}",

         "summary": {% if post.url contains "/blog/" %}{{ post.excerpt | smartify | jsonify }}{% else %}{{ post.description | smartify | jsonify }}{% endif %},

         "date_published": "{{ post.date }}",
         {% if post.categories %} "categories"  : [
                {% for category in post.categories %} "{{ category }}"
                {% if forloop.last %}{% else %},{% endif %}
                {% endfor %}
                ],
         {% endif %}
         {% if post.categories == nil %} "categories"  : [],  {% endif %}

         {% if post.tags %} "tags"  : [
                {% for tag in post.tags %} "{{ tag }}"
                {% if forloop.last %}{% else %},{% endif %}
                {% endfor %}
                ]
         {% endif %}
         {% if post.tags == nil %} "tags"  : []  {% endif %}

    }{% unless forloop.last == true %},{% endunless %}
{% endfor %}

We have looped through all site.posts and created a JSON object with each post data separating the objects with a comma. After building your website, Jekyll will take care of parsing the YAML and Liquid data and outputting output.json with your posts data in the JSON format.

Go ahead and test it with a Jekyll blog, serve it or build it then look inside of your _site folder for your output.json with posts data. Or just visit 127.0.0.1:4000/output.json to see the result.

If you use use github pages go to your blog link /output.json and see the result.

The limit meta in the front matter controls the number of posts to output as JSON.

Using the output as API

It's simple! Place the output.json under a new folder called api and rename it index.json.

Making this API as JSON feed

I read about the JSON feed spec, and I was intrigued by the novelty of it — not the ease of using JSON as much as the insurmountable pain of using Atom XML.

For most developers, JSON is far easier to read and write than XML. Developers may groan at picking up an XML parser, but decoding JSON is often just a single line of code.

Since I already been using Jekyll for my blog, writing the code would need to be done in Liquid without any plugins.

Also in the example we already have a API ready, Why not use it?


---
layout: none
---
{
    ""version": "https://jsonfeed.org/version/1",
    "title": {{ site.name | smartify | jsonify }},
    {% if site.description %}"description": {{ site.description | smartify | jsonify }},{% endif %}
    "home_page_url": "{{ site.url }}/",
    "feed_url": "{{ site.url }}/api/index.json",
    "icon": "{{ site.url }}/assets/favicon/android-chrome-192x192.png",
    "favicon": "{{ site.url }}/favicon.ico",
    "author": {
        "name": "{{ site.author }}",
        "url": "https://alokprateek.in/",
        "avatar": "https://alokprateek.in/avatar3.jpg"
    },
    "expired": false,
    "items": [
           ]
}

Under items whatever existed in index.json before goes in, without the front matter, that remains the same.

Fields like icon, favicon, and author depend on your particular implementation, and I didn’t feel like generalizing the code by using front-matter variables rather I just pasted the values directly.

Second, you’ll have to read the spec for the full info on which fields are optional and mandatory.

That’s about it! 😊

For a final example take a look at my final JSON. And you can curl at this link blog.alokprateek.in/api/


---
limit: 10
layout: none
---
{
    "version": "https://jsonfeed.org/version/1",
    "title": {{ site.name | smartify | jsonify }},
    {% if site.description %}"description": {{ site.description | smartify | jsonify }},{% endif %}
    "home_page_url": "{{ site.url }}/",
    "feed_url": "{{ site.url }}/api/index.json",
    "icon": "{{ site.url }}/assets/favicon/android-chrome-192x192.png",
    "favicon": "{{ site.url }}/favicon.ico",
    "author": {
        "name": "{{ site.author }}",
        "url": "https://alokprateek.in/",
        "avatar": "https://alokprateek.in/avatar3.jpg"
    },
    "expired": false,
    "items": [
{% for post in site.posts limit: page.limit %}
    {
      "title": "{{ post.title }}",
      "date"     : "{{ post.date | date: "%B %d, %Y" }}",
      "url": "{{ site.url }}{{ post.url }}",
      "summary": {{ post.excerpt | smartify | jsonify }},
      "content_html": {{ post.content | jsonify }},
      {% if post.categories %} "categories"  : [
        {% for category in post.categories %} "{{ category }}"
        {% if forloop.last %}{% else %},{% endif %}
        {% endfor %}
        ],
      {% endif %}
      {% if post.categories == nil %} "categories"  : [],  {% endif %}
      {% if post.tags %} "tags"  : [
        {% for tag in post.tags %} "{{ tag }}"
        {% if forloop.last %}{% else %},{% endif %}
        {% endfor %}
        ]
      {% endif %}
      {% if post.tags == nil %} "tags"  : []  {% endif %}

    }
    {% unless forloop.last %},{% endunless %}
{% endfor %}
    ]
}

Until next time!

Cheers!🍻