Recently, I have started learning Laravel and now, I'm building an application for my new company using this amazing framework.

My senior developer was curious and thought of having a conversation with me that went like this:

Senior dev: Hmm, can I have a look at your code?

Me: Oh sure, here take a look.

Senior: (Goes through project file structure)

Senior: So, have you ever thought of using events in your application?

Me: Yeah, I wrote a custom JavaScript file to handle and fire events on the client-side like validating the forms and passing async requests to the server.

Senior: Hmm, that's okay but I'm talking using events in Laravel.

At this point, I was pretty clueless and I didn't know what the heck was going on. Events in PHP? I mean, I know about it in JavaScript because of it's event-driven architecture that we are all familiar with. But in PHP? I didn't know that.

Still confused, he proceeds to explain about it's concepts in an abstract manner and thanks to him, it induced my curiosity by asking myself: What's the deal in between using events over function calls using a route on a standard controller?

In today's article, I'll be talking about why and when to use events over function calls using Laravel in your application.

What's an event?

An event is a piece of reusable logic stored somewhere in your application that has a set of listeners waiting to be executed, if triggered.

Let's say, you have a simple CRUD application that involves user registration. Whenever a user registers, you may want to perform certain actions, such as:

• Adding them into your mailing list
• Confirmation of account

You can add more but this is just to give you an idea. Let's see take a look at two different approaches:

1. Functional
2. Events and Listeners

Functional

If you're using an MVC framework (Laravel, in our case), you'd do this in a controller with a bunch of methods like so:

<?php
namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\User;

class UserController extends Controller {
    public function index() {
        // insert code to view users page
    }

    public function create(Request $request) {
        $arr = [
            'username' => $request->username,
            'email' => $request->email,
            'password' => bcrypt('something')
        ];

        $user = User::create($arr);

        $this->sendConfirmationEmail($user);
        $this->subscribeToMailingList($user);
    }

    // Send confirmation email to user
    private function sendConfirmationEmail($user) {
        // insert code
    }

    // Subscribe user to mailing list
    private function subscribeToMailingList($user) {
        // insert code
    }
}
?>

This is approach is self-contained and simple to follow but you're also adding in a lot of responsibility to your controller.

Not only that, what if the user wants to register from another place in your application, in that case, you'll have to duplicate your logic in multiple places.

Events and Listeners

Using this approach, you can split this into Event and Listener files in your application.

<?php
namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\User;

class UserController extends Controller {
    public function index() {
        // insert code to view users page
    }

    public function create(Request $request) {
        $arr = [
            'username' => $request->username,
            'email' => $request->email,
            'password' => bcrypt('something')
        ];

        $user = User::create($arr);

        // Emit event
        event(new UserRegistered($user));
    }
}
?>

This is how your UserRegistered event would look like:

<?php
namespace App\Events;

use Illuminate\Queue\SerializeModels;
use App\User;

class UserRegistered {
    use SerializesModels;

    public $user;

    public function __construct(User $user) {
        $this->user = $user;
    }
}
?>

And this is how your SendConfirmationEmail listener would look like:

<?php
namespace App\Listeners;

use App\Events\UserRegistered;

class SendConfirmationEmail {

    public function __construct(User $user) {
        // insert code
    }

    public function handle(UserRegister $event) {
        // insert code
    }
}
?>

Using this approach, you can use the UserRegistered event anywhere you wanted in your application. No matter what happens, it will trigger the same actions as it was intended to do so. If you want to add a new functionality, create a new listener and register it with the event in your EventServiceProvider file like this:

<?php
protected $listen = [
    'App\Events\UserRegistered' => [
    'App\Listeners\SendConfirmationEmail',
    ],
];
?>

If you follow this approach, your logic complexity is toned down and the controller will have less responsibility.

Why use events and listeners over function calls?

Just like this answer that I found on StackOverflow question regarding events and listeners over calling functions:

You might not be in control of the code that's doing the calling. Or even if you are, you don't want to introduce dependencies into that code.

Think about it, what if you built an API or library that you want people to use but don't want them to modify the source code. Instead, you could provide a documentation that states specific events are raised under specific circumstances, in turn, they can write code that responds to such events.

I'm sure that there are more examples as to where this methodology might be applied.

When to use it?

Truth be told, it depends. If you have a simple application, then a functional approach is all you need but it's a larger and more complicated application, using Events and Listeners can be a better option.

Conclusion

Please note, I'm not an expert at this topic as I'm still learning and I thought of sharing what I had learnt. If you have any suggestions or thoughts, please share it with me on Twitter or send me a message to my inbox.

Hope you liked reading this article.

Stay tuned for more.

Extras

• Why use event listeners over function calls
• The meaning of events in PHP
• Laravel Events

Beautiful, isn't it? It might look complex but it's mathematically quite impressive. Making this pattern wasn't hard but it definitely took a lot of trial and error to get it right and honestly, I don't really know if it's this is the most efficient way to generate this pattern.

This article isn't a tutorial but rather, I'll be talking about the algorithm itself. However, you can check out the source code in my GitHub repository.

How it works?

In order to achieve that "stacked" effect, there are two things to keep in mind:

1. Generate circles with a random radius
2. Look for collisions with other circles

The logic is quite similar to the Overlapping Rectangles problem except this is done with circles.

Generate circles with dynamic radius

This method will help generate valid circles with a random radius. Circles that don't overlap or collide with other circles are considered to be valid.

// Generate a valid circle
const generateCircle = () => {
    let newCircle;
    let isValidCircle = false;

    for(let i=0; i<attempts; i++) {
        newCircle = {
            x: Math.floor(Math.random() * width),
            y: Math.floor(Math.random() * width),
            radius: minRadius
        };

        if(checkForCollision(newCircle)) {
            continue;
        }
        else {
            isValidCircle = true;
            break;
        }
    }

    if(!isValidCircle) { return; }

    for(let i=minRadius; i<=maxRadius; i++) {
        newCircle.radius = i;
        if(checkForCollision(newCircle)) {
            newCircle.radius--;
            break;
        }
    }

    circles.push(newCircle);
    drawCircleOnCanvas(context, newCircle, colors[Math.floor(Math.random() * colors.length)]);
}

Look for collision with other circles

Thanks to some online research, I was able implement the Euclidean Distance equation that helped with calculating the distances between each circle and detect for collisions. Along with that, I also found another article on Touching Circles that was quite useful.

These are the formulas used to detect the collision:

1. Find the distance between two centres $$AB=\sqrt{(x2-x1{)}^2-(y2-y1{)}^2}$$

2. Calculate the radii of both circles. $$R=r1+r2$$

If the radii is greater than or equal to the euclidean distance of both circles, then it's a valid circle with no collisions.

// Check for collision in a canvas
const checkForCollision = (newCircle) => {

    let x2 = newCircle.x;
    let y2 = newCircle.y;
    let r2 = newCircle.radius;


    // Determine the euclidean distance between two circle
    // using Pythagorean Theorem.

    // Refer to: 
    // https://en.wikipedia.org/wiki/Euclidean_distance

    for(let i=0; i<circles.length; i++) {

        let otherCircle = circles[i];
        let r1 = otherCircle.radius;
        let x1 = otherCircle.x;
        let y1 = otherCircle.y;
        let xx = ((x2 - x1) * (x2 - x1));
        let yy = ((y2 - y1) * (y2 - y1));
        let radii = r2 + r1;
        let euclidDistance = Math.sqrt(xx + yy);

        if(radii >= euclidDistance) {
            return true;
        }
    }

    // Check collision on top
    if(x2 + r2 >= width || 
        x2 - r2 <= 0) {
        return true;
    }

    // Check collision on bottom
    if(y2 + r2 >= width || 
        y2 - r2 <= 0) {
        return true;
    }

    //else return false
    return false;
}

Conclusion

I'm thinking of implementing more generative patterns like Triangular Mesh and Piet Mondrian's Red, Blue and Yellow composition.

Hope you liked reading this article.

Stay tuned for more!

In my previous article, I talked about how to setup your environment for developing your Laravel applications. Today, I'll be talking about deploying your application along with a database on Heroku.

I wrote a simple CRUD application using Laravel but didn't understand on how to host it. I tried to host it on free shared hosting service but apparently, most of them don't support PHP system calls like proc_open(). However, if it was a VPS hosting service, it's supported but ain't nobody got time for shelling out cash for a test drive.

As an alternative, I went on google and discovered that Heroku does support my requirements and it worked flawlessly, which is why I thought of sharing this information to others as well.

If you're a developer who's at the early stages of learning Laravel (like me 😆), then this article is for you.

Prerequisites

You'll be doing some minor configurations, so you should be fine as long as you have a stable internet connection, familiar with using the CLI (Command Line Interface) and have some PHP knowledge.

If you're a Windows user, please Git for Windows. Else, if you're a Linux or macOS user, you should be fine.

How to deploy?

You can ignore the first two steps if you already know about Heroku and how to work with it but please follow the rest of the steps:

1. Install Heroku
2. Create a Heroku repository
3. Define Procfile
4. Push Laravel app to repository
5. Add configuration variables
6. Setup your database

Install Heroku CLI

You can install this directly from the command line by typing the following:

sudo snap install heroku --classic

Create a Heroku repository

If you don't have a Heroku account yet, create an account now and once you're done with that, type the following:

heroku login

Follow the login instructions from the command line prompt, fill in your login credentials and you'll be in!

Once, you're done with that, create a repository by doing the following:

heroku create

In a few seconds, you'll get a randomly generated domain address, which is the link to your Heroku repository. If you can't remember the link, it's fine, you can make changes to it in your Heroku account.

Define Procfile

In case, you don't know what's a Procfile, it's a file that specifies the commands that needs to be executed by the application on startup. You can declare a variety of process types, click here to learn more.

Since our application is PHP based, we need to add some specific command that selects the server on boot, I chose Apache server for this project:

cd your_laravel_project
touch Procfile
echo "web: vendor/bin/heroku-php-apache2 web/" > Procfile

Push Laravel app to repository

It's similar to pushing your code into your GitHub, except this time, it's your Heroku repository. Type the following in your command line:

git add .
git commit -m "pushing application to repo"
git push heroku master

To check if your application is launched, type the following:

heroku open

At this stage, you might face Error 500, that's normal because we'll take care of that in the next step.

Configure your Heroku environment

We need to add some config variables that changes the way your app behaves. So, let's start adding it:

heroku config:set APP_DEBUG=true
heroku config:set APP_KEY=yourlaravelapplicationkey
heroku config:set APP_URL=https://yourwebsite.herokuapp.com
heroku config:set REDIRECT_HTTPS=true

In this configuration, you have done the following: - Enabled debug mode - Set your Laravel application's base64 encrypted key - The website's URL - Force HTTPS redirect (Useful, when you're calling external assets that uses HTTPS protocol)

Note: You can find your APP_KEY in your .env file that's found in your project directory.

Setup your database

Initially, I built the database on MySQL but I later learnt that Heroku gives a free PostgreSQL starter database. I've never tried PostgreSQL before but it's quite similar to MySQL, so you shouldn't worry about your schema as Laravel supports PostgreSQL and MySQL databases by default.

Type the following in the command line:

heroku addons:create heroku-postgresql:hobby-dev

This will create a PostgreSQL database and sets a DATABASE_URL, which contains the username and password to the database. To check it, type the following:

heroku config

Now, go to your project directory and open the config/database.php file and add the following:

<?php
// Place these variables above
$url = parse_url(getenv("DATABASE_URL"));
$host = $url["host"]??null;
$username = $url["user"]??null;
$password = $url["pass"]??null;
$database = substr($url["path"], 1)??null;

// Replace the default connection
'default' => env('DB_CONNECTION', 'pgsql_prod'),

// Under the connections attribute, create a new connection called 'pgsql_prod'
'pgsql_production' => [
    'driver' => 'pgsql',
    'host' => $host,
    'database' => $database,
    'username' => $username,
    'password' => $password,
    'charset' => 'utf-8',
    'prefix' => '',
    'schema' => 'public',
],
?>

Push the new changes to your repository:

git add .
git commit -m "configured database"
git push heroku master

One last step, we need to create the tables from your schema, so type the following:

heroku run php /app/artisan migrate --seed

Follow the command line prompt and voila, you have successfully deployed your Laravel application with a database on Heroku.

Conclusion

Well, I hope you found this article really useful especially if you're a beginner. If you do find this useful, please share it with others too!

Stay tuned for more!

I started learning Laravel and I thought of writing a small tutorial on how to setup your own local development environment for Laravel projects with Laravel Homestead and Vagrant.

What is Laravel Homestead?

It's an official package from Laravel that provides a neat development environment that comes along with a Vagrant box that has pre-installed software. Read their documentation to know more about it.

Note: The examples of this tutorial are applicable to any developer that uses any UNIX-based operating systems such as macOS or any Linux distributions like Ubuntu. If you're using Windows, I recommend that you install Git for Windows on your local machine.

Prerequisites

The only requirement for this tutorial is that you should be familiar with using the command-line interface.

Install VirtualBox and Vagrant

VirtualBox is the software used to run a virtual machine with a sandbox operating system within your own computer.

Vagrant is a software that's used to manage a development environment. Through the command-line, you can perform any operation such as installing an OS, configuration, deployment and so on.

You can install VirtualBox and Vagrant via the command-line:

sudo apt install virtualbox vagrant

Once you're done installing them, you should add the laravel/homestead box to your Vagrant installation using the following command:

vagrant box add laravel/homestead

To check if it has been installed, use the following command:

vagrant box list | grep "homestead"

Using VirtualBox and Vagrant allows you to simulate your Laravel development environment without messing up any configurations on your hosting system. Even if you did, no worries, Vagrant boxes are disposable, so you can destroy and create a new box again in minutes.

Download Laravel Homestead

You can install Homestead by cloning it's repository onto your local machine by typing the following command:

git clone https://github.com/laravel/homestead.git ~/projects/Homestead

Generate configuration file

Once you're done cloning the repository, go inside the projects/Homestead directory and run the init.sh or init.bat (for Windows) to create the Homestead.yaml configuration file:

cd projects/Homestead
bash init.sh

Open the default Homestead.yaml file and make the following changes:

---
ip: "192.168.10.10"
memory: 2048
cpus: 2
provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

folders:
    - map: ~/projects/code
      to: /home/vagrant/projects/code

sites:
    - map: homestead.test
      to: /home/vagrant/projects/code/public

databases:
    - homestead

Generate SSH key

The documentation for Laravel Homestead doesn't really talk about generating SSH keys used to access the Vagrant box. Use the following command to generate it using ssh-keygen on the command-line:

ssh-keygen -t rsa -C "root@homestead"

Map the project's shared folder

Make sure that you have created a folder named code in your projects directory. This folder will keep all of your Laravel project files in sync between your local machine and Homestead environment.

Installing Laravel

Time to install Laravel into your virtual machine. So, get switch on your virtual machine by doing the following in the command-line:

vagrant up

As you're switching it on for the first time, depending on your internet connection, it might take somewhere around 10-20 minutes to getting it running but it'll be fine afterwards.

Alright, login to your Vagrant machine by doing the following the command-line:

vagrant ssh

Once you're in, go to your code directory and type the following in the command-line:

composer global require laravel/installer

Create a new project

Now, it's time to create a new Laravel project by simply typing the following command:

laravel new projectname

It'll take some time to generate the necessary files and boilerplate code and after that, you're good to go!

Oh, you should be able to see the Laravel project files in your local machine as it's synced with the virtual machine and local machine. That means, any changes made on either machines will be synced and reflected on both ends.

Map your hosts file

One last step, make sure you map your project's test domain onto your local machine's hosts file.

Open a text-editor of your choice and do the following in the etc/hosts file:

127.0.0.1   localhost
::1         localhost

# Add this line (Note: It can be any URL)
127.0.0.1   homestead.test

Now, go to your browser and type homestead.test and you should be able to see your Laravel project's sample layout.

Conclusion

As mentioned, in the beginning of this article, I have started to learn Laravel and I'll be building some projects and writing out my experiences about it soon.

I hope you liked reading this article and please share it with others if you do find this tutorial useful.

Stay tuned for more!

If you are curious about web development, you must have came across names like Jekyll, Hugo, Gatsby and more. These names that I mentioned are called Static Site generators. In fact, this website that you're on, is powered by a static site generator and I really like it so far.

In today's article, you'll learn how to build your own Static Site Generator using Python, create a blog and host it on Netlify for free. Please note, that this is a basic tutorial that would show the bare-metals of this generator.

These are the pre-requisities to this tutorial:

• Basic understanding of Python, Git, HTML and Markdown
• Basic knowledge of file I/O
• Know-how on using the command-line

If you don't know them, it's okay, you can still do your own research on Google and learn on-the-go!

Before we jump in, let's see why is it the latest craze!

Why is it popular?

Take a blog, it's a dynamic web application that consists of a lot of sections like blog posts, archives and categories. Each time, a user visits a blog post, it sends a GET request to the server, fetches the data, then generates a webpage along with the fetched data on-the-fly. However, with a static site generator, you only serve pre-rendered files, so you don't have to generate or create anything on-the-fly, it's already there!

Apart from that, applications like a blog are usually database-dependant and you need to host it somewhere with a price. Not only that, but it does have security risks. With static site generators, you write your content on a markdown file and then convert it into static HTML files, which can then be used to host your website on services like GitHub Pages or Netlify for free and you don't have to worry about any security issues.

What are the functionalities?

These are the functionalities that we'd require in a blog:

• Display all blog articles
• Pagination module
• A page for each article

So, let's go ahead and start with building the project.

Time to build it!

Let's plan before we dive in straight into coding it. This is the file structure we'll be following in this tutorial:

Create file structure

This is the file structure we're going to follow in this tutorial, so create it before you proceed with the tutorial.

\blog-ssg
    \content
    \output
    \templates
    make_entry.py
    ssg.py
    ssglib.py

Next, install the following dependencies using pip:

pip install markdown2
pip install jinja2

Generate markdown files

Go to your make_entry.py file and copy-paste this code. This will be used to generate markdown file for you to edit instead of having to create it manually all the time.

import os, sys
from glob import glob
from datetime import datetime

# This is the Markdown template
TEMPLATE = """
title: {title}
date: {date}
slug: {slug}
category: Write category here.
summary: Write summary here.

Write content here.
"""

def suffix(d):
    return 'th' if 11<=d<=13 else {'1':'st', '2':'nd', '3':'rd'}.get(d%10, 'th')

def custom_strftime(format, t):
    return t.strftime(format).replace('{S}', str(t.day) + suffix(t.day))

# Generate file number by looking at the number blog articles in the directory
def gen_file_no(file_path, existing_files):
    """
        If no files are found,
        then this is the first file.
    """
    if not existing_files:
        return 1

    """
        Look for the biggest file number
        and return the bigger one
    """
    prefixes = [filename.replace(file_path,"")[:2] for filename in existing_files]
    biggest_prefix = max(prefixes, key= lambda n: int(n))
    return int(biggest_prefix) + 1

# Generate slug for the blog article
def gen_slug(title):
    title = "".join(x for x in title if x.isalnum() or x == ' ')
    title = title.lower().strip("").replace(' ','-')
    return title

# Create entry
def make_entry(title, file_type):
    if file_type == "articles":
        file_path = "content/" + file_type + "/"

        # Create folders if they didn't exist
        if not os.path.exists(file_path):
            os.makedirs(os.path.dirname(file_path))

        today = datetime.today()

        slug = gen_slug(title)
        file_no = gen_file_no(file_path, existing_files=glob(file_path + "*.md"))
        blog_file_path = file_path + "{:0>2}_{}_{:0>2}_{:0>2}_{}.md".format(file_no, today.year, today.month, today.day, slug)

        post_date = datetime.strptime(str(today.date()), '%Y-%m-%d')
        post_date = custom_strftime('%B {S}, %Y', post_date)

        t = TEMPLATE.strip().format(title=title,
            year=today.year,
            month=today.month,
            date=post_date,
            slug=slug)      

        with open(blog_file_path, 'w') as w:
            w.write(t)

        print blog_file_path

if __name__ == '__main__':
    if len(sys.argv) > 1:
        make_entry(sys.argv[1], sys.argv[2])
    else:
    print "Enter blog title and article type"

To create a blog entry, just type this in your terminal:

python make_entry.py "Article Name" articles

Create a library

This library must have the following functionalities:

• Fetch content from Markdown files
• Create templates
• Generate index page
• Generate articles from Markdown to HTML
• Generate pagination module
• Generate blog

So, create a new file named ssglib.py and let's do each of the functionality step-by-step to gain a deeper understanding of each method/function in the library.

Before that, add the following lines to the file:

import os, random, sys
from datetime import datetime
from jinja2 import Environment, PackageLoader
from markdown2 import markdown
from argparse import Namespace

# Jinja2 Environment
env = Environment(loader=PackageLoader('ssg','templates'))

Fetch content from Markdown files

This method will fetch content from all of the Markdown files that resides in the content/articles folder.

# Get Markdown files from content directory
def get_markdown_files(section):
    POSTS = {}

    file_path = 'content/'

    for md_file in os.listdir(file_path):
        md_file_path = os.path.join(file_path, md_file)

        # if it's not a directory, read it
        if not os.path.isdir(md_file_path):
            with open(md_file_path, 'r') as file:
                POSTS[md_file] = markdown(file.read(), extras=['metadata'])

    return POSTS

Create templates

You'll need to create two templates, one for home page and the other is for your articles. All templates will reside in the templates folder.

This is the template for the home page of your blog and you can name this as index.html:

<!DOCTYPE html>
<html>
<head>
    <title>My Blog</title>
    <base href="/"/>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
    <main>
        <div class="posts-list">
            {% for post in posts %}
            <a href="posts/{{ post.slug }}/">
                <p>{{ post.date }} &mdash; {{ post.title }}</p>
            </a>
            {% endfor %}
        </div>

        <div class="paginator">
            {% if curr == 2 %}
                <a class="prev" href="/" rel="prev">Newer</a>
            {% elif prev != 0 %}
                <a class="prev" href="/pages/{{prev}}" rel="prev">Newer</a>
            {% else %}
                <a class="prev inactive">Newer</a>
            {% endif %}

            <p>{{curr}} <span>of</span> {{total}}</p>

            {% if next != 0 %}
                <a class="next" href="/pages/{{next}}" rel="next">Older</a>
            {% else %}
                <a class="next inactive">Older</a>
            {% endif %}
        </div>

    </main>
</body>
</html>

This is the template for the article page and you can name this as article.html:

<!DOCTYPE html>
<html>
<head>
    <title>{{ post.title }}</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="author" content="Your name">
    <meta name="description" content="{{ post.summary }}.">
</head>
<body>
    <main class="article-main">
        <div class="article-info">
            <div>
                <h5>{{ post.category }}</h5>
                <h1>{{ post.title }}</h1>
                <p>{{ post.summary }}</p>
                <h6>Your name &mdash; {{ post.date }}</h6>
            </div>    
        </div>
        <article class="article-container">
            <div class="content">
            {{ post.content }}
            </div>
        </article>
    </main>
</body>
</html>

Though, this is just a bare-bone template, you can be creative and make your own changes to it by making it visually-appealing!

Generate index page

This method will create your index page. The index page will contain the links for each article.

def index(POSTS, isPaginate=True):
    posts_metadata = get_posts_metadata(POSTS)
    if not isPaginate:
        template = env.get_template('index-alt.html')
        html_content = template.render(posts=posts_metadata)
        index_path = 'output/index.html'
        write_to_file(index_path, html_content.encode('utf-8'))
    else:
        args = {
            "template": env.get_template('index.html'),
            "posts_metadata": posts_metadata,

            # Keeps tracks the current post
            "curr_posts_index": 0,

            # Total number of posts
            "total_posts": len(POSTS),

            # Number of posts per page
            "posts_per_page": 8,

            # Directory to hold the pages
            "main_pages_path": "output/pages/"
        }
        pagination(args)

Generate articles from Markdown to HTML

This method will convert your Markdown content into HTML pages. One thing to note, each blog post will have it's own folder name with it's own slug and index.html file, so that it'll be easier to access the article.

# Generate all posts
def articles(POSTS, post_template):
    for post in POSTS:
        post_metadata = POSTS[post].metadata
        post_data = {
            'content': POSTS[post],
            'slug': post_metadata['slug'],
            'title': post_metadata['title'],
            'summary': post_metadata['summary'],
            'category': post_metadata['category'],
            'date': post_metadata['date']
        }
        post_html_content = post_template.render(post=post_data)
        post_file_path = 'output/posts/{slug}/index.html'.format(slug=post_metadata['slug'])
        create_directory(post_file_path)
        write_to_file(post_file_path, post_html_content.encode('utf-8'))

Generate pagination module

Depending on the amount of blog articles you want to display, it will create total number of posts / article per page pages on the home page. They will look identical to the index page and these pages will be created in output/pages folder.

# Pagination module
def pagination(args):

    x = Namespace(**args)

    # Number of pages (for pagination)
    num_pages = (x.total_posts/x.posts_per_page)

    # Create a page directory, if it doesn't exist
    create_directory(x.main_pages_path) 

    for pagenum in range(0, num_pages+1):
        # This will contain metadata of every x number of posts per page
        page_metadata = []
        page_path = ""
        curr_page = pagenum+1

        if curr_page == 1:
            page_path = "output/index.html" 
        else:
            page_path = "output/pages/{page}/index.html".format(page=curr_page)

        create_directory(page_path)

        # Internal counter to keep track of posts per page
        posts_counter = 0

        for j in range(x.curr_posts_index, len(x.posts_metadata)):
            page_metadata.append(x.posts_metadata[j])
            posts_counter = posts_counter+1

            # If it reached it's limit, break
            if posts_counter == x.posts_per_page:
                x.curr_posts_index = j+1
                break

        # Create links for previous and next pages
        prev_page = 0 if curr_page == 1 else curr_page-1
        next_page = 0 if curr_page == num_pages+1 else curr_page+1

        # Render the page
        html_content = x.template.render(
            posts=page_metadata, 
            curr=curr_page,
            prev=prev_page, 
            next=next_page,
            total=num_pages+1
        )

        write_to_file(page_path, html_content.encode('utf-8'))

Generate blog

This is the main function that will generate the entire blog including all of the article pages.

# Generate blog -- Main function
def main(section):
    sections = ['articles']
    if section in sections:
        POSTS = get_markdown_files(section)
        if section == "articles":
            posts_template = env.get_template('article.html')
            index(POSTS, True)
            articles(POSTS, posts_template)
    else:
        print "This section doesn't exist."

Take a look at the source code for both ssglib.py and ssg.py and feel free to tinker around with it.

Source code for ssglib.py:

#!usr/bin/python
import os, random, sys
from datetime import datetime
from jinja2 import Environment, PackageLoader
from markdown2 import markdown
from argparse import Namespace

# Jinja2 Environment
env = Environment(loader=PackageLoader('ssg','templates'))

# Write to file
def write_to_file(path, content):
    with open(path, 'w') as file:
        file.write(content)
        file.close()

# Create directory
def create_directory(path):
    if not os.path.exists(path):
        os.makedirs(os.path.dirname(path))

# Get Markdown files from content directory
def get_markdown_files(section):
    POSTS = {}

    file_path = 'content/'

    for md_file in os.listdir(file_path):
        md_file_path = os.path.join(file_path, md_file)

        # if it's not a directory, read it
        if not os.path.isdir(md_file_path):
            with open(md_file_path, 'r') as file:
                POSTS[md_file] = markdown(file.read(), extras=['metadata'])

    return POSTS

"""
Collect metadata of all the posts
for home page and sort them 
in reversed order

@param: 
    POSTS => Dictionary
"""
def get_posts_metadata(POSTS):
    posts_metadata = []
    for k,v in sorted(POSTS.items(), reverse=True):
        posts_metadata.append(v.metadata)
    return posts_metadata

"""
    @params:
    POSTS => Dictionary
    template => jinja template
    isPaginate => boolean to enable pagination
"""
def index(POSTS, isPaginate=True):

    posts_metadata = get_posts_metadata(POSTS)

    if not isPaginate:
        template = env.get_template('index-alt.html')
        html_content = template.render(posts=posts_metadata)
        index_path = 'output/index.html'
        write_to_file(index_path, html_content.encode('utf-8'))

    else:
        args = {
            "template": env.get_template('index.html'),
            "posts_metadata": posts_metadata,

            # Keeps tracks the current post
            "curr_posts_index": 0,

            # Total number of posts
            "total_posts": len(POSTS),

            # Number of posts per page
            "posts_per_page": 8,

            # Directory to hold the pages
            "main_pages_path": "output/pages/"
        }

        pagination(args)

# Generate all posts
def articles(POSTS, post_template):
    for post in POSTS:
        post_metadata = POSTS[post].metadata
        post_data = {
            'content': POSTS[post],
            'slug': post_metadata['slug'],
            'title': post_metadata['title'],
            'summary': post_metadata['summary'],
            'category': post_metadata['category'],
            'date': post_metadata['date']
        }
        post_html_content = post_template.render(post=post_data)
        post_file_path = 'output/posts/{slug}/index.html'.format(slug=post_metadata['slug'])
        create_directory(post_file_path)
        write_to_file(post_file_path, post_html_content.encode('utf-8'))

# Generate pages
def pagination(args):

    x = Namespace(**args)

    # Number of pages (for pagination)
    num_pages = (x.total_posts/x.posts_per_page)

    # Create a page directory, if it doesn't exist
    create_directory(x.main_pages_path) 

    for pagenum in range(0, num_pages+1):
        # This will contain metadata of every x number of posts per page
        page_metadata = []
        page_path = ""
        curr_page = pagenum+1

        if curr_page == 1:
            page_path = "output/index.html" 
        else:
            page_path = "output/pages/{page}/index.html".format(page=curr_page)

        create_directory(page_path)

        # Internal counter to keep track of posts per page
        posts_counter = 0

        for j in range(x.curr_posts_index, len(x.posts_metadata)):
            page_metadata.append(x.posts_metadata[j])
            posts_counter = posts_counter+1

            # If it reached it's limit, break
            if posts_counter == x.posts_per_page:
                x.curr_posts_index = j+1
                break

        # Create links for previous and next pages
        prev_page = 0 if curr_page == 1 else curr_page-1
        next_page = 0 if curr_page == num_pages+1 else curr_page+1

        # Render the page
        html_content = x.template.render(
            posts=page_metadata, 
            curr=curr_page,
            prev=prev_page, 
            next=next_page,
            total=num_pages+1
        )
        write_to_file(page_path, html_content.encode('utf-8'))

# Generate blog -- Main function
def main(section):
    sections = ['articles']
    if section in sections:
        POSTS = get_markdown_files(section)
        if section == "articles":
            posts_template = env.get_template('article.html')
            index(POSTS, True)
            articles(POSTS, posts_template)
    else:
        print "This section doesn't exist."

Source code for ssglib.py

import ssglib
from ssglib import (os, random, sys, datetime, 
Environment, PackageLoader, markdown)

if __name__ == '__main__':
    if len(sys.argv) > 1:
        ssglib.main(sys.argv[1])
    else:
        print "Enter section name you want to generate."

To generate your blog, type the following in your command-line:

python ssg.py articles

Make sure you have a local HTTP server running on your computer, if you don't install this using NPM on your command-line:

npm i live-server

Alright, your blog is generated and now, it's time to launch it to the internet!

Deploy project on Netlify

As I had mentioned in the previous article, I'm currently hosting my blog on Netlify. If you want to know more about it, click here.

Let's go through the steps to deploying your blog:

1. Create a GitHub repository

If you have a GitHub account, continue reading. If not, go here.

Create a repository with any name you like and push all your files into the repository.

2. Connect to Netlify

Create an account on Netlify.com and then connect to your GitHub account. After that, you have to select the repository that has your static files (Not the python code).

3. Sit and Relax

At this stage, your blog will be deployed automatically and you'll be given a unique URL to view your website.

If you have a custom domain, I suggest you follow the instructions and make the necessary changes in the CNAME and A records.

Don't worry about the SSL certificate, it does take some time to activate, it took me like 7-8 hours to get it working.

Conclusion

If you've completed this tutorial, give a yourself a pat in the back because now you know how static site generators work and you've built and hosted your own blog on the internet.

Hope you liked reading this article and please share it to others too!

Stay tuned for more!

When I converted my website to a static site using a custom-built static site generator using Python, I came across topics like "Hosting your website on GitHub Pages". At the time, I thought that I didn't really need it because my website was hosted on Hostinger and it pretty much had everything that I needed until it started to get on my nerves.

Recently, my blog had been facing a lot of issues such as my website would face random downtime, hosting prices wasn't consistent and the FTP service for it was really annoying.

So, I decided that I need to find a better hosting service for my blog.

Exploring GitHub Pages

Setting up your website was pretty easy using GitHub Pages, all you have to do was create a repository named websitename.github.io and you're done.

Plus, unlike other hosting services, GitHub Pages hosts your website for free. That sounded like really amazing and it has really good security, caching and speed too.

However, it was my first choice and like every other free hosting services, it does come with a few drawbacks that didn't fit my requirements. GitHub Pages offers a bandwidth limit of 1GB and it didn't have good custom domain support. Also, I read that it had weird caching issues once you commit your changes to your repository.

Here comes, Netlify!

When I discovered Netlify, I was happy because it had free hosting, good custom domain support and a 100GB soft bandwidth, which is really fitting my requirements.

According to Netlify:

Make your site or web-app many times faster by bringing it closer to your users.

The cool thing is that your website is not only pushed to a single server but to a global network of CDN nodes that can handle operations like automatic caching, smart rewrite and redirect rules and yes, blazing, fast loading speeds.

Hosting your website on Netlify is simple as few clicks, all you have to do is upload your website on a Git repository then connect it to Netlify and it will deploy your website in less than 5 minutes.

Updating my blog is easier now as now I just have to push my new commits to my GitHub repo and Netlify would automatically deploy it. Goodbye, FTP!

Configuring HTTPS and custom domain settings

Since I have a custom domain, I configured my domain to point to Netlify's load balancer IP address by changing the A and CNAME records in the DNS Zone editor. The HTTPS/SSL part was a bit annoying and it took some time, like 5-6 hours, but apart from that, it was a great experience in migrating to Netlify.

Conclusion

In short, my blog's static files are hosted on GitHub and automatically deployed on Netlify for free. I do have some future plans, like trying to roll out a commenting engine and light/dark themes for the blog.

Hope you liked reading this article!

Stay tuned!

Before you read this article, play with the above game. The rule is simple, reveal one cell at a time by clicking on them, If the cell you've clicked on is clear, you'll see the number of mines that's adjacent to it. Else, if it's a mine, then all mines will explode and you lose the game. Reload the game by clicking the Reset button.

The source code of the game can be found over here.

Background

It's a classical puzzle game that gained immense popularity when it came along with Windows 3.1 OS. To be honest, I never really had any experience playing this game until a few days ago, I had a sudden curiosity as to how it works. I studied it's game mechanics on Wikipedia and it turned to be simple enough to write a clone in Javascript.

Game mechanics

What makes it interesting to play is it's simplicity in which all that matters is that you shouldn't click the cell that goes "KABOOM!".

Here are some of the game mechanics:

• Generate cells
• Placing the mines
• Reveal the mines
• Scan for mines
• Level completion

Generate cells

Generating the grid is pretty much straightforward. Each cell will have an attribute named data-mine with a boolean value of true or false.

//Generate minesweeper grid
const generateGrid = () => {
    allowClick = true;
    grid.innerHTML = "";
    for(let i=0; i<size; i++) {
        let row = grid.insertRow(i);
        for(let j=0; j<size; j++) {
            let cell = row.insertCell(j);
            cell.onclick = function(){clickCell(this);}
            let mine = document.createAttribute("data-mine");
            mine.value = "false";
            cell.setAttributeNode(mine);
        }
    }
    setMines();
}

Placing the mines

After the grid is generated, a mine will be added to each random cell.

//Set mines
const setMines = () => {
    for(let i=0; i<size*2; i++) {
        let r = Math.floor(Math.random() * size);
        let c = Math.floor(Math.random() * size);
        let cell = grid.rows[r].cells[c];
        cell.setAttribute("data-mine", "true");
        if(testMode){cell.innerHTML = "&#x1f4a3;";}
    }
}

Reveal the mines

If you've clicked on a mine, every cell that has a mine will be exposed and then it's game over.

//Reveal mines
const revealMines = () => {
    for(let i=0; i<size; i++) {
        for(let j=0; j<size; j++) {
            let cell = grid.rows[i].cells[j];
            if(cell.getAttribute("data-mine") === "true") {
                cell.className = "mine";
                cell.innerHTML = "&#x1f4a3;";
            }
        }
    }
}

Scan for mines

When you click on a tile, there are 2 possibilities i.e. either the cell is a mine or not.

If it's a mine, we know what happens, it's self explanatory. If it's not a mine, what happens then? Well, it'll start scanning for mines that are adjacent to it in all eight directions:

If there aren't any mines adjacent to it, it'll reveal all adjacent cells via recursion.

    //Click a cell
    const clickCell = (cell) => {
        if(allowClick != false) {
            //If it's a mine, game over
            if(cell.getAttribute("data-mine") === "true") {
                alert("game over");
                revealMines();
                allowClick = false;
            }
            //If it's not a mine, reveal the mines
            else {
                //Mark it as "clicked"
                cell.className = "clicked";
                scanForMines(cell);
                checkGameStatus();
            }       
        }
    }

    //Scan for mines that are adjacent to the cell
    const scanForMines = (cell) => {
        let rowPos = cell.parentNode.rowIndex;
        let colPos = cell.cellIndex;
        let mineCount = 0;

        for(let i=Math.max(rowPos-1, 0); i<Math.min(rowPos+1, size-1); i++) {
            for(let j=Math.max(colPos-1, 0); j<Math.min(colPos+1, size-1); j++) {
                let adjacentCell = grid.rows[i].cells[j];
                if(adjacentCell.getAttribute("data-mine") == "true") {
                    mineCount++;
                }
            }
        }

        cell.innerHTML = mineCount > 0 ? mineCount : " ";

        //If zero mines, then reveal all adjacent cells
        if(mineCount == 0) {
            for(let i=Math.max(rowPos-1, 0); i<Math.min(rowPos+1, size-1); i++) {
                for(let j=Math.max(colPos-1, 0); j<Math.min(colPos+1, size-1); j++) {
                    let adjacentCell = grid.rows[i].cells[j];
                    if(adjacentCell.innerHTML == "") {
                        clickCell(adjacentCell);
                    }
                }
            }
        }
    }

Level completion

If the player completed the game without clicking on any mine, the level is complete.

    //Check game status
    const checkGameStatus = () => {
        let levelComplete = true;
        for(let i=0; i<size; i++) {
            for (let j=0; j<size; j++) {
                var cell = grid.rows[i].cells[j];
                if((cell.getAttribute("data-mine") == "false") && (cell.innerHTML == "")) {
                    levelComplete = false;
                }
            }
        }

        if(levelComplete) {
            alert("Congratulations, you won!");
            revealMines();
        }
    }

Conclusion

Well, that's about it. I had fun writing this game. Do you want me to build more games like this? Send me an email about it and I'll see what I can do from my end.

Have fun playing the game and oh, don't blow yourself up! 😜

Hope you liked reading this article!

Stay tuned for more!