DEV Community: RoryJZauner

Hugo vs Nuxt.js - A Blog-Off

RoryJZauner — Fri, 08 Apr 2022 12:23:59 +0000

I have been researching different Tools for blogging and two that have caught my eye were Hugo and Nuxt.js.

Being a developer who uses Vue.js quite heavily, Nuxt.js with its content module seemed like a good choice.

Hugo intrigued me because many say it is really fast and is based on Go, another language I am using more and more.

I thought the may be some of you are also looking at starting a blog or are looking to create a static site and would like to know more about two tools that you can use.

Requirements

Choosing a framework is all about looking at what you need and then deciding which one suits your needs the best.

Seeing as I also want to showcase my design-skills, I will be looking at how much I can customize my blog.

Static-Site-Generators

I would just like to get into what Static-Site-Generators are and why they seem to be getting really popular.

Not too long ago, you didn't have much choice when it came to creating your own blog - you had WordPress and then further being Drupal and Typo3 and others.

These were all heavy Content-Management-Systems that saved your posts in a database and retrieved them, when they were needed.

This made them a bit slow, because the client has to wait until a post has been retrieved from the database.

Enter Static Site Generators.

As the name suggests, we have no dynamic pieces of code here - we do not query a database for our posts.

The posts are written in markdown format and a the tool (Hugo, Nuxt.js, Next.js, Jekyll and many more) take that markdown and convert it to a static html page that gets presented to the user when it is called for.

That makes them really quick.

Additionally, because we have no server-side code that needs to be run, these sites can be run on any static-hosting service.

This also makes them really cost-effective alternatives to larger Content-Management-Systems.

Now let us get into our two contenders today.

Hugo

Seeing as I am on a Mac, it was really easy to setup using brew to install Hugo:

brew install Hugo

After installing Hugo, we can create a new site by first navigating to where we want our Site to live and the typing in the following command:

hugo new site <site-name>

Simply replace <site-name> with your project name - this will be used to create a directory with that exact name.

Once that has been completed, we can add a theme to our blog.

Themes

Like I already said in the introduction, I am looking to out my own stamp on the design of the site.

Therefore we won't be looking at the themes readily available for Hugo.

Of course your requirements are going differ from mine.

If you do find a theme that suits your need then that is great!

Creating your own theme for Hugo

In Hugo this is done by creating my own theme.

We first add a new theme using the following command:

hugo new theme <theme-name>

This will create the skeleton structure we need to create a new theme for our blog.

The first thing we need to do is create our partials. If you are familiar with components, then partials are exactly that. They are re-usable pieces of code that we can use to make our code less repetitive.

We will first ensure that our metadata is correct in our head.html file:

Next we can define how our header is going to be styled:

Next we can write the markup that will be displayed on our landing page:

Finally, we need to tell Hugo that we want our theme to be used:

And if we now start up our development server using Hugo server we will see the end result:

The partials work because they are added in our base.html file:

We can also create our own partials by placing them in the partials folder and then referencing them in our template.

There are other default base styles available such as list.html for rendering a list of posts and single.html, for displaying a single blog post.

Creating a new Post

We first define how our blog post should be structured. For this, we can use our single.html file:

We are pulling in the title and our content.

Now let us create some content!

Create a new blog post:

hugo new posts/testpost.md

This will create our markdown file in a new posts directory within content.

Let us add a bit of content to the file and then start our development server:

If we start up our development server hugo server -D we can see that our site is exposed at http://localhost:1313.

We can view our post by navigating to http://localhost:1313/posts/testpost:

That worked out rather easily.

I would like to add in the name of the author. To not have to do this every time we write a post, I am going to make use of partials.

Let us create a new file in our partials directory called post meta.html:

This will be used to display the author name.

Now we add this information to our single.html file:

Now if we look at the post in our browser we see that the author name we defined in our markdown file has also been rendered:

This way we can include additional information about our post, such as the date it was published on, tags etc.

Lastly, we can also style our posts.

In our static directory we can add a new main.css file in our css directory:

Nuxt.js

Now let us have a look at Nuxt.js.

To use Nuxt.js we can start by installing the necessary dependencies:

npx create-nuxt-app <project-name>

Again, <project-name>is the name that you choose for your project.

We will then be asked a few questions:

For this project I decided to stick to JavaScript because we won't be dealing with anything data-heavy.

As a UI-Framework I went for Tailwind, but you can choose whatever you feel most comfortable with.

We can then also add in the Content-Module that will form the basis of your blogging app.

We then choose our Rendering mode to be Universal (SSR / SSG) and our deployment target we set to Static (Static/Jamstack hosting).

We will use git as our version control system, since I have it already installed.

Then hit enter wait until everything is installed.

We can quickly check that everything works as expected by changing into our directory and starting up the development server:

cd <project-name>

npm run dev

After everything has compiled, you can navigate to http://localhost:3000 to see the website:

Great! Everything installed perfectly fine.

No we can start by creating a new post.

Creating a post

We can now quickly create a new post by first creating a new directory articles in our content directory that was created for us:

mkdir articles

And then create a new markdown file for us write our post:

touch content/articles/testpost.md

We can quickly add a few lines of markdown:

To expose our post we need to create a Vue component that will house our markdown.

For that, we can create a new directory in our pages directory called blog.

Inside blog, we can then create a new file called _slug.vue.

The file name allows us to make use of the params.slug parameter that we receive with from the vue-router. That way, when we finally navigate to http://localhost:3000/blog/testpost, we will see our freshly created page.

Before we can do that however, we need to prepare our newly created page:

In the JavaScript above we are fetching our articles directory we created earlier alongside our params that we need for our routing to work.

The content is then rendered using the <nuxt-content />component that takes in the article variable we created.

The markdown then gets rendered to the browser like this:

The styling here is rather scarce - apart from the basic Tailwind style, there is not much happening here.

Let us change that.

Styling

We already installed our tooling for getting started with styling our blog.

Nuxt.js as such does not have the theming-capabilities of Hugo, which does mean that we will need to develop our theme for our blog from scratch.

This does however give you more freedom to let your imagination run wild.

Do quickly show you how we can style our markdown, I made some changes to our _slug.vue file:

Using the nuxt-content class followed by the element-tag we want to select, we can directly apply style using the tailwind utility classes.

It gives our page a bit more structure:

Final Impressions

Both frameworks offer something different to developers.

Hugo makes setting up a static site very quickly - even when creating your own theme, Hugo helps you along the way.

Nuxt.js on the other hand gives you a lot more freedom to build the site you want. If you are familiar with Vue.js, then you should be able to pick up Nuxt.js pretty quickly.

One major difference between the two is that Hugo does have a set of themes that you can use for your blog - Nuxt.js does not. This does allow you to hit the ground running really quickly.

If you have tried either one for a side-project or your blog, I would like to know how you found working with them.

ASP.Net 5 Web API Basics with C#: A Tutorial

RoryJZauner — Mon, 20 Sep 2021 05:47:05 +0000

There are quite a few tools at your disposal, when it comes to creating an API for your product.

In this article we will be looking at .Net 5 as an option. For those of you who do not know, .Net 5 is the open-source framework from Microsoft for building products.

The framework can be used on any operating system. We can now enjoy the type-safety of C# on a Mac or using one of the awesome Linux-Distributions.

What you will learn:

Use the .Net SDK to create a new project
API Routing
Setting up Sqlite
API Controller Methods
Data Transfer Objects (DTOs)

What you will need

.Net 5 SDK installed (Official Website)
Visual Studio or Visual Studio Code installed

I am using Visual Studio Code in this tutorial and installed the recommended extension.

After that we are all set to start.

Creating a new Project

The SDK comes with a very handy command-line tool that we can use to scaffold just about any project we want.

We will be creating a new Web API Project using the following command:

dotnet new webapi -o webApiCrud

This will download and install all of the necessary dependencies and place them in a new project directory called webApiCrud.

Once everything is installed, we can open up our new project using your IDE of choice.

To check that everything works we can fire up our development server using the following command:

dotnet run

This will build our project and then make it available at https://localhost: 5001/.

You won't see anything, because the route "/" is not configured to return anything. To check that we are returning something from our API, we can run https://localhost:5001/weatherforecast/ and will see a response object.

Now that we have verified that everything works, let us have a look at the routing.

API Routing

If you already have experience with backend frameworks, you will know that routing is one of the more important aspects to get right. Routing essentially exposes the data you want to share with your client.

The first part of our routing takes place in the startup.cs file. It is here where our routing is configured:

app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });

This method indicates to the framework, that we are defining our routes within the controllers themselves.

.Net 5 APIs use what is referred to as attribute routing. This means we are defining the route on the controller or the action we want to use to handle the response when the URL is being called.

Working with our example route from above (https://localhost:5001/weatherforecast/) we know that we made a GET Request to that endpoint.

Seeing as each route is mapped to a controller and/or action, we know that we will find the action mapped to our GET Request in the WeatherForecastController.cs file.

Here we can see the following:

    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }

We can see the [ApiController] annotation that indicates to our program that this controller is used to return resources.

The [Route("[controller]")] is the part where our routing continues. It essentially defines a route that takes the controller name and removes the "controller" part. That would mean we are left with "weatherforecast" as our route name.

The final part of our routing is a few lines further down. It is the Http verb attribute [HttpGet] that tells our program that the action with this attribute responds to GET requests.

Putting it all together means that when the request was made to the endpoint https://localhost:5001/weatherforecast/, our program passed the request on to the WeatherForecastController who then passed it on to its Get() function.

What if we wanted all of our API routes to begin with "/api"?

We can simply change the Route attribute in our controller to get this done:

    [ApiController]
    [Route("api/[controller]")] //added "api"
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }

Now we need to stop the development server with Ctrl + C and re-build our project by running dotnet run again.

If we navigate to our old route https://localhost:5001/weatherforecast/ we will see no response. The resource is now available using our new route https://localhost:5001/api/weatherforecast/.

We can also define route attributes on the actions themselves. Let us assume we wanted to give our action the additional "all" at the end:

[ApiController]
    [Route("api/[controller]/")] //added "api" and "/"
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet("all")]   //defines additional part of name
        public IEnumerable<WeatherForecast> Get()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }

With this we can further specify the route we want our actions to map to.

We need to again stop the development server and re-build our project to see our changes. We can start up a watcher that will watch our project for changes and initiate a build as soon as we save our work. That way we won't have to stop and start each time we change something. To start our watcher we can run dotnet watch run.

Now if we navigate to https://localhost:5001/api/weatherforecast/all we can see our resource being returned.

Now that we have a better idea of how routing works, we can now have a look at setting up a development Sqlite database to persist our data to.

Setting up Sqlite

Be it for development or just to practice, Sqlite is a great way to get up and running quickly without having to set up a whole database system.

We will need to install the following packages:

dotnet tool install --global dotnet-ef

This we will need to create migrations and apply the changes to our database.

dotnet add package Microsoft.EntityFrameworkCore.Sqlite --version 5.0.9

Will allow us to connect to and use our Sqlite database.

Another package we will be needing for our tooling is dotnet add package Microsoft.EntityFrameworkCore.Design --version 5.0.9.

We first create a new Dbcontext class that will allow us to interact with our database.

I am going to create a new Models directory in our project root and in then directory I am going to place the ApiContext.cs file:

using Microsoft.EntityFrameworkCore;

namespace webApiCrud.Models
{
    public class ApiContext: DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        //place the models being used here
    }
}

You don't have to name your file like that, you can call it whatever you want to.

As you can see from the code above, we are going to be placing our models within the context class so that we can make use of them in our project.

We first need a model to add so in the Models directory create a new file called Note.cs:

namespace webApiCrud.Models
{
    public class Note
    {
        public int Id { get; set; }
        public string NoteTitle { get; set; }
        public string NoteText { get; set; }
    }
}

This is what our table in the database will look like. This is essentially the blueprint for our database.

Now we can update our ApiContext.cs:

using Microsoft.EntityFrameworkCore;

namespace webApiCrud.Models
{
    public class ApiContext: DbContext
    {
        public ApiContext(DbContextOptions<ApiContext> options)
            : base(options)
        {
        }

        public DbSet<Note> Notes { get; set; }
    }
}

Now we can make use of our model to not only create the structure of our database, but we can also use this to make queries.

The next step is to register our ApiContext.cs in our Startup.cs class so that our program is aware of it.

Our Startup.cs will look like this:

public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {

            services.AddControllers();

            services.AddDbContext<ApiContext>(options => options.UseSqlite(Configuration.GetConnectionString("DevDb")));

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "webApiCrud", Version = "v1" });
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                app.UseSwagger();
                app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "webApiCrud v1"));
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }

You will most likely encounter a missing directive error when writing these lines. In VSCode you can simply hover over the offending element and use the command Ctrl + . or on a Mac cmd + . to receive options as to what to import. In this case you will need to import using webApiCrud.Models for our ApiContext and using Microsoft.EntityFrameworkCore for the UseSqlite-method.

You may have noticed that we are using a connection string for our database. These can be found in appsetting.json:

{
  "ConnectionStrings": {
    "DevDb": "Data Source=./testdb.db"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*"
}

That takes care of that.

Once we have completed all of that we can start with our migrations.

Migration

These allow us to create and update our database structure without having to write SQL-Statements ourselves. It also makes sharing your work easier, because a new developer on your team will simply have to run the migrations to get the database structure they need.

With .Net 5 we use a toolset called Entity Framework Core. These tools allow us to manage our database structure and take care of migrating our changes.

The migration process involves first creating a migration file with our changes in it and then applying those changes to our database.

We can create a new migration using the following command:

dotnet ef migrations add InitialMigration

The last part of the command is the name of your migration - you can name it whatever you want.

On completion you will see a new directory in your project with the name "Migrations" which stores, you guessed it, all of your migrations.

We can now apply those changes to our database:

dotnet ef database update

The command will not only apply any database updates, but will also create our database file for us.

Now it is time to get started on some controller methods.

API Controller Methods

To being with, we will be needing a new controller class, so in our Controller directory, we can create a new NotesController.cs file with the following barebones structure:

using Microsoft.AspNetCore.Mvc;

namespace webApiCrud.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class NotesController : ControllerBase
    {

    }
}

As you can see we have the [ApiController] and the [Route("api/[controller]")] annotations. The routing defines as such would mean that the [controller] part will be replaced by the controller name, in this case by "notes".

We can now define each route and also specify what will happen, when that route is being called.

We first need to ensure that we can use our context we created previously within our controller:

using Microsoft.AspNetCore.Mvc;
using webApiCrud.Models;

namespace webApiCrud.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class NotesController : ControllerBase
    {
        private readonly ApiContext _context;

        public NotesController(ApiContext context)
        {
            _context = context;
        }
    }
}

We create a private readonly attribute called _context and then assign the context in the constructor of the controller class to our readonly _context. This way we have access to it throughout our controller.

We can now implement our create, read, update and delete methods:

using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using webApiCrud.Models;

namespace webApiCrud.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class NotesController : ControllerBase
    {
        private readonly ApiContext _context;

        public NotesController(ApiContext context)
        {
            _context = context;
        }

        [HttpPost("create")]
        public async Task<ActionResult<Note>> Create(Note note)
        {
            var new_note = new Note{
                NoteTitle = note.NoteTitle,
                NoteText = note.NoteText,
            };

            _context.Notes.Add(new_note);
            await _context.SaveChangesAsync();

            return CreatedAtAction(
                nameof(GetAll),
                new_note
            );

        }

        [HttpGet("all")]
        public async Task<ActionResult<IEnumerable<Note>>> GetAll()
        {
            var notes = await _context.Notes.Select(row => row).ToListAsync();

            return notes;
        }

        [HttpGet("{id}/get")]
        public async Task<ActionResult<Note>> GetById(int id)
        {
            var note = await _context.Notes.FindAsync(id);

            if(note == null)
            {
                return NotFound();
            }

            return note;
        }

        [HttpPut("{id}/update")]
        public async Task<ActionResult<Note>> Update(int id, Note note)
        {
            var noteToBeUpdated = await _context.Notes.FindAsync(id);

            if(noteToBeUpdated == null)
            {
                return NotFound();
            }

            noteToBeUpdated.NoteTitle = note.NoteTitle;
            noteToBeUpdated.NoteText = note.NoteText;

            await _context.SaveChangesAsync();

            return noteToBeUpdated;
        }

        [HttpDelete("{id}/delete")]
        public async Task<ActionResult<Note>> Delete(int id)
        {
            var noteToBeRemoved = await _context.Notes.FindAsync(id);

            if(noteToBeRemoved == null)
            {
                return NotFound();
            }

            _context.Notes.Remove(noteToBeRemoved);
            await _context.SaveChangesAsync();

            return NoContent();
        }
    }
}

Each method has its corresponding Http verb as annotation along with a specific route ending.

Each of our methods her has an "async" keyword, which tells our API that it can process request parallel to each other. For this, we use a Task<>which forms part of the task-based asynchronous patterns. Together they allow us to run our program asynchronously.

Inside our Task<> we have an ActionResult<> that defines the typical return type for controllers. All methods inside our controllers are referred to as actions, which is why the return type if these is called action result.

We then define what is being returned alongside the result. Here we are simply defining the model we want to return.

Interacting with our database

Inside each method, you will see that we use our _context every time we want to interact with our database.

In our POST request we create a new Note and use the data provided to us from the client.

We use Linq to create a new query:

_context.Notes.Add(new_note)

Linq is an awesome feature of C# that allows us to write these queries directly in our code.

I would definitely encourage you to learn more about Linq as it can make your life writing C# a lot easier.

In the example above we also used Linq queries such as Remove() for our delete route, FindAsync() to find a particular entry and the good old Select() to get all of our items from the database.

You will notice that each time we have an "Async" in our method name, we have an await at the start of the line. This is the way to write asynchronous lines of code inside our controller actions.

With the next line we write the data into our database:

await _context.SaveChangesAsync()

Only at this line are we actually doing anything in our database.

Testing our API

We can now check to see if everything works by first making sure we are not getting any build errors.

After that you can use different tools to mock requests. You can use curl which you should be able to use without having to set anything up.

The other firm favourite of mine is Postman. You can create an account and set everything up in Postman and then mock some requests.

It does not really matter which tool you choose, important is that you are comfortable using it and can test everything you want to test.

Updating our Database using Migrations

Now that we have our initial database structure, we want to update our table.

Let us assume we wanted to add information that tells us when the note was created and when it was last updated. These two timestamps are going to be two columns within our table:

using System;
using System.ComponentModel.DataAnnotations;

namespace webApiCrud.Models
{
    public class Note
    {
        public int Id { get; set; }
        public string NoteTitle { get; set; }
        public string NoteText { get; set; }

        [DataType(DataType.Date)]
        public DateTime CreatedOn { get; set; }

        [DataType(DataType.Date)]
        public DateTime UpdatedOn { get; set; }
    }
}

We are again going to be using annotations to specify that these fields are of type datetime.

Now then, how are we going to get these changes reflected in our database?

You guessed it - migrations.

Let us create a new migration that we can then use to update our database with:

dotnet ef migrations add AddsCreateAndUpdateDateFields

We can hit enter and a new migration file will be added to our project.

Now we can update our database:

dotnet ef database update

We have successfully updated our database without writing a single line of SQL!

We need to update our Controller methods to populate the new data fields we just created:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using webApiCrud.Models;

namespace webApiCrud.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class NotesController : ControllerBase
    {
        private readonly ApiContext _context;

        public NotesController(ApiContext context)
        {
            _context = context;
        }

        [HttpPost("create")]
        public async Task<ActionResult<Note>> Create(Note note)
        {
            var new_note = new Note{
                NoteTitle = note.NoteTitle,
                NoteText = note.NoteText,
                CreatedOn = DateTime.Now,
            };

            _context.Notes.Add(new_note);
            await _context.SaveChangesAsync();

            return CreatedAtAction(
                nameof(GetAll),
                new_note
            );

        }

        [HttpGet("all")]
        public async Task<ActionResult<IEnumerable<Note>>> GetAll()
        {
            var notes = await _context.Notes.Select(row => row).ToListAsync();

            return notes;
        }

        [HttpGet("{id}/get")]
        public async Task<ActionResult<Note>> GetById(int id)
        {
            var note = await _context.Notes.FindAsync(id);

            if(note == null)
            {
                return NotFound();
            }

            return note;
        }

        [HttpPut("{id}/update")]
        public async Task<ActionResult<Note>> Update(int id, Note note)
        {
            var noteToBeUpdated = await _context.Notes.FindAsync(id);

            if(noteToBeUpdated == null)
            {
                return NotFound();
            }

            noteToBeUpdated.NoteTitle = note.NoteTitle;
            noteToBeUpdated.NoteText = note.NoteText;
            noteToBeUpdated.UpdatedOn = DateTime.Now;

            await _context.SaveChangesAsync();

            return noteToBeUpdated;
        }

        [HttpDelete("{id}/delete")]
        public async Task<ActionResult<Note>> Delete(int id)
        {
            var noteToBeRemoved = await _context.Notes.FindAsync(id);

            if(noteToBeRemoved == null)
            {
                return NotFound();
            }

            _context.Notes.Remove(noteToBeRemoved);
            await _context.SaveChangesAsync();

            return NoContent();
        }
    }
}

It is as easy as that.

I would encourage you to create new model classes, migrate the changes and create new controller methods to further practice what we have covered so far in this article.

Lastly, we will tackle data transfer objects.

Data Transfer Objects

When working with our API in its current state, we see that we are working with all of the fields we defined in our model. Now this may well be what you are after, but there may be instances where we need all of the fields defined, but the client only needs a subset of those fields.

This is where data transfer objects come into play. They allow us to define the fields that our client is allowed to see and use.

Let us assume that the client only needs the title of the note as well as the id and the text. The timestamps are only meant for admin users or are added for analytical purposes.

We first create a new class where we define the fields that are going to be exposed as part of our DTO (Data Transfer Object):

namespace webApiCrud.Models
{
    public class NoteDTO
    {
        public int Id { get; set; }
        public string NoteTitle { get; set; }
        public string NoteText { get; set; }
    }
}

Our new NoteDTO class holds our fields.

We can now update our controller actions to use the new DTO instead of our whole model:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using webApiCrud.Models;

namespace webApiCrud.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class NotesController : ControllerBase
    {
        private readonly ApiContext _context;

        public NotesController(ApiContext context)
        {
            _context = context;
        }

        [HttpPost("create")]
        public async Task<ActionResult<NoteDTO>> Create(Note note)
        {
            var new_note = new Note{
                NoteTitle = note.NoteTitle,
                NoteText = note.NoteText,
                CreatedOn = DateTime.Now,
            };

            _context.Notes.Add(new_note);
            await _context.SaveChangesAsync();

            return CreatedAtAction(
                nameof(GetAll),
                NoteDTO(new_note)
            );

        }

        [HttpGet("all")]
        public async Task<ActionResult<IEnumerable<NoteDTO>>> GetAll()
        {
            var notes = await _context.Notes.Select(row => NoteDTO(row)).ToListAsync();

            return notes;
        }

        [HttpGet("{id}/get")]
        public async Task<ActionResult<NoteDTO>> GetById(int id)
        {
            var note = await _context.Notes.FindAsync(id);

            if(note == null)
            {
                return NotFound();
            }

            return NoteDTO(note);
        }

        [HttpPut("{id}/update")]
        public async Task<ActionResult<NoteDTO>> Update(int id, Note note)
        {
            var noteToBeUpdated = await _context.Notes.FindAsync(id);

            if(noteToBeUpdated == null)
            {
                return NotFound();
            }

            noteToBeUpdated.NoteTitle = note.NoteTitle;
            noteToBeUpdated.NoteText = note.NoteText;
            noteToBeUpdated.UpdatedOn = DateTime.Now;

            await _context.SaveChangesAsync();

            return NoteDTO(noteToBeUpdated);
        }

        [HttpDelete("{id}/delete")]
        public async Task<ActionResult<NoteDTO>> Delete(int id)
        {
            var noteToBeRemoved = await _context.Notes.FindAsync(id);

            if(noteToBeRemoved == null)
            {
                return NotFound();
            }

            _context.Notes.Remove(noteToBeRemoved);
            await _context.SaveChangesAsync();

            return NoContent();
        }

        private static NoteDTO NoteDTO(Note note) =>
        new NoteDTO
        {
            Id = note.Id,
            NoteTitle = note.NoteTitle,
            NoteText = note.NoteText
        };
    }
}

At the end of our controller, we have a small function that we can use to return an instance of our DTO instead of the full model.

If you now test your API you will see that the timestamps have been removed from the response and we returning only the fields we defined as part of our DTO.

Conclusion

That is it as far as basics go when it comes to using .Net 5. There is obviously so much more to know and I would definitely encourage you to build a few small projects and experiment.

Let me know in the comments if you are currently learning C# and .Net 5 and what your experience has been like so far!

Getting started with Laravel 8, Vue 3 and Tailwind

RoryJZauner — Fri, 27 Aug 2021 06:46:43 +0000

Laravel is one of the most popular web frameworks you can use for your next project. Having used Laravel extensively myself I can honestly say, the developer experience is extremely good.

Vue has a long-standing history with Laravel and quite a bit of its popularity comes from the Laravel community heavily using Vue for their frontend work.

As such I thought it would be interesting to see how we can setup the latest installment of Vue in Laravel. Just for fun, we will also setup Tailwind, for those of you curious to see how that works.

Learnings

Setup a Laravel project using Composer
Install and configure Vue 3
Install and configure TailwindCSS
Setup a Sqlite database for development

Setup a Laravel Project using Composer

There are a few options when it comes to installing Laravel. We will be using Composer to setup the Laravel framework.

For this you will need to install the following:

And for development you will be needing PHP 8.

If you are asking yourself how much JavaScript you need to know to use Vue, I have an article that details exactly this.

After installing all of this, we can simply run the following command to scaffold a complete Laravel project:

composer create-project Laravel/laravel <app-name>

In our case I will be using the following command:

composer create-project Laravel/laravel Laravel-vue

This will then install everything we need.

Great! Now onto installing Vue 3.

Install and configure Vue 3

If you have been using Laravel from 6.x onward, you may well have come across the Laravel/ui package, with which we could install Bootstrap as well as React or Vue.

For Vue 3 there is not a package as of time of writing, but there is a rather easy way of doing this.

Let us first install the dependencies needed for Vue 3:

npm install --save vue@next && npm install --save-dev vue-loader@next

After that we need to tell webpack to compile our vue files as well. WE can do this be opening the webpack.mix.js file and add the following line:



const mix = require("laravel-mix");

mix.js("resources/js/app.js", "public/js")
    .vue() //new
    .postCss("resources/css/app.css", "public/css", [
        //
    ]);

I usually run npm install followed by npm run dev.

Here you will likely get an error the first time compiling that, because npm has installed a missing package for us:

Simply re-run npm run dev and everything compiles without any errors.

We can start our project by running php artisan serve that start the built-in PHP development server on port 8000. If you now go to localhost:8000 you will see the following:

Laravel is done, now to get Vue setup.

Create our Vue project

We haven't actually done anything with our Vue setup. Let us change that by creating a root component that will house our entire Vue app.

Create a new App.vue file in the resources/js folder with the following markup:



<template>
    <div>
        <h1>Vue 3 App</h1>
    </div>
</template>

A very simple Vue app with a heading.

Now we need to adapt our app.js in resources/js to make use of our vue file:



//resources/js/app.js

import { createApp } from "vue";

import App from "./App.vue";

createApp(App).mount("#app");

require("./bootstrap");

Here we are first importing the createApp() method that is new to Vue developers. With this we can create a new Vue instance.

We then import our Vue file and create a new Vue instance and mount it on an element with the id "app".

Now let us create an element that has that id. To do this, we can remove the standard markup found in our welcome.blade.php file and replace it with this:



<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>Laravel</title>

        <!-- Fonts -->
        <link href="https://fonts.googleapis.com/css2?family=Nunito:wght@400;600;700&display=swap" rel="stylesheet">
    </head>
    <body>
        <div id="app"></div>
    </body>
    <script src="{{ asset('js/app.js') }}"></script>
</html>

As you can see, we have a div with the id app that will be replaced by our Vue app.

Below we have a script tag that references not the app.js we have in resources/js, but within our public/js folder. This file is the end result of our webpack build process.

Before we do that, we need to once again run a build process because we have not actually processed the Vue files we created.

To avoid having to run npm run dev every time we make a change, we can run npm run watch that allows us to trigger a build process as soon as we save the changes.

You should now be able to see our heading:

You may need to restart the development server, if you are getting errors.

Install and configure TailwindCSS

TailwindCSS has become very popular, not only with Laravel developers, but also with Vue developers.

Tailwind allows you to create apps and website without ever having to leave your html.

First we need to install the necessary dependencies:

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

We can now create a tailwind config file that we can use to extend the default TailwindCSS settings:

npx tailwindcss init

This will create a new tailwind.config.js in our project.

We then need to configure webpack to process the tailwind installation:



const mix = require("laravel-mix");

mix.js("resources/js/app.js", "public/js")
    .vue()
    .postCss("resources/css/app.css", "public/css", [require("tailwindcss")]);

To be able to use the tailwind utility classes in your project, we can simply add it to our resources/css/app.css file:



@tailwind base;
@tailwind components;
@tailwind utilities;

These tailwind directives are picked up by our webpack build processes and the tailwind utility classes are placed within the final css file produced.

We can finally add the stylesheet to our welcome.blade.php to use the styles in our project:



<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>Laravel</title>

        <!-- Fonts -->
        <link href="https://fonts.googleapis.com/css2?family=Nunito:wght@400;600;700&display=swap" rel="stylesheet">
        <link rel="stylesheet" href="{{ asset('css/app.css') }}">
    </head>
    <body>
        <div id="app"></div>
    </body>
    <script src="{{ asset('js/app.js') }}"></script>
</html>

You may again have to restart the development server and/or restart the build process.

We can now add a few utility classes to our component to test that everything works:



<template>
    <div class="flex justify-center mt-24">
        <h1 class="text-2xl font-bold text-gray-700">Vue 3 App</h1>
    </div>
</template>

The result being:

Awesome! We can now style our project using TailwindCSS.

We can now go about setting up a Sqlite database for our development.

Setting up Sqlite

In our database folder we can create a new file called database.sqlite. This will be our database for development purposes. It is a very lightweight option and every handy, particularly for learning purposes.

We now need to configure Laravel to use our new database file. To do this we need to update our .env file:



DB_CONNECTION=sqlite
DB_DATABASE=database/database.sqlite

The default setup can be replaced with the one above. To test this setup we can run a migration using the following command:

php artisan migrate

I usually restart the development server before running the migrate command. If all goes well, you can see the following output:

That is it!

You now have a Laravel project ready for further development.

Conclusion

I hope this article provides you with the necessary information to build your own app that uses Laravel 8 and Vue 3 with TailwindCSS.

Let me know in the comments what frameworks you are using in your projects.

I'd love to know!

9 Tips for getting started with Vue.js: A Guide

RoryJZauner — Thu, 12 Aug 2021 20:26:38 +0000

When I was first introduced to the world of frontend development, I was quickly overwhelmed by the amount of things I needed to know. Or at least I thought I needed to know.

When it came down to learning a JavaScript framework, I remember feeling a bit lost.

There was a lot of information and tutorials and how-tos out there, I simply didn't know where to start.

If you are feeling just as overwhelmed on your journey to learning Vue.js, then I hope this article will help she some light.

Learn and keep learning JavaScript

This may be obvious, but I would definitely advise you to get a good foundation by learning JavaScript.

Vue.js uses JavaScript, so gaining a good understanding of JavaScript will help you learn Vue.js more readily.

I have written an article on what to look out for when starting to learn JavaScript and what aspects of the language are helpful to those starting to learn to write singe-page-applications.

Vue.js Documentation

The first part you will often hear from senior engineers. But reading the documentation to Vue.js is very helpful. In fact, they have been created in such a way, that within one day, you can familiarise yourself with all of the key concept of the core Vue library.

They have been created will lots of care and will definitely help get you started using Vue.

A complete guide of different concepts can be found in the documentation, but here is a quick overview to whet your appetite:

Vue-directives such as v-if, v-else, v-for etc.
Handling user input using v-model
Handling user-initiated events such as clicks and typing
Props
Lifecycle Methods such as mounted()
Structure of Vue Single-File-Components as these are often the ones you will be working on

Build small projects

While you are reading, build something with the topic your are currently on. It does not have to be the next unicorn startup you are building.

Start small.

The more you read, the more the learning accumulate and the bigger your little application can get.

By applying your knowledge your are ensuring that when it comes down to using that knowledge, your fingertips are ready for it.

Have a look at the Style Guide

This makes the documentation for Vue even more special. It has a style guide. It gives you tips and tricks to make your Vue code more clean and readable.

It also helps to keep Vue code consistent across different projects, allowing a new member of your team to pick up the code a lot quicker.

Experiment with Vue

There often seems to be this image that Vue can only be used to build single-page-applications.

While this may be one of its primary use-cases, Vue can also be used as a replacement for jQuery in that legacy applications everyone on the team keeps going on about.

Experiment with the library. Try to build something, get stuck, read the docs, figure it out and there you go. Building things and experimenting with new technologies is a great way to get a grasp on them.

The Vue-Ecosystem

Once you have gotten a good look at the core Vue library, you will eventually read about Vue-Router

Vue-Router

Similar to React, Vue also has its own routing library that gives us that single-page-effect by removing the reloading of the page when navigating from one to the other.

I would again read through the documentation and get down to coding something up using the routing library.

It will certainly help you gain a better understanding of how too solve problems using it.

Vuex

This is a bit more complex, because it involves something called state management.

Whenever you find yourself having to pass data from one component to the other, props tend to be go-to solution.

But as the application grows and the data flow starts to go in more than one direction and you find yourself having to make extra requests to your backend to get the same data you needed in your first component, then the solution you are looking for is called state management.

For Vue this usually means Vuex.

The documentation will again get you up-to-speed with the library and what state, getters, mutations and actions are.

Vuex may well be something that you will use on medium-sized projects, as it simplifies how you manage your data and ensures your data flow is kept clean and easily maintained.

StackOverflow is your best friend

This is certainly nothing new to those that have gotten stuck and needed to consult the collective intelligence on StackOverflow.

It really will help you get rid of that roadblock.

Generally, if you have question regarding anything in Vue, just have a look and ask them.

Vue.js has a great community and they are always ready to help any newcomers to the framework quickly find their way.

Application Architecture

Once you start building more complex applications, the more the actual architecture of your app will begin to play role.

How you structure your files and folders, will play a huge role not only regarding productivity, but also how well you can maintain the codebase.

Nuxt.js is a great tool for building larger-sized Vue projects. It uses Vue.js as a base and takes care of a lot of basics, such as routing, for you.

This allows you to focus more on the actual app and helps keep your codebase organised and clean for the next developer.

Testing

This topic tends to divide teams.

The one team is all for testing, the other sees it as unnecessary code needing to be written.

For me, testing has helped me write only the code I really needed. It has forced me to think about how everything needs to work, before I even wrote a single line of code.

That ensures that my components and pages only contain the code I really need.

It also makes refactoring so much easier. You can make changes to functions that have existed since the dawn of time and by quickly running your test, you can assess whether or not something broke.

That way you don't have to check every single feature in the entire application that uses this function, just to check if something went wrong.

That is very time-consuming and not an efficient use of your time.

Writing test may be a pain at first, but they are well-worth it when it comes down to it.

Styling

After all of that, it may well be time to have a look at CSS-Frameworks the language brings with it.

You can use whatever CSS-Framework you like, but there are two that I feel are particularly popular: BootstrapVue and TailwindCSS.

BootstrapVue, as the name suggests, is the third-parts package to allow Vue developers access to the Bootstrap library. The reason being that Vue and jQuery do not get along very well and Bootstrap 4.x uses jQuery for the JavaScript needs.

With Bootstrap 5.x this is no longer the case and we could happily omit BoostrapVue from our package.json, but there is more to the library than meets the eye.

BoostrapVue

BoostrapVue also has many more components, specifically created for Vue. One that I regularly use is the modal window.

Now it may not be such a big deal to write your own logic to create a modal window, it certainly takes a bit of time to get everything right.

TailwindCSS

This appears to be a rising star among css frameworks and has gained some fame within the vue community.

The concept behind it is awesome in my opinion and makes frontend work a lot smoother.

Unlike Bootstrap and BootstrapVue, there are no flashy modals or pre-configured data tables you can use here. You use each class to add a new rule to your element. The sum of these classes will make your component.

It has everything you need to write your entire css without ever having to leave your html.

Both of these are great and are great to at least experiment with to see what each of them is about.

Nothing will substitute a good solid foundation on CSS.

Conclusion

I hope this gives you a good overview of the different tips you can use to make your learning of Vue easier.

Let me know in the comments what tips I may have missed.

Learn the basics of Vue.js by building a simple CRUD App: A Tutorial

RoryJZauner — Thu, 05 Aug 2021 05:56:13 +0000

In this post we will be looking at writing a single-page application using Vue 2.x as our framework.

The aim of this app will be to manage customer data, a very basic CRM-system.

Vue has gained popularity over the years and is a very quick framework to pick up. The awesome Vue-Team has released Vue 3.x, however, the basics used in Vue 2.x can be transferred to Vue 3.

What we will be taking a look at

Project Setup using the Vue CLI
Creating Components
Styling with BootstrapVue
Json-Server for API Mocking
Making Http-Requests
Conditional Rendering of Elements
Displaying Data
Handling User Input

If you want to follow along, you will need the following installed on your machine:

Nodejs
Vue CLI
Your trusty IDE (I am using VSCode, but you can use whatever you want)

If you are unsure as to whether or not to start with a single-page-framework such as Vue or React, then you can have a look at my other article where I talk about the JavaScript features that helped me become more productive with Vue and React.

Project Setup

Using the Vue CLI allows us to quickly scaffold an entire Vue projects with a few commands. We can also manage our Vue-related dependencies such as Vue-Router and Vuex using the CLI.

To start with, run the following command:

vue create vue-tutorial

Then let us manually select features:

And then let us include the Vue-Router:

Then we can configure the rest to be:

I won't be saving this setup, but you can if you want to use this in future projects.

Then let us cd into the directory and run. npm run serve which will start our development server. This allows us to check that everything is working as expected before we continue with our project setup.

Now that we have that, we can have a look at setting up Bootstrap for our project.

We first install the dependencies:

npm install bootstrap bootstrap-vue

After those have been installed, we need to open up our project in our IDE and open the main.js file.

Here we will add in a couple of lines that tell Vue to use our freshly installed Bootstrap and BootstrapVue dependencies:

import Vue from "vue";
import App from "./App.vue";
import router from "./router";
import { BootstrapVue, IconsPlugin } from "bootstrap-vue";

// Import Bootstrap an BootstrapVue CSS files (order is important)
import "bootstrap/dist/css/bootstrap.css";
import "bootstrap-vue/dist/bootstrap-vue.css";

// Make BootstrapVue available throughout your project
Vue.use(BootstrapVue);
Vue.use(IconsPlugin);

Vue.config.productionTip = false;

new Vue({
  router,
  render: (h) => h(App),
}).$mount("#app");

You may have noticed that there is also a IconsPlugin that we are adding. This allows us to use the Bootstrap Icons throughout our entire project.

At this point I like to just restart the development server and recompile everything. So simply hit ctrl + C and run npm run serve once more to get everything up and running again.

Awesome! Setup complete, we can now start creating our component and pages.

Mocking the Backend

As a frontend engineer, you may well find that the api endpoints you are going to be using not quite ready yet.

In such cases, we can use json-server.

Once installed, it allows us to create, read, update and delete records without having to write a single line of backend code.

To install it, we can use:

npm install -g json-server

Then we create a new file called db.json directly on the root directory and fill it with the data we want:

{
  "customers": [
    {
      "id": 1,
      "company_name": "My awesome Company",
      "contact_firstname": "Jane",
      "contact_lastname": "Doe",
      "contact_email": "jdoe@awesome.com",
      "acquired_on": "2021-04-03",
      "customer_status": "active"
    },
    {
      "id": 2,
      "company_name": "Company ABC",
      "contact_firstname": "Sarah",
      "contact_lastname": "Jane",
      "contact_email": "sjane@coabc.com",
      "acquired_on": "2021-06-03",
      "customer_status": "active"
    },
    {
      "id": 3,
      "company_name": "Company xYZ",
      "contact_firstname": "Tim",
      "contact_lastname": "Hane",
      "contact_email": "thane@coxyz.com",
      "acquired_on": "2020-12-03",
      "customer_status": "active"
    },
    {
      "id": 4,
      "company_name": "Video Production Consulting",
      "contact_firstname": "Miriam",
      "contact_lastname": "Doe",
      "contact_email": "mdoe@vidprod.com",
      "acquired_on": "2020-07-05",
      "customer_status": "inactive"
    },
    {
      "id": 5,
      "company_name": "Code Writers",
      "contact_firstname": "Jill",
      "contact_lastname": "Wade",
      "contact_email": "jwade@codewrit.com",
      "acquired_on": "2020-04-03",
      "customer_status": "active"
    }
  ]
}

Now we can make these records available, by running the following command:

json-server --watch db.json

This will allow us to send and receive data by visiting "http://localhost:3000/customers/".

Great!

Now we can create our application to interact with this mock-api.

Creating Components and Pages

Let us start with our topmost component: App.vue.

Here we will remove the style-tag at the end and the navigation:

<template>
  <div>
    <header-bar></header-bar>
    <b-container>
      <b-row class="mt-5">
        <router-view />
      </b-row>
    </b-container>
  </div>
</template>

<script>
import HeaderBar from "@/components/HeaderBar.vue";

export default {
  components: {
    HeaderBar,
  },
};
</script>

As you can see we have a HeaderBar.vue component that we haven't created yet.

Head over to your components directory and create a new file called HeaderBar.vue with the following code:

<template>
  <b-navbar toggleable="lg" type="dark" variant="primary">
    <b-container>
      <b-row class="text-white">
        <b-col>
          <b-icon-people-fill class="h2"></b-icon-people-fill>
        </b-col>
        <b-col>
          <span class="h3">CRM</span>
        </b-col>
      </b-row>
    </b-container>
  </b-navbar>
</template>

<script>
export default {
  name: "HeaderBar",
};
</script>

This will give us a nice header along the top of our app with a logo and some text:

You have created your first Vue component! That's awesome!

As you can see, we are able to seamlessly add icons to our design without having to go through too much effort in setting everything up.

We can now have a look at removing the default code from our Home.vue and start building our app.

This will be our overview page. We can search for customers and also have a quick scan of their data.

We first need to install axis for us to be able to send and receive data from our backend:

npm install axios

After that, we can import it whenever and wherever we need it.

Now we can create a simple data-table component:

<template>
  <div>
    <b-row>
      <data-table></data-table>
    </b-row>
  </div>
</template>

<script>
import DataTable from "@/components/DataTable.vue";

export default {
  name: "Home",
  components: {
    DataTable,
  },
};
</script>

And we can now create our DataTable.vue component with a CustomerOverview component:

<template>
  <div>
    <b-row>
      <b-alert v-model="showSuccessAlert" variant="success" dismissible>
        {{ alertMessage }}
      </b-alert>
    </b-row>
    <b-row>
      <customer-overview
        :totalCustomers="numberOfCustomers"
        :activeCustomers="activeCustomers"
        @totalCustomersIsActive="setFilterTotalIsActive"
        @activeCustomerIsActive="setFilterActiveIsActive"
      ></customer-overview>
    </b-row>
    <b-row class="mt-3">
      <b-card>
        <b-row align-h="between">
          <b-col cols="6">
            <h3>{{ tableHeader }}</h3>
          </b-col>
          <b-col cols="2">
            <b-row>
              <b-col>
                <b-button
                  variant="primary"
                  id="show-btn"
                  @click="showCreateModal"
                >
                  <b-icon-plus class="text-white"></b-icon-plus>
                  <span class="h6 text-white">New Customer</span>
                </b-button>
              </b-col>
            </b-row>
          </b-col>
        </b-row>
        <b-row class="mt-3">
          <b-table
            striped
            hover
            :items="items"
            :fields="fields"
            class="text-center"
          >
            <template #cell(contact_name)="data">
              {{
                `${data.item.contact_firstname} ${data.item.contact_lastname}`
              }}
            </template>
            <template #cell(customer_status)="data">
              <b-icon-bookmark-check-fill
                variant="success"
                v-if="data.item.customer_status === 'active'"
              ></b-icon-bookmark-check-fill>
              <b-icon-bookmark-x-fill
                variant="danger"
                v-else
              ></b-icon-bookmark-x-fill>
            </template>
            <template #cell(actions)="data">
              <b-row>
                <b-col cols="7">
                  <b-icon-pencil-square
                    class="action-item"
                    variant="primary"
                    @click="getRowData(data.item.id)"
                  ></b-icon-pencil-square>
                </b-col>
                <b-col cols="1">
                  <b-icon-trash-fill
                    class="action-item"
                    variant="danger"
                    @click="showDeleteModal(data.item.id)"
                  ></b-icon-trash-fill>
                </b-col>
              </b-row>
            </template>
          </b-table>
        </b-row>
      </b-card>
    </b-row>

    <!-- Modal for adding new customers -->
    <b-modal
      ref="create-customer-modal"
      size="xl"
      hide-footer
      title="New Customer"
    >
      <create-customer-form
        @closeCreateModal="closeCreateModal"
        @reloadDataTable="getCustomerData"
        @showSuccessAlert="showAlertCreate"
      ></create-customer-form>
    </b-modal>

    <!-- Modal for updating customers -->
    <b-modal
      ref="edit-customer-modal"
      size="xl"
      hide-footer
      title="Edit Customer"
    >
      <edit-customer-form
        @closeEditModal="closeEditModal"
        @reloadDataTable="getCustomerData"
        @showSuccessAlert="showAlertUpdate"
        :customerId="customerId"
      ></edit-customer-form>
    </b-modal>

    <!-- Delete Customer Modal -->
    <b-modal
      ref="delete-customer-modal"
      size="md"
      hide-footer
      title="Confirm Deletion"
    >
      <delete-customer-modal
        @closeDeleteModal="closeDeleteModal"
        @reloadDataTable="getCustomerData"
        @showDeleteAlert="showDeleteSuccessModal"
        :customerId="customerId"
      ></delete-customer-modal>
    </b-modal>
  </div>
</template>

<script>
import axios from "axios";
import CustomerOverview from "@/components/CustomerOverview.vue";
import CreateCustomerForm from "@/components/CreateCustomerForm.vue";
import EditCustomerForm from "@/components/EditCustomerForm.vue";
import DeleteCustomerModal from "@/components/DeleteCustomerModal.vue";

export default {
  components: {
    CustomerOverview,
    CreateCustomerForm,
    EditCustomerForm,
    DeleteCustomerModal,
  },
  data() {
    return {
      // Note 'isActive' is left out and will not appear in the rendered table

      fields: [
        {
          key: "company_name",
          label: "Company Name",
          sortable: false,
        },
        {
          key: "contact_name",
          label: "Contact Name",
          sortable: false,
        },
        {
          key: "contact_email",
          label: "Contact E-Mail",
          sortable: false,
        },
        {
          key: "customer_status",
          label: "Customer Status",
          sortable: false,
        },
        "actions",
      ],
      items: [],
      numberOfCustomers: 0,
      activeCustomers: 0,
      activeCustomersData: [],
      customerId: 0,
      companySearchTerm: "",
      tableHeader: "",
      showSuccessAlert: false,
      alertMessage: "",
    };
  },
  mounted() {
    this.getCustomerData();
  },
  methods: {
    showCreateModal() {
      this.$refs["create-customer-modal"].show();
    },
    closeCreateModal() {
      this.$refs["create-customer-modal"].hide();
    },
    getCustomerData() {
      axios
        .get("http://localhost:3000/customers/")
        .then((response) => {
          this.tableHeader = "Total Customer";
          this.items = response.data;
          this.numberOfCustomers = response.data.length;
          this.activeCustomersData = response.data.filter(
            (item) => item.customer_status === "active"
          );
          this.activeCustomers = this.activeCustomersData.length;
        })
        .catch((error) => {
          console.log(error);
        });
    },
    getRowData(id) {
      this.$refs["edit-customer-modal"].show();
      this.customerId = id;
    },
    closeEditModal() {
      this.$refs["edit-customer-modal"].hide();
    },
    setFilterTotalIsActive() {
      this.tableHeader = "Total Customers";
      this.getCustomerData();
    },
    setFilterActiveIsActive() {
      this.tableHeader = "Active Customers";
      this.items = this.activeCustomersData;
    },
    showAlertCreate() {
      this.showSuccessAlert = true;
      this.alertMessage = "Customer was created successfully!";
    },
    showAlertUpdate() {
      this.showSuccessAlert = true;
      this.alertMessage = "Customer was updated successfully";
    },
    showDeleteModal(id) {
      this.$refs["delete-customer-modal"].show();
      this.customerId = id;
    },
    closeDeleteModal() {
      this.$refs["delete-customer-modal"].hide();
    },
    showDeleteSuccessModal() {
      this.showSuccessAlert = true;
      this.alertMessage = "Customer was deleted successfully!";
    },
  },
};
</script>

<style>
.action-item:hover {
  cursor: pointer;
}
</style>

And our CustomerOverview.vue component will look like this:

<template>
  <div>
    <b-row class="text-center">
      <b-col>
        <div
          class="filter-card p-3"
          :class="{
            'bg-active-filter': totalIsActive,
            'bg-light': !totalIsActive,
          }"
          @click="totalCustomersIsActiveFilter"
        >
          <h6>Total Customers</h6>
          <h4>
            <strong>{{ totalCustomers }}</strong>
          </h4>
        </div>
      </b-col>
      <b-col>
        <div
          class="filter-card p-3"
          :class="{
            'bg-active-filter': activeIsActive,
            'bg-light': !activeIsActive,
          }"
          @click="activeCustomersIsActiveFilter"
        >
          <h6 class="text-secondary">Active Customers</h6>
          <h4>
            <strong>{{ activeCustomers }}</strong>
          </h4>
        </div>
      </b-col>
    </b-row>
  </div>
</template>

<script>
export default {
  name: "CustomerOverview",
  props: {
    totalCustomers: Number,
    activeCustomers: Number,
  },
  data() {
    return {
      totalIsActive: true,
      activeIsActive: false,
    };
  },
  methods: {
    totalCustomersIsActiveFilter() {
      this.totalIsActive = true;
      this.activeIsActive = false;
      this.$emit("totalCustomersIsActive");
    },
    activeCustomersIsActiveFilter() {
      this.totalIsActive = false;
      this.activeIsActive = true;
      this.$emit("activeCustomerIsActive");
    },
  },
};
</script>

<style>
.filter-card:hover {
  cursor: pointer;
  text-decoration: underline;
}

.bg-active-filter {
  background-color: #e9f1fe;
  color: #074297;
}
</style>

We also have three modals that are used to add new customers to our list, one for updating existing customers and one for removing existing records:

<!-- Modal for adding new customers -->
    <!-- Modal for adding new customers -->
    <b-modal
      ref="create-customer-modal"
      size="xl"
      hide-footer
      title="New Customer"
    >
      <create-customer-form
        @closeCreateModal="closeCreateModal"
        @reloadDataTable="getCustomerData"
        @showSuccessAlert="showAlertCreate"
      ></create-customer-form>
    </b-modal>

    <!-- Modal for updating customers -->
    <b-modal
      ref="edit-customer-modal"
      size="xl"
      hide-footer
      title="Edit Customer"
    >
      <edit-customer-form
        @closeEditModal="closeEditModal"
        @reloadDataTable="getCustomerData"
        @showSuccessAlert="showAlertUpdate"
        :customerId="customerId"
      ></edit-customer-form>
    </b-modal>

<!-- Delete Customer Modal -->
    <b-modal
      ref="delete-customer-modal"
      size="md"
      hide-footer
      title="Confirm Deletion"
    >
      <delete-customer-modal
        @closeDeleteModal="closeDeleteModal"
        @reloadDataTable="getCustomerData"
        @showDeleteAlert="showDeleteSuccessModal"
        :customerId="customerId"
      ></delete-customer-modal>
    </b-modal>

As you can see, we are importing the forms themselves, meaning that we need to create a CreateCustomerForm.vue:

<template>
  <b-form class="mt-3">
    <b-row>
      <b-row>
        <h4 class="text-secondary">Contact Details</h4>
      </b-row>
      <b-col cols="6">
        <b-form-group id="first-name" label="First Name" label-for="first-name">
          <b-form-input
            id="first-name"
            type="text"
            placeholder="First Name"
            v-model="customer.contact_firstname"
          ></b-form-input>
        </b-form-group>
      </b-col>
      <b-col cols="6">
        <b-form-group id="last-name" label="Last Name" label-for="last-name">
          <b-form-input
            id="last-name"
            type="text"
            placeholder="Last Name"
            v-model="customer.contact_lastname"
          ></b-form-input>
        </b-form-group>
      </b-col>
    </b-row>
    <b-row class="mt-3">
      <b-col cols="6">
        <b-form-group id="email" label="E-Mail" label-for="email">
          <b-form-input
            id="email"
            type="email"
            placeholder="example@crm.com"
            v-model="customer.contact_email"
          ></b-form-input>
        </b-form-group>
      </b-col>
    </b-row>
    <b-row class="mt-5">
      <h4 class="text-secondary">Company Details</h4>
    </b-row>
    <b-row>
      <b-col cols="4">
        <b-form-group
          id="company_name"
          label="Company Name"
          label-for="company_name"
        >
          <b-form-input
            id="company_name"
            type="text"
            placeholder="XYZ Industries"
            v-model="customer.company_name"
          ></b-form-input>
        </b-form-group>
      </b-col>
    </b-row>
    <b-row>
      <b-col cols="4">
        <b-form-group
          id="acquired_on"
          label="Acquired On"
          label-for="acquired_on"
        >
          <b-form-input
            id="acquired_on"
            type="date"
            v-model="customer.acquired_on"
          ></b-form-input>
        </b-form-group>
      </b-col>
    </b-row>
    <b-row class="mt-2">
      <b-form-checkbox
        id="customer_status"
        v-model="customer.customer_status"
        name="customer-status"
        value="active"
        unchecked-value="inactive"
      >
        Customer is active
      </b-form-checkbox>
    </b-row>
    <b-row class="mt-4">
      <b-col cols="3">
        <b-button variant="primary" class="px-5" @click="addNewCustomer"
          >Add Customer</b-button
        >
      </b-col>
      <b-col>
        <b-button variant="warning" @click="triggerClose">Close</b-button>
      </b-col>
    </b-row>
  </b-form>
</template>

<script>
import axios from "axios";

export default {
  name: "CreateCustomerModal",
  data() {
    return {
      customer: {},
    };
  },
  methods: {
    triggerClose() {
      this.$emit("closeCreateModal");
    },
    addNewCustomer() {
      axios
        .post("http://localhost:3000/customers/", this.customer)
        .then((response) => {
          console.log(response.data);
          this.$emit("closeCreateModal");
          this.$emit("reloadDataTable");
          this.$emit("showSuccessAlert");
        })
        .catch((error) => {
          console.log(error);
        });
    },
  },
};
</script>

And EditCustomerForm.vue component:

<template>
  <b-form class="mt-3">
    <b-row>
      <b-row>
        <h4 class="text-secondary">Contact Details</h4>
      </b-row>
      <b-col cols="6">
        <b-form-group id="first-name" label="First Name" label-for="first-name">
          <b-form-input
            id="first-name"
            type="text"
            placeholder="First Name"
            v-model="customer.contact_firstname"
          ></b-form-input>
        </b-form-group>
      </b-col>
      <b-col cols="6">
        <b-form-group id="last-name" label="Last Name" label-for="last-name">
          <b-form-input
            id="last-name"
            type="text"
            placeholder="Last Name"
            v-model="customer.contact_lastname"
          ></b-form-input>
        </b-form-group>
      </b-col>
    </b-row>
    <b-row class="mt-3">
      <b-col cols="6">
        <b-form-group id="email" label="E-Mail" label-for="email">
          <b-form-input
            id="email"
            type="email"
            placeholder="example@crm.com"
            v-model="customer.contact_email"
          ></b-form-input>
        </b-form-group>
      </b-col>
    </b-row>
    <b-row class="mt-5">
      <h4 class="text-secondary">Company Details</h4>
    </b-row>
    <b-row>
      <b-col cols="4">
        <b-form-group
          id="company_name"
          label="Company Name"
          label-for="company_name"
        >
          <b-form-input
            id="company_name"
            type="text"
            placeholder="XYZ Industries"
            v-model="customer.company_name"
          ></b-form-input>
        </b-form-group>
      </b-col>
    </b-row>
    <b-row>
      <b-col cols="4">
        <b-form-group
          id="acquired_on"
          label="Acquired On"
          label-for="acquired_on"
        >
          <b-form-input
            id="acquired_on"
            type="date"
            v-model="customer.acquired_on"
          ></b-form-input>
        </b-form-group>
      </b-col>
    </b-row>
    <b-row class="mt-2">
      <b-form-checkbox
        id="customer_status"
        v-model="customer.customer_status"
        name="customer-status"
        value="active"
        unchecked-value="inactive"
      >
        Customer is active
      </b-form-checkbox>
    </b-row>
    <b-row class="mt-4">
      <b-col cols="3">
        <b-button variant="primary" class="px-5" @click="updateCustomer"
          >Update Customer</b-button
        >
      </b-col>
      <b-col>
        <b-button variant="warning" @click="triggerClose">Close</b-button>
      </b-col>
    </b-row>
  </b-form>
</template>

<script>
import axios from "axios";

export default {
  name: "CreateCustomerModal",
  props: {
    customerId: Number,
  },
  data() {
    return {
      customer: {},
    };
  },
  mounted() {
    this.getCusomterByID();
  },
  methods: {
    triggerClose() {
      this.$emit("closeEditModal");
    },
    getCusomterByID() {
      axios
        .get(`http://localhost:3000/customers/${this.customerId}`)
        .then((response) => {
          this.customer = response.data;
        })
        .catch((error) => {
          console.log(error);
        });
    },
    updateCustomer() {
      axios
        .put(
          `http://localhost:3000/customers/${this.customerId}`,
          this.customer
        )
        .then((response) => {
          console.log(response.data);
          this.$emit("closeEditModal");
          this.$emit("reloadDataTable");
          this.$emit("showSuccessAlert");
        })
        .catch((error) => {
          console.log(error);
        });
    },
  },
};
</script>

For our delete modal we will have a confirmation message, asking the user to confirm that the record needs to be deleted:

<template>
  <div>
    <b-row class="mt-2 mb-3">
      <h6 class="text-secondary">
        Are you sure you want to delete this customer from your CRM?
      </h6>
    </b-row>
    <b-row class="mt-2 mb-3">
      <p class="text-danger">
        This action is not reversible and may result in the loss if important
        data.
      </p>
    </b-row>
    <b-row class="mt-4">
      <b-col>
        <b-button variant="danger" @click="removeCustomerFromData"
          >Delete Customer</b-button
        >
      </b-col>
      <b-col>
        <b-button variant="warning" @click="triggerClose">Close</b-button>
      </b-col>
    </b-row>
  </div>
</template>

<script>
import axios from "axios";

export default {
  name: "DeleteCustomerModal",
  props: {
    customerId: Number,
  },
  methods: {
    triggerClose() {
      this.$emit("closeDeleteModal");
    },
    removeCustomerFromData() {
      axios
        .delete(`http://localhost:3000/customers/${this.customerId}`)
        .then(() => {
          this.$emit("reloadDataTable");
          this.$emit("showDeleteAlert");
          this.$emit("closeDeleteModal");
        })
        .catch((error) => {
          console.log(error);
        });
    },
  },
};
</script>

The result will be:

By clicking on the "Active Customers" we can filter the table to include only those, that are currently active:

This function is used to reset the items array to its original form where all customers are included:

setFilterTotalIsActive() {
      this.tableHeader = "Total Customers";
      this.getCustomerData();
}

This function is responsible for filtering out any customers that are not currently active:

setFilterActiveIsActive() {
      this.tableHeader = "Active Customers";
      this.items = this.activeCustomersData;
}

The activeCustomersData is returned from our data() function. The array is filled when the data is being requested from our backend:

getCustomerData() {
      axios
        .get("http://localhost:3000/customers/")
        .then((response) => {
          this.tableHeader = "Total Customer";
          this.items = response.data;
          this.numberOfCustomers = response.data.length;
          this.activeCustomersData = response.data.filter(
            (item) => item.customer_status === "active"
          ); //filters out any inactive customers
          this.activeCustomers = this.activeCustomersData.length;
        })
        .catch((error) => {
          console.log(error);
        });
    },

We are also conditionally rendering a green tag when the customer is active and a red one, when the customer is inactive:

This is done using the following:

          <b-table
            striped
            hover
            :items="items"
            :fields="fields"
            class="text-center"
          >
            <template #cell(contact_name)="data">
              {{
                `${data.item.contact_firstname} ${data.item.contact_lastname}`
              }}
            </template>
            <template #cell(customer_status)="data">
              <b-icon-bookmark-check-fill
                variant="success"
                v-if="data.item.customer_status === 'active'"
              ></b-icon-bookmark-check-fill>
              <b-icon-bookmark-x-fill
                variant="danger"
                v-else
              ></b-icon-bookmark-x-fill>
            </template>
            <template #cell(actions)="data">
              <b-row>
                <b-col cols="7">
                  <b-icon-pencil-square
                    class="action-item"
                    variant="primary"
                    @click="getRowData(data.item.id)"
                  ></b-icon-pencil-square>
                </b-col>
                <b-col cols="1">
                  <b-icon-trash-fill
                    class="action-item"
                    variant="danger"
                    @click="showDeleteModal(data.item.id)"
                  ></b-icon-trash-fill>
                </b-col>
              </b-row>
            </template>
          </b-table>

As you can see, if the data.item.customer_status is active, we render the <b-icon-bookmark-check-fill></b-icon-bookmark-check-fill> with a success variant. If the customer is inactive, we use the <b-icon-bookmark-x-fill></b-icon-bookmark-x-fill>with the danger variant.

We are using the template within our data table to be able to customise what is rendered inside our table.

We are also using this render our <b-icon-pencil-square></b-icon-pencil-square>-icon, our <b-icon-trash-fill></b-icon-trash-fill>-icon and to render the full name of our contact.

Create Functionality

We can simply click on the button with the label "New Customer" and fill out the form:

We can then hit "Add Customer" to store the data in our mock api database.

We now have a new entry in our table:

We can see that we included the success message at the top, to inform the user that customer has been successfully added.

What happens is that our actions sends a post request to the backend with the data we want to store:

addNewCustomer() {
    axios
       .post("http://localhost:3000/customers/",this.customer)
        .then((response) => {
          console.log(response.data);
          this.$emit("closeCreateModal");
          this.$emit("reloadDataTable");
          this.$emit("showSuccessAlert");
        })
        .catch((error) => {
          console.log(error);
        });
    },

Now you may have noticed these this.$emit events. These allow us to send data from the child component (in this case the modal window) back to the parent (in this case the data table).

Here we are first closing the modal window by triggering the closeCreateModal() method, reloading the data and telling our parent component to render the alert.

These events are registered in our parent component:

<!-- Modal for adding new customers -->
    <b-modal
      ref="create-customer-modal"
      size="xl"
      hide-footer
      title="New Customer"
    >
      <create-customer-form
        @closeCreateModal="closeCreateModal"
        @reloadDataTable="getCustomerData"
        @showSuccessAlert="showAlertCreate"
      ></create-customer-form>
    </b-modal>

As you can see, the child component has the name of the string we place in the $emit.

That way Vue knows which event to look out for and when that event is registered, it knows which method to call next:

closeCreateModal() {
      this.$refs["create-customer-modal"].hide();
    },
    getCustomerData() {
      axios
        .get("http://localhost:3000/customers/")
        .then((response) => {
          this.tableHeader = "Total Customer";
          this.items = response.data;
          this.numberOfCustomers = response.data.length;
          this.activeCustomersData = response.data.filter(
            (item) => item.customer_status === "active"
          );
          this.activeCustomers = this.activeCustomersData.length;
        })
        .catch((error) => {
          console.log(error);
        });
    },
showAlertCreate() {
      this.showSuccessAlert = true;
      this.alertMessage = "Customer was created successfully!";
    },

Update Functionality

Now that we can create new customers, we can focus on editing the existing records.

This usually has two parts to it:

Identify and load the specific data of the record
Send the updated data to the backend for storage

So, we first need to identify the records. For that we have ids. They are unique to each record, which is exactly what we need.:

             <template #cell(actions)="data">
              <b-icon-pencil-square
                class="action-item"
                variant="primary"
                @click="getRowData(data.item.id)"
              ></b-icon-pencil-square>
            </template>

This is part of our data table and we again are using <template></template> to customise what is being rendered.

Here we are calling a function that will assign the id to a property returned by the data method:

getRowData(id) {
      this.$refs["edit-customer-modal"].show();
      this.customerId = id;
    },

We are using $refs to identify the modal we want to open. In this case we are using the edit-customer-modal. Think of $refs as a form of selector such as the id or class.

We are also passing the id of the element to our customerId to be used in our update call.

With the customerId we can now pass this to our child modal.

But how?

For this reason props exist:

<!-- Modal for updating customers -->
    <b-modal
      ref="edit-customer-modal"
      size="xl"
      hide-footer
      title="Edit Customer"
    >
      <edit-customer-form
        @closeEditModal="closeEditModal"
        @reloadDataTable="getCustomerData"
        @showSuccessAlert="showAlertUpdate"
        :customerId="customerId"
      ></edit-customer-form>
    </b-modal>

We are passing our customerId with our stored id to a property with the same name. You can name it any way you want, but it happens that we have the same name here.

The syntax is :<prop name>="whatever you want to pass"

We now need to register this prop name in our modal component, to be able to use it:

  name: "CreateCustomerModal",
  props: {
    customerId: Number,
  },

In our export default, we can add this props-property to it, allowing us access to it within our child component.

With this in place, we can now make a request to our api and by supplying our id, we can get the specific record:

getCusomterByID() {
   axios
    .get(`http://localhost:3000/customers/${this.customerId}`)
    .then((response) => {
       this.customer = response.data;
     })
     .catch((error) => {
       console.log(error);
     });
    },

This will return the data we need to pre-fill the input fields with the current data stored:

Now let us change the E-Mail that is being used and then click on the update button to save the changes:

And this will then be reflected in our table:

This is thanks to our axios request that sends the updated data to our api:

updateCustomer() {
      axios
        .put(
          `http://localhost:3000/customers/${this.customerId}`,
          this.customer
        )
        .then((response) => {
          console.log(response.data);
          this.$emit("closeEditModal");
          this.$emit("reloadDataTable");
          this.$emit("showSuccessAlert");
        })
        .catch((error) => {
          console.log(error);
        });
    },

We are using a the PUT Http-verb here to tell axios that we want to update a specific record with the data we define as the second argument.

We therefore also need to include the id of the record we want to update.

We again make use of our events to close the modal, reload the table to be able to see the changes happen and display our success message.

Delete Functionality

And last, but certainly not least we have our delete, identifiable by our trash can icon in red:

When we click on it, the record will not be immediately deleted, but a prompt will appear, asking the user, if we want to permanently delete this record:

It is considered good usability practice to inform the user of any potential dangers their actions may have.

The modal appears thanks to our icon having a click-event attached to it:

<b-col cols="1">
                  <b-icon-trash-fill
                    class="action-item"
                    variant="danger"
                    @click="showDeleteModal(data.item.id)"
                  ></b-icon-trash-fill>
                </b-col>

Just as we did with the edit modal we also pass in the id of our item, which we will be needing for when we make our delete request:

<script>
import axios from "axios";

export default {
  name: "DeleteCustomerModal",
  props: {
    customerId: Number,
  },
  methods: {
    triggerClose() {
      this.$emit("closeDeleteModal");
    },
    removeCustomerFromData() {axios
 .delete(`http://localhost:3000/customers/${this.customerId}`)
        .then(() => {
          this.$emit("reloadDataTable");
          this.$emit("showDeleteAlert");
          this.$emit("closeDeleteModal");
        })
        .catch((error) => {
          console.log(error);
        });
    },
  },
};
</script>

Here are basically again doing the same things we did in the previous examples.

We make our request when a user takes an action and then we emit a few events back to the parent data table component to close the modal, reload the data to reflect our changes and display the success alert.

Here we also have an option close the modal, which is why there is an additional method that emits and event in the case the user decides to take this route.

We are also using red text and a red background for our button to signal to the user that this is a very important action that may have negative consequences.

Once we confirm the deletion, we can again see the success alert informing us and can verify, that the record has been removed from the table:

Conclusion

I hope you enjoyed this introduction to Vue. These points outlined above are not only applicable to Vue, be it 2.x or 3.x, but also to other Single-Page-Frameworks such as React, Angular or Svelte.

The concepts remain the same.

If you have been following along, you can have a look at see if you can simplify our DataTable.vue file by splitting it up into more components.

Let me know if there is anything that you would like to read about on this page.

The Benefits UX-Design has on Software Development and Business: An Overview

RoryJZauner — Thu, 29 Jul 2021 06:05:43 +0000

Once the requirements for a project are down, it is very tempting to simply dive into coding it all up without designing any of the features beforehand.

After all, it is only the user interface.

In this article we will explore how designing a product from scratch, before a single line of code is written, can make a huge difference.

Summary

Cheaper to make changes in design than code
Build something users are looking for
Shorter development times
Improved usability

Making Changes in Code vs. Making Changes in Design

Imagine you receive the requirements for a feature that needs to be implemented.

The different work items on the board outline what needs to be done.

So, you start coding away and build out the backend portion and then start to code out a frontend you think will be ideal for this feature.

Once all of this is done, you present your final work to the product team, who then want improvements to be made on the frontend-side.

No problem, we simply need to refactor some parts of it.

After some more testing, the product team find a few more UI-issues that need fixing.

These issues may result in a more complex refactor, meaning you are spending more time working on the UI-elements.

After the work is complete, the product team again need a few tweaks to the UI, some changes result in the UI looking the way it did originally.

What a pain.

After all of that has been done, and the product team finally happy with the result, the users are asked to test the product.

Here we find quite a few and severe usability issues, meaning we need to go back and refactor the frontend some more.

You again make changes, push changes, and test it on some more users, who again find a few more changes that need to be made.

And the cycle repeats itself.

As you can see, there are a lot of developer hours spent on refactoring code.

Making changes in code is way more resource intensive than making an adjustment during the design-phase.

In a design-tool we can simply move elements around and have a new prototype up-and-running within minutes.

Creating design beforehand allows us to quickly prototype an idea, get it to the users, receive feedback, refine the prototype, and test it on some more users.

On the business side of things we can see that this would increase the satisfaction of users and make them more likely to keep using our product.

Build something Users Need

As we saw with the example above, the actual users get to see the product at a very late stage in the development process. At this stage, a lot of assumptions and design decisions have already been made.

These may not necessarily reflect the needs of the users.

We need to involve users at every step of the way and get that invaluable feedback on our design. This way we can ensure that we are building for our users and that the final product or feature is something they will actually use.

People tend to get confused when the team starts to talk about design and think that it only has to do with the how the user-interface is going to look.

The way we design of our products has a lot to do with how it will work for the user and if the user can work with our product.

The user-interface is the gateway through which the user learns to interact with our product. It allows people to harness the power of technology.

By building something the user actually needs, that solves an actual problem they have, you are investing in a loyal fanbase that helps guards against competition.

Shorter Development Times

Designing the product before it gets translated into code means that the important decisions regarding how the product should work and feel are already made.

This means that the development team can focus solely on logic and not be slowed down by design decisions.

Additionally, the design has been tested by real users, ensuring that any usability issues have been ironed out before a single line of code has been written.

This again reduces the overall amount of refactoring the development needs to get done before a product is launched.

It means that resources are being spent more efficiently and features can be pushed more quickly, decreasing the time-to-market.

Improved Usability

I have mentioned usability a few times now, but what exactly do I mean by that?

It generally describes the how easily a user can achieve their goal when using your product.

Core values of usability are:

Effectiveness: It helps the user achieve their goal
Efficiency: Users can achieve their goals quickly
Engagement: The user experience of your product is pleasant
Error Tolerance: How easily are errors made within the system and how easily can a user recover from them?
Ease of Learning: How quickly can a new user learn to use your product?

By using a clickable prototype, the product team can ensure that users are able to use the product and achieve their goals efficiently.

This will result in fewer negative experiences while using your product and ensure that the product meets the user's needs.

Happy users will gladly recommend your product to others, turning them into advocates for your brand and product.

Happy users are a great marketing tool.

Conclusion

This may not always be feasible and not ever team has a UX-Designer that can get these tasks done.

But just a bit of designing and feedback, can go a long way in ensuring your designs are meeting the user's needs.

The theme running through all of these is the user. You are building the product for them. You want to give them the best possible experience when using your product. They are the one of the best marketing resources you can employ.

Don't annoy or frustrate them, and they will thank you will trust and loyalty.

Let me know what your experience has been and how design has benefited or harmed the outcome.

Would love to hear from you.

What JavaScript do you need to know to write Single-Page-Applications more effectively: A Guide

RoryJZauner — Thu, 22 Jul 2021 12:20:04 +0000

If you are interested in knowing what aspects of JavaScript are going to be important for frameworks such as React or Vue, then this article is for you.

I will be covering what aspects of JavaScript I have used when developing using React or Vue.

Summary

JavaScript Basics
Basic DOM Manipulation
Arrow Functions
Array Methods
Asynchronous JavaScript
Making Requests to an API using Fetch
ES Modules
NPM

Before we jump-in, I would just like to mention that it is not absolutely necessary to know all of these concepts to use React or Vue.

I definitely did not know everything when I first started using React and Vue.

Understanding these concepts and how JavaScript works in the browser is important and will give you a good foundation for your learning of React and Vue.

JavaScript Basics

As with everything, the basics of JavaScript are going to be important.

Variables

In JavaScript you can create variables using the keyword const, var and let.

const is used to declare constants - these are variables whose value will not change over time.

const daysOfTheWeek = 7;

let and var are used in the same way with the keyword being placed before the variable name:

let firstName = "Jane";

var lastName = "Doe";

These are generally used when we have variables whose values are going to change over time.

You may be asking yourself, why there are two keywords with the same function.

There is a small difference.

function varExample ()
{
    var name = "Jane";

    if(name === "Jane")
    {
        var name = "Doe"; //    the same variable as above
        console.log(name) //    will return "Doe"
    }

    console.log(name); //    will also return "Doe"
}

function letExample ()
{
    let name = "Jane";

    if(name === "Jane")
    {
        let name = "Doe"; //    new variable is created
        console.log(name) //    will return "Doe"
    }

    console.log(name); //    will also return "Jane"
}

The variable created using var gets updated, regardless of where in the function it is called.

The variable created using let does not get updated, because the value of that variable is specific to the block it is created in.

Now that we know how to create variables in JavaScript, we can move on to looking at datatypes in JavaScript.

Built-in Datatypes

When writing JavaScript, you will not be declaring the type of variable you are creating.

However, it can be helpful to know which data types exist in the wild west of JavaScript:

Undefined
Number
Boolean
String
BigInt
Symbol

For more information on types in JavaScript you can have a look at the awesome documentation by Mozilla

String Manipulation

Being able to manipulate strings is another task that is often needed when building an application.

Adding Two Strings Together

let firstName = "Jane";
let lastName = "Doe";

//joining them using a '+'
let fullNameOne = firstName + " " + lastName;

console.log(fullNameOne);

//or using template string by using backticks(``)
let fullNameTwo = `${firstName} ${lastName}`;

console.log(fullNameTwo);

//both will result in "Jane Doe"

We can directly use the variables we created to build our final string that will be used as part of our user interface.

Strings also have properties we can access such as the length:

let firstName = "Jane"

let firstNameLength = firstName.length

//will output "4"
console.log(firstNameLength);

We can also convert strings to upper- and lower-case using built-in methods:

let firstName = "Jane";

let upperCaseName = firstName.toUpperCase();
let lowerCaseName = firstName.toLowerCase();

console.log(upperCaseName);//Output: "JANE"
console.log(lowerCaseName);//Output: "jane"

These are again just a small sub-section of what you can do using the built-in JavaScript methods.

DOM Manipulation

JavaScript is definitely a powerful language for the web. It allows us to directly alter what we see in the browser. Using JavaScript we can respond to user input.

It is this reactivity that is an important concept to understand, especially when we progress to using React or Vue.

Selecting Elements from a Webpage

The first step in using JavaScript to manipulate the DOM is to know how to select the elements you want to manipulate.

The older approach you may see is this one:

//this will store all elements that have a class of "title" within our heading variable
let heading = document.getElementByClassName("title");

//this will store the element with the Id "submit" within our button variable
let button = document.getElementById("submit");

A newer approach is to use querySelector():

//this will store the *first* element that has a class of "title" within our heading variable
let heading = document.querySelector(".title");

//this will store the element with the Id "submit" within our button variable
let button = document.querySelector("#submit");

//this will store all of the elements that have a class of "title" within our heading variable as an array
let heading = document.querySelectorAll(".title");

Creating DOM Elements

Another great feature of JavaScript is the ability to create elements that get rendered in the browser.

Helpful when you are retrieving data from an api and you want to display it in a list.

//here we have our heading
const heading = document.querySelector('.heading');

//now let us add our subheading
const subheading = document.createElement('h5');
subheading.textContent = "I am a subheading";

//we can now add this subheading to the heading element
heading.appendChild(subheading);

Handling User Input

This may well be one of the most common tasks when it comes to writing React and Vue apps. Which is why it is also important to understand how it works.

Assume we have a form and we want to get the input the user has entered into the field for the username.

There will be two parts to this form, an input field and a button:

<input type="text" class="username">
<button class="submit-btn" onClick="submitData()">
  Submit
</button>

Using onClick we can define what needs to happen when the button is clicked:

const submitData = () => {
        let username = document.querySelector(".username").value;

  console.log(username);  //will print our the text entered in the input field to the console
}

We can also adjust this to validate the user input every time a new character is added to the input:

<input type="text" class="username" onkeyup="logInput()">
<button class="submit-btn" onClick="submitData()">
  Submit
</button>

const logInput = () => {
    let username = document.querySelector(".username").value;

  console.log(username); 
 //will produce if typed slow enough:
 // "J"
 // "Ja"
 // "Jan"
 // "Jane"
}

There are many different events that can be triggered based on user input.

Dynamically Styling Elements using JavaScript

JavaScript allows us to dynamically update the styling of our UI, allowing us to give feedback to user in response to their input.

Very handy when we are validating the e-mail in a form:

<input type="text" class="user-email" onkeyup="validateInput()">

We are validating the e-mail on every character, giving the user the feedback and letting the know, if their input is valid or not.

This saves them the frustration of submitting data that they then have to correct later on, after the submit fails the validation check.

const validateInput = () => {
    //select the input element
    let emailInputElement = document.querySelector(".user-email");

  //get the value of the input field
  let userEmail = emailInputElement.value;

  //decide if the e-mail is valid or not
  if(!userEmail.includes("@"))
  {
    //here we are adding the red border of the e-mail is valid
    emailInputElement.classList.add("invalid-input");

    //and removing it, if the e-mail becomes invalid again
    emailInputElement.classList.remove("valid-input");
  } else {
        //here we add the green border if it is valid
        emailInputElement.classList.add("valid-input");

      //and remove the red border
      emailInputElement.classList.remove("invalid-input");
  }
}

With these manipulations I definitely would encourage you to try and build a few small projects where you focus on using JavaScript to build-in some reactivity into your app.

Arrow Functions

In a couple of the examples I have shown you, you may already seen this "=>" appear. These are called arrow functions and allow us to simplify the more traditional function declaration:

//traditional JavaScript function
function generateFullName(firstName, lastName){
    return `${firstName} ${lastName}`;
}

//will return "Jane Doe"
console.log(generateFullName("Jane", "Doe"));

//arrow function with name
const generateFullNameArrow = (firstName, lastName) => `${firstName} ${lastName}`

//arrow function returning "Jane Doe"
console.log(generateFullNameArrow("Jane", "Doe"));

Array Methods

These are perhaps one of the most widely used aspects of JavaScript when it comes to dealing with data being retrieved from an API.

In JavaScript arrays can be created using the following syntax:

let nameArray = ["Jane", "John", "Sarah", "Mike"];

Very simple right?

We store the data in a variable, which is why we need a let at the beginning.

Arrays have different methods that allow us to interact and manipulate the data inside.

Going over each item

To go over each item in array we can use the forEach method:

nameArray.forEach(name => console.log(name));

//    Output: "Jane"
//    Output: "John"
//    Output: "Sarah"
//    Output: "Mike"

This does exactly the same as a for-loop:

for(let i = 0; i < nameArray.length; i++)
{
    console.log(nameArray[i]);
}

The forEach method allows us to write less code, but there is not a right or wrong way to go about this.

The console.log(nameArray[i]); is how we can access specific elements within an array.

We need to know what index the element within an array has.

For our nameArray array, we have the following:

//index             0       1       2        3    
let nameArray = ["Jane", "John", "Sarah", "Mike"];

//accessing the name Sarah
console.log(nameArray[2]);

In JavaScript the index starts at 0 and goes up.

Filtering items

JavaScript also has a built-in filter() function that allows us to take the original array and create a new one with items, that fulfill a certain criteria.

//will give us a new array with names that have 4 letters or less
let namesThatHaveFourLetters = nameArray.filter(name => name.length <= 4);

//output: ["Jane", "John", "Mike"]
console.log(namesThatHaveFourLetters);

This will only include names that have 4 characters or less in them.

Applying changes to all items

Another great method that I can recommend using is the map() method.

It allows us to apply changes to each item of an array:

let randomNumbersArray = [1, 2, 3, 4, 5];

let doubledNumbersArray = randomNumbersArray.map(number => number * 2);

console.log(doubledNumbersArray);

//output: [2, 4, 6, 8, 10]

Adding and Removing Items from an array

Another task that does come up is adding and removing items from an array:

//add item to the end of an array
let nameArray.push("Amy");

//add item to the start of an array
let nameArray.unshift("Tom");

//remove item from the end of an array
let nameArray.pop(); //removes "Amy" from array

//remove item from the start of an array
let nameArray.shift(); // removes "Tom" from array

I again recommend that you have a look at the documentation for Mozilla, where there is a more complete list of what is possible with arrays in JavaScript.

Asynchronous JavaScript

This is a key concept when looking using JavaScript-based technologies.

A synchronous app would be one that we are generally familiar with - one line of code is executed after another and there are no two tasks being executed alongside each other.

This can become a problem when you are executing an intensive piece of code and are waiting for that to finish before going on to the next task. If this happens with in the browser, you may well see no response and think the browser has frozen.

You will find that many tasks that relate to fetching some sort of resource from a server now feature asynchronous code to run.

Using setTimeout we can easily show how JavaScript enables us to run code asynchronously:

setTimeout( () => {
    console.log("First console log");
}, 2000);

console.log("Second console log");

//Output:
//"Second console log"
//"First console log"

This is using callbacks to run whatever is inside of the function only after 2 seconds have elapsed.

This means that JavaScript goes onto the next line while the function is waiting to be resolved.

There is a newer and more modern way of writing these types of asynchronous tasks using Promises:

fetch("api/for/some/resource")
//Promises have a characteristic .then()
  .then( response => {
    console.log(response.data);
//it is common to use .catch() to log any errors
}).then( json => {
    console.log(json);
}).catch( error => {
    console.log(error);
});

The code contained within .then() will only be executed, when fetch() returns a result. If the it returns an error instead, the .catch()-block will be invoked.

There is a third level of asynchronous JavaScript that can be achieved using async/await:

//the async keyword comes before the function you want to use await in
const data = async () => {
    //get the resource returned by the api
    const resource = await fetch("api/for/some/resource")
    //convert the returned data to json
    const posts = await resource.json();
    //make it available
    return posts;
}

As you can see this does make your code more readable and cleaner to understand.

Making Requests to an API using Fetch

When working on the frontend of a project, one of the main tasks will be to send and receive data from the backend.

The fetch API provides us with a very convenient way of doing exactly this:

const getUserData = async () => {
    const response = await fetch('api/user/resource', {
        method: 'GET' //'POST', 'PUT', 'PATCH', 'DELETE'
    });

    const data = await response.json();

    return data;
}

If we wanted to post data to the server, we simply use the 'POST' method:

const formData = { firstName: "Jane" };

const postUserData = async () => {
    const response = await fetch('api/user/create', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json; charset=UTF-8'
        },
        body: JSON.stringify(formData),
    });

    const data = await response.json();

    return data;
}

The same thing can be done will all other Http verbs that you can use.

This forms pretty much the backbone of building singe-page-applications using Vue or React.

Mozilla have again done a great job in documenting how to use the Fetch API.

ES Modules

Modules allow us to write logic in one file, export the logic we want and import it in the file we need.

This was possible before we had modules:

const library = require('library-name);

While the module syntax looks like:

import library from 'library-name';

In order for us to be able to import any library or logic, we need to first make it available to be imported. This is done using the export keyword.

//roundNumber.js
export default decimal => Math.round(decimal);

We can now use this in our app.js file:

//app.js
import roundNumber from './roundNumber.js';

let decimal = 3,2;

let roundedDecimal = roundNumber(decimal);

In a Vue or React project you will definitely be importing functionality from different third-party tools and also exporting your own logic to be used within the entire app.

Package Management with NPM

When you first start out a new job as a developer, chances are you will be working on an existing project.

This means that you will need to setup and install all of the dependencies for the project.

Luckily, we have something called npm with which we can easily install all of the dependencies defined within the project's package.json file.

To install all of the packages defined in the file, simply run npm install.

You will see a node_modules-directory created, where, you guessed it, all of your modules/dependencies are installed, ready to be imported.

You can also add packages to a project using npm install <package-name>.

Additionally, we can define which modules are going to be used in production (use npm install <package-name> --save) and which are pure development dependencies (use npm install <package-name> --save-dev).

Testing libraries are usually used during development, but are not needed during production.

Lastly, we can also define commands within our package.json that we can then run using npm:

//package.json
{
    "scripts": {
        "dev": "vue-cli-service serve",
    }
}

We can then reference this using npm by running npm run dev which will in this case start up the development server of our Vue app.

Conclusion

I hope this brief overview gave you an idea of what to know when it comes to starting with React or Vue.

Like I wrote in the beginning, it is not necessary to know all of this, but it does help and speed-up your progress by being familiar with these concepts.

Let me know in the comments if I missed anything that is relevant to learning.

UX-Toolbox: Doherty's Threshold

RoryJZauner — Fri, 16 Jul 2021 12:35:41 +0000

Ever visit a site to find that loading the content takes forever?

Or worse, you clicked on the submit button, expecting to be greeted by a loading spinner and a new page, instead you see the same page and nothing happens. After a few seconds, the page suddenly changes without warning.

This feeling of frustration is what we are looking into today.

In this article I want to introduce to you the UX-effect known as Doherty's Threshold.

Take-Aways

Keep the response time of your application to around 400ms - this will keep people engaged with the task
Use loading spinners and progress-bars to keep people engaged when waiting times have to be longer

What is Doherty's Threshold?

It was named after IBM Researcher Walter J. Doherty who discovered that when the response time of the system was quicker, the overall efficiency of the process improved.

This means a person does not have to wait for a response but receives the cues for the next step toward completing the task.

People are not waiting for the system to respond, but can smoothly transition to the next step, keeping their train-of- thought.

Increasing the response time will not only cause frustration, if no visual feedback in the form of loading spinners or progress bars are presented but will most likely result in rage-clicking.

Not good.

Which is why you should always include some form one indication that work is being in the background - one of the most important Usability Heuristics outlined by Jakob Nielsen.

That way the person is receiving visual feedback in response to their action.

This makes the person feel more at ease and builds trust in your product.

The ideal response time of a system has been measured at around 400ms.

Keeping the response time at this level allows the person using the system to flow between steps and efficiently achieve the task they set out to complete.

Conclusion

This effect demonstrates well how important it is to give the person using your product feedback in response to their action. Particularly, when this action will require longer loading times.

This will simply allow them to know that everything is working and that currently the system is loading.

Comment down below your most frustrating user-experience you have had.

Use Material-UI to Design your React Components using Material Design

RoryJZauner — Fri, 09 Jul 2021 11:20:57 +0000

If you have read my post on using Material Design with Vue.js, then you will know that I enjoy the material design spec.

I also wrote about how I used Material-UI in my React projects to style my components.

This post will show how to set up the Material-UI in a freshly installed React project.

Summary

Project Setup
Using components
Material Icons
Conclusion

Project Setup

First we will setup our React project using Create-React-App and then we will install Material-UI.

Create-React-App

Using the following command, we can scaffold our entire React App to get us started in building our Single-Page-Application:

npx create-react-app <app-name>

In my case this will be:

npx create-react-app material-react

This will create a new directory called material-react with our dependencies installed and ready for development.

To check that everything has installed correctly, we can simply start the development server:

cd material-react
npm start

After starting the development server, the browser will open on localhost://3000, where you will see the React logo:

If not, simply open your favorite browser and paste in localhost://3000 to see the app running.

Awesome, now we can install the Material-UI to get some nice material design styling going.

Material-UI and Material Icons

To install the Material-UI-Library, I will be following the documentation - always a great place to learn more about the technologies you are using.

First, we need to install the necessary packages:

npm install @material-ui/core

Once that is installed, we can add the signature Roboto-Font using via CDN.

Simply add it to your project by placing it in the

-tag of your index.html located in the public folder:

<!--public/index.html-->
<head>
    <meta charset="utf-8" />
    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta
      name="description"
      content="Web site created using create-react-app"
    />
    <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
    <!--
      manifest.json provides metadata used when your web app is installed on a
      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
    -->
    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
    <!--
      Notice the use of %PUBLIC_URL% in the tags above.
      It will be replaced with the URL of the `public` folder during the build.
      Only files inside the `public` folder can be referenced from the HTML.

      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
      work correctly both with client-side routing and a non-root public URL.
      Learn how to configure a non-root public URL by running `npm run build`.
    -->
<!--Add Roboto Font-->
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" />
    <title>React App</title>
  </head>

Next we can install the SVG-Icons:

npm install @material-ui/icons

Perfect! Our setup is completed - we can now have a look at what we installed and make sure everything is working.

Replace the code in App.js with the following snippet:

//    src/App.js
import "./App.css";

//  import the component you want to use
import Button from "@material-ui/core/Button";

function App() {
  return (
    <div className="items-center">
      <Button variant="contained">Default</Button>
      <Button variant="contained" color="primary">
        Primary
      </Button>
      <Button variant="contained" color="secondary">
        Secondary
      </Button>
      <Button variant="contained" disabled>
        Disabled
      </Button>
      <Button variant="contained" color="primary" href="#contained-buttons">
        Link
      </Button>
    </div>
  );
}

export default App;

You can use your own CSS-classes alongside the library. Here we are using a flex-box to center our items:


/*src/App.css*/
body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen",
    "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue",
    sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

code {
  font-family: source-code-pro, Menlo, Monaco, Consolas, "Courier New",
    monospace;
}

.items-center {
  display: flex; /*wrap in flex box so that we can use justify-conent*/
  justify-content: center; /*center items*/
  margin-top: 30px; /*add some margin that the top*/
}

Which results in:

Awesome!

Looking at the docs, we can see that there are many different components we can use in this way.

This is one way of adding CSS-rules to your component. We can also make use of the following:

import "./App.css";

//  import the component you want to use
import Button from "@material-ui/core/Button";

//  import makeStyles
import { makeStyles } from "@material-ui/core/styles";

//  define the same styles used for placement
const useStyles = makeStyles({
  root: {
    display: "flex",
    justifyContent: "center",
    marginTop: "30px",
  },
});

function App() {
  const classes = useStyles();
  return (
    <div className={classes.root}>
      <Button variant="contained">Default</Button>
      <Button variant="contained" color="primary">
        Primary
      </Button>
      <Button variant="contained" color="secondary">
        Secondary
      </Button>
      <Button variant="contained" disabled>
        Disabled
      </Button>
      <Button variant="contained" color="primary" href="#contained-buttons">
        Link
      </Button>
    </div>
  );
}

export default App;

The result does not change, but with this, we can define our styling within the components we are creating.

Material-UI Icons

No UI-framework overview would be complete with a look at what icons are on offer.

We did install them earlier, so now we can get down to using them in our app.

We again import the icons we want to use from the icon library and then add it to our jsx:

import "./App.css";

//  import the component you want to use
import Button from "@material-ui/core/Button";

//  import makeStyles
import { makeStyles } from "@material-ui/core/styles";

//  import delete icon
import DeleteIcon from "@material-ui/icons/Delete";

const useStyles = makeStyles({
  root: {
    display: "flex",
    justifyContent: "center",
    marginTop: "30px",
  },
  button: {
    marginLeft: "10px",
  },
});

function App() {
  const classes = useStyles();
  return (
    <div className={classes.root}>
      <Button variant="contained" color="secondary" startIcon={<DeleteIcon />}>
        Delete
      </Button>
      <Button
        variant="contained"
        color="secondary"
        className={classes.button}
        endIcon={<DeleteIcon />}
      >
        Delete
      </Button>
    </div>
  );
}

export default App;

We can specify where we want to place our icon, be using the startIcon and endIcons attributes.

This is a quick and easy why to build out your UI without having ton configure too much yourself.

I again add in a button style to create some space between the two buttons.

Conclusion

I hope this gave you a good overview of what you can do with Material-UI.

I highly recommend you check out the documentation, the maintainers did an awesome job creating it.

As always, leave me a comment and let me know how you are finding the work with Material-UI.

UX-Toolbox: Aesthetic-Usability-Effect

RoryJZauner — Fri, 02 Jul 2021 06:41:34 +0000

One of the best ways to improve your product or help it stand out against competition, is to ensure the user experience is top-notch.

By applying different UX-Effects, you can ensure that your users are getting the most out of your product.

In this article, we will examine the Aesthetic-Usability Effect and see how it can improve your user experience.

Take-Away

Here are some actionable points you can take with you:

Crafting a beautiful user interface is worth it, as it can improve the perception of your product and brand
Make sure that your product performs the function it is meant to perform - create a balance between the beauty and function of your design
Spotting the aesthetic usability effect during user research will prevent usability issues from creeping into your product

What is this Aesthetic-Usability-Effect all about?

The Aesthetic-Usability Effect describes the case where people perceive design that they feel is visually pleasing to them, as design that works better.

Research shows that the more beautiful participants rated the user interface, the more usable they perceived the user interface to be.

This means that when a person finds the design of an app pleasing, they will be more likely to believe that the product works better.

This is because the pleasing design causes a positive reaction in the person's brain.

Impact

One of the positives to take away from this effect is that it can lead people to be more forgiving of minor usability issues, when they find your product's visual design good.

I highlighted the word minor because a good visual design won't save you, if the user can't actually perform the function your product sets out to perform.

All you have to do is make sure your product works as intended and make it look good - that's it?

Not quite.

A more negative aspect of this effect is that it can get in the way of your usability testing.

Remember that good design makes people more forgiving?

Well, that can mask usability issues during testing, leaving them to be undiscovered.

It is very important that whoever is conducting the user research knows what this effect is and how to spot it.

If you see the user struggling to find information on the screen or perform a particular action, this is a good sign that the usability is a bit off.

When the user then starts to comment on the beautiful user interface and the colour scheme, you know that they have fallen prey to the aesthetic-usability effect.

The carefully crafted and beautifully designed user interface should enhance the already great function of your product. Finding a good balance between form and function is important when building great products.

Let me know in the comments what topics in UX-Design you would like to learn about.

React + TailwindCSS + Vite.js = a Match made in Heaven?

RoryJZauner — Fri, 25 Jun 2021 05:52:22 +0000

For all of you who are fed up using create-react-app to scaffold a new React-project, this post will show you how to use Vitejs to get React and TailwindCSS up-and-running.

Summary

What is Vitejs?
Project Setup
Conclusion

What is Vitejs?

Vitejs aims to address some of the shortcomings that have crept in with our tooling.

Webpack, Gulp and Parcel are great for bundling our code, but are terribly slow when starting the development server, especially when you have an enormous amount of JavaScript-Code to load.

In more traditional build-tools the bundler will usually have to re-bundle the whole thing, which will take longer, the larger your application gets.

Even with something like hot-module-replacement, the build-speed can still take a significant hit, as the project increases in size.

Vitejs is blazingly fast, even when you first start your development server.

It also carries the speed advantage when you are editing a file. The changes are reflected in the browser almost instantly.

Now that you have a bit of background on Vitejs, let us get started in setting up our React project.

Project Setup

With this tutorial, I will be using React as my frontend-framework of choice, but you can use whatever you like.

Vitejs currently supports the following:

vanilla
vanilla-ts
vue
vue-ts
react
react-ts
preact
preact-ts
lit-element
lit-element-ts
svelte
svelte-ts

Unfortunately, Vitejs does not support Angular at the time of writing.

React Setup with Vitejs

To setup a react project is rather easy, simply pick the directory you want to store your project in, open up a terminal there and run the following command:

npm init @vitejs/app vite-react --template react

This will download our project files we need for our React project.

Again, you can use whatever technology you like. If you wanted to create a project using vanilla JavaScript, you would use:

npm init @vitejs/app vite-vanilla --template vanilla

It is that easy!

Now we need to change into our directory and install the dependencies, this is JavaScript after all.

cd vite-react

npm install

After we installed everything, we can now start our development server using the following command:

npm run serve

And in a matter of split-seconds, we can see that our terminal is showing a very pleasing sight:

Now it is time to install TailwindCSS.

TailwindCSS setup

This is also a very simple process.

First, we need to install the dependencies:

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

After that has installed successfully, we can create the tailwind config files using the following command:

npx tailwindcss init -p

That will create a tailwind- and a postcss-config file.

Now simply navigate into your src-directory, open up your index.css-file, remove all of the code and add these lines:

/* ./src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

That is it!

We now simply need to stop the development server using ctrl + C and restart it again using npm run dev.

Now to test our setup, we can remove the default jsx-code that comes pre-defined and add our own little tailwind-snippet.

My App.jsx looks like this:

/* src/App.jsx */
import React from "react";
import "./App.css";

function App() {
  return (
    <div className="flex justify-center">
      <h1 className="font-bold text-2xl text-blue-900">
        React and Tailwind with Vitejs!
      </h1>
    </div>
  );
}

export default App;

And the result looks like this:

With that we have verified that our tailwind setup works like a charm.

Conclusion

That is it for this week!

I hope you join me next week for another article.

If you enjoyed this article, give it a like and let me know in the comments what kind of content you would be interested in reading in the future.

Design Systems: What they are and how to build one

RoryJZauner — Fri, 18 Jun 2021 05:51:10 +0000

Ever wondered what all this talk about a thing called design systems is all about?

This article will get you up-to-speed with what a design system is, how to build one and what benefits a design system can have for your work.

Summary

Design Systems: The What
Design Systems: The Why
Design Systems: The How

Design Systems: The What

A design system is often mistaken for a style guide or a pattern library. These two tools are a part of a design system, but are not the design system itself.

A design system focuses more on the product as a whole.

Alongside style guides and pattern libraries that tell the designers and developers how something should look and work, there are also other more strategic aspects that play an important role as well.

These can include the values of your product's brand, company values, shared beliefs, design principles and many more.

These more high-level, strategic elements of a design system will influence how the user-interface is designed and how the product will work.

You can think of a design system as a single-source of truth for all product-related decisions. The elements of a design system go beyond product development and can ripple into the ad-campaigns your marketing team runs.

It gives you, your team and others working on a product a common language when it comes to design-related decisions regarding your product.

Now that we have touched on what exactly a design system is, we can look at the why.

Design Systems: The Why

The design system's purpose is to make the development of products more efficient by eliminating design inconsistencies.

Think about it - everyone has a different way of approaching their work. That also means, that everyone will do things differently and chances are, that the styling of UI-elements will start to reflect this.

This also means that with every new hire, the person is re-inventing the wheel - they are re-designing an element, that has already been designed by someone before them.

This slows down development, as designers and developers have to first look and find the element they are designing on another page, check the HTML, CSS and potentially also JavaScript, only for them to copy and paste the code straight into the element they are working on.

A design system can also be beneficial when looking at making design-related decisions. By grounding your designs on values and principles, you can begin to make decision within a framework.

This will ensure that not a lot of time is being wasted on deciding how something should work. This time can then be used to make other decisions and allows the team to work more efficiently.

As you can see, a design system can improve the efficiency and consistency of your products. This is great and all, but how do we actually build something like this?

I am glad you asked.

Design Systems: The How

As with many things nowadays, a design system is more of a process than something you deliver and that is it.

A design system grows gradually with the team and changes as the product and the requirements change over time.

Especially in the beginning, you are delivering different elements incrementally, watering your design system as it stretches toward the sunlight.

What makes up a design system?

A design system will likely include the following:

Design Principles: Goals that your design system aims to achieve such as minimalist design or remove not used UI
Brand Values: What are the values of the brand and how can the design system reflect these?
Style Guide: How are the elements going to be styled and why
Component Library: Ready-to-use components for developers and designers

Take stock of what you have

The first step in building your very own shiny design system is having a look at all of your elements across the different products and platforms and documenting the inconsistencies.

This will not only serve as a starting point for you and your team when building your style guide and pattern library, but also as a way for getting everyone on board.

There will be little doubt in the room, when you have 9 different alert styles for just 1 alert message across 3 apps.

This will also give you an indication of which UI-elements you need to focus on first. These will usually be the ones that have the most impact, also-known-as the ones that get used the most across the different apps and platforms.

Rally your team

This step is just also an important one - you should definitely look to get everyone on board and behind the goal you want to achieve. This will also help with adoption of the design system later one, when there is a working version of it.

The inconsistencies are a great visual tool to show everyone just how important it is, to be consistent with your visual language.

This is a great lead-in to explaining a bit about how important consistency is for the user experience. You can also look at how inconsistency can negatively impact the success of your product, even if the idea is the best in the market.

Everyone should also be allowed to give input and raise any concerns.

Dealing with concerns and expectations of the team will get them feeling comfortable with the idea of a design system and build-up a collaborative feeling within the team.

This is important, as nurturing a design system lives from collaboration.

This can't be stressed enough, as any issues with the implementation of the UI-elements needs to be raise, otherwise the design system fails to meet its purpose.

Designers and developers will go back to re-inventing the wheel.

Once the team feels confident with the proposed solution, you can look at recruiting any skills you will need for implementation.

The skills may vary, but usually you are looking at UX/UI-Designers for the visual design aspect, and frontend engineers for the coding and testing aspect.

Depending on the size of your team and the size of your design system, you may product designers, product managers, mobile engineers and many more.

You may find that while developing there are a few tasks that need a designated role. When that time comes, you can always grow the team, so you don't have to spend too much time picking your team.

Lay the foundation

Now that you and your team are ready to build your design system, it is time to lay a solid foundation.

You have seen the horror of inconsistencies on your design and can now establish rules and principles to help avoid these.

One of the ways you can start to implement a design system is to actually have a newer part of your UI serve as a starting point.

The advantage here is that you have something tried and tested and not have something completely new that may cause problems with your users.

The other option would be to simply scratch everything and start fresh with a clean slate.

Apart from the starting point, the team also needs to decide which technologies to use. This is relevant when you are looking at building your component library.

You can look to introduce a new technology stack or simply stick with what you know and already have.

On a higher-level you and can begin looking at design principles. These act as your guiding light for all of your design-related decisions. These will also help create a framework, within which you can build your awesome UI-elements.

These principles will also help map out a process for developing and extending your design system.

The implementation of you design system in your product portfolio is another consideration your team needs to make. Are you going to implement it one product at a time or are you going to be implementing across the entire portfolio.

And if your team has not yet had a chance to look at code formatting tools such as prettier, now is the time.

This is important because you need to communicate this to the members of the other teams.

Define your building blocks

There are many different parts that make up your UI. Breaking this down into more basic elements will make the decision making process easier.

Some of the first decisions you will be making are:

Colours
Typography
Icons
Layout

Colours

One of the more important decision of your design system will be the colour palette. Colour heavily influences the user experience.

This is not only a design decision, but also a branding one. You obviously want the colours of your product to reflect the colours of your brand - that way users will recognise the product as the one from your brand.

From this you can pick your secondary colours, accent colours and more.

Not only what colours you are going to use are part of this step, but also looking at what names your are going to be giving them.

Once you have a colour palette, you can begin by documenting the colours and giving them cool variables names.

Alongside colour, another important factor that influences the user experience is typography. It is in every heading, button and alert. Therefore, it is important to again get this right and keep it consistent.

Have a look at what you are working with and see if the text size, line heights and letter spacing are appropriate and work for different content.

You have your colours, great!

You have your typography down, even better!

Now it is time to look at your icons. Again, have a look at what you have and see if it needs improving or has many inconsistencies.

Clean it up and create a consistent icon library your designers and developers will love.

Now we are talking - your design system is growing by the minute and things are starting to come together.

Now we can look at standardising other parts of your designs, such as layout or responsiveness to name two. There are more, so always keep a lookout for anything where designers or developers start guessing, that is an ideal place for some standardisation.

These will definitely again follow a similar pattern to the previous three elements: see if you already have something useful, then either repurpose and polish or create something new.

That went by rather quickly didn't it?

It is important to test these basic building blocks before moving on. Testing them with real users is a good indication for you and your team, that you are heading in the right direction and can begin using these to create your first design patterns.

We have our basic building blocks laid down, documented and tested, you can now have a look at how put them together.

Build some awesome UI-Patterns

Now we can combine these building blocks and build our awesome UI.

This is my favourite task of the process as you get to see the fruits of labour.

How you go about structuring your UI-patterns will be up to you - one way is to use a more atomic approach.

When building a design system you are most likely going to be developing it in sprints. It is important during sprints, not to bite of more than you can chew - in other word, do not try and create all of your UI-patterns in one sprint.

These patterns are going to serve your entire product portfolio, they need to thoroughly tested and reviewed by other developers, designers, product managers and also your users.

So the easiest way to start with this is to take an UI-element that is used across most if not all of your portfolio.

Buttons are a great way to get started - they have colour, typography, icons and different sizes. Additionally, they are found pretty much everywhere. Therefore, your efforts are going to have an impact.

It is here where you will begin to gather the different components in the form of your technology of choice. Among many others, these would most likely be Vue, React, Angular, Web Components or Svelte.

Review your Work

Now that you have completed a first run through of your design system process, it is time to look at what you have achieved.

This will give you and your team an opportunity to talk about anything that has not gone smoothly and you can work on in the next sprint.

Conclusion

As you can see, creating a design system can be a labour-intensive task. The reward of being able to produce a consistent user experience with relative ease and at a larger scale, is well worth the effort in my opinion.

It really can improve your efficiency as a team, because you are focusing on building and not on what shade of gray you need to use for this element.

I hope you enjoyed reading this article and I will see you next time with another article.

Bye.

If you enjoyed this article you can give it a like and tell me what you think of design systems and how they could impact your work