DEV Community: Miguel Jimenez

The REST pattern explained like you're 6 years old

Miguel Jimenez — Wed, 17 Nov 2021 13:10:31 +0000

Most explanations of the REST architectural pattern out there are overly abstract and computer-sciency. They are very hard to digest to if you have little to no experience in web development.

Here's an illustrated tale to explain what RESTful architecture is like you were a 6 year-old who knows the internet kinda exists and it involves something called servers.

Asim, the pyramid architect

A very, very long time ago in Ancient Egypt, there was an architect. His name was Asim. Unlike other architects who built massive pyramids, Asim's job was slightly different. He specialized in building very small, unipersonal pyramids for the nobles of Luxor.

Asim received orders to build many small pyramids that needed to be finished promptly. All these pyramids looked almost the same, but Asim allowed his clients to choose the color. All pyramids also had a unique id number and a noble who would be placed inside once Anubis came knocking.

Asim was a hands-on architect that enjoyed being close to the building site. From the frontlines he could quickly oversee how many pyramids had been done so far and tell the builders exactly what he needed. If mistakes happened, Asim could react immediately and fix them before it was too late.

Building from the distance

Unfortunately, Asim was struck with a strange sickness that made him intolerant to high temperatures. Doctors recommended him to leave Luxor and move to Alexandria, where the weather was milder.

Despite his condition, Asim did not intend to retire anytime soon. He needed to find an effective way of managing the building site from Alexandria and keep delivering pyramids while he was away.

A couple days after settling in his new residence, Asim went back to work. , He sent very detailed instructions to the builders via the Egyptian mail.

He wrote the following:

Dear building team.

I would like you to complete the following request. 

Take noble Adom's pyramid and paint it black. Noble Kadesh apparently no longer
needs his pyramid and wants a new one in green, so we can destroy the current one
and get to work. 

Also, please refer to the notes of our last meeting
and create a blue pyramid for noble Maat. Once you are done, 
please send me a report with the latest state of all the pyramids.

Unfortunately for Asim, this is the report that got back from the construction site.

Dear Asim,

After duly following your instructions, we are pleased to report 
the current state of the building site:

- Pyramid 1 - color: red, nobleman: Adom
- Pyramid 2 - color: green, nobleman: Maat - destroyed
- Pyramid 3 - color: black, nobleman: Kadesh
- Pyramid 4 - color: blur, nobleman: Kadesh - newly created

Mayhem! The building site workers got Asim's intent mixed up! This was bad news, mistakes like these were very expensive in the pyramid business.

Building with a new message protocol

Asim had to think about a better way of communicating his wishes to the builders. He understood that he needed to modify the pyramids from a distance, and once the request was sent, the work would get started and there's nothing he could do if things would go in the wrong direction.

To make sure everything worked well, he created a message protocol with the following properties.

Whenever Asim requested something from the building team, he would write very clearly which action should be performed.
The messages would be very very simple. A message could only contain one action at a time to make sure the construction site did not mess the instructions up.
If he would like to know what's the state of the pyramids, he would write GET at the beginning of the message.
If he needed to commission a new pyramid, he would start the message with the word POST. To change an attribute in an existing pyramid, he would use PATCH.
If a pyramid would need to be demolished, Asim would write DELETE at the beginning of the message.
To minimize confusion, there would be no context in a request. No reference to previous meetings, past work or other documentation. All the information needed to carry out the work would be in the message itself.
The building team should always write back after receiving a letter with the results of their work. If they did not understand the instructions, they should write back immediately asking for clarification and not do any work at all.

Despite his health, Asim went back to Luxor for a week to teach his new messaging protocol to the building team. When he came back to Alexandria, he was excited and ready to get started. First, he wanted to get an overview of all the pyramids in the construction site. His first request looked like this.

GET pyramids

And he got back in response:

success

- Pyramid 1 -> please send GET pyramids/1 for more details
- Pyramid 2 -> please send GET pyramids/2 for more details
- Pyramid 3 -> please send GET pyramids/3 for more details
- Pyramid 4 -> please send GET pyramids/4 for more details

Excellent! The message protocol was working. After receiving this message, Asim enquired about the details of pyramid 3

GET pyramids/3

Gladly, Asim got the details he expected

success

pyramid 3
color: black
noble: Chasisi

He then requested a new pyramid for his good friend Baahir, a well-known scholar in Luxor.

POST pyramids

color: black
noble: Baahir

To the delight of his eyes, Asim got the following response

success

created pyramid 5
color: black
noble: Baahir

Asim also wanted to know if the builders were diligent when a message was not well written. To test them, he wrote an incomplete request:

POST pyramids

color: black

The building team spotted the error on the message and responded with:

error on new pyramid request

Original request:
 color: black

Please send a new POST request including both the **color** and the **nobleman**.

The protocol was working wonders! If he needed to change a pyramid, all he needed to do is a short PATCH message. For instance, if he wanted to change the color of the pyramid for his friend Rashida to red, it would be something like.

PATCH pyramid/4
color: red

or if he needed to demolish the first pyramid

DELETE pyramid/1

Tying the Pyramids back to the Web

This little contrived tale you read aims to illustrate some of the key ideas behind REST in a palatable manner. Let's bring them back to the realm of software development.

REST is about clients and servers

The REST architectural style imposes a client-server constraint, so both parts of the system can communicate and evolve completely independently. In our tale, our unwavering architect acts as the client when he moved to Alexandria*.* The building team at the construction site represents the server.

In REST, clients and servers exchange information about resources

Our little story revolves around the idea of pyramids that are inspected, built, edited and destroyed. In REST parlance, the pyramids map to the idea of a resource. Resources are, broadly speaking, domain models or services that are exposed by an application. Some examples:

In the Trello API, some of the resources are boards, lists, and cards.
The Stripe API exposes resources such payments, refunds, subscriptions, orders and much more.
Simple APIs like PokeAPI exposes all the pokemon ever as resources.

Client and Server communicate with requests and responses

Asim sent letters to the building site. On the web, clients send requests to servers over the http protocol. Technically, you could have a REST architecture without using http. It's just not very frequent.

As requests, the client uses:

an HTTP verb, which declares what action will be done with the resource of operation to perform. Just like in the tale, http verbs also are GET, POST, PATCH and DELETE. There's a few more, in case you are interested.
a header, which allows to pass additional metadata about the request. The messages in our tale did not cover headers to keep it simple.
a unique path to a resource. In the tale, we had /pyramids, and /pyramids/:id . In the real world, you might find similar paths like https://api.trello.com/1/boards/:id
an optional message body. Some requests might need additional information for the server to its job. In the story, Asim would add the details of a new pyramid whenever he POSTed to the building site, so the builders knew what needed to be done.

The workers in the building site always sent a letter back to Asim as a response. In REST, the server responds with a response when a request comes through. A response should contain:

a status code, which flags what was the result of the operation on the server. In the story, we simplified these with success and error . The http protocol uses a bunch of numeric response codes that give you more detail on what happened, you can learn more about them here
a response body, which contains data the client can use. In the world of REST APIs, this is usually JSON, but XML data or media files are also possible.

REST Resources should behave like hyperlinks on the web

In our story, Asim requested for all information about all his pyramids, and the response included information on how to get information for a specific pyramid, allowing him to send a follow-up request.

This is another crucial aspect of REST pattern. Just like a Wikipedia article links to other articles that are related, a response should contain all the information needed to dig deeper.

For instance, say you wanted my github profile information from api.github/users/libsyz. The response you get will look like this

{
  "login": "libsyz",
  "id": 22333041,
  "node_id": "MDQ6VXNlcjIyMzMzMDQx",
  "avatar_url": "https://avatars.githubusercontent.com/u/22333041?v=4",
  "gravatar_id": "",
  "url": "https://api.github.com/users/libsyz",
...

If you wanted to get the avatar image, you don't need to second-guess the path or look it up the docs, the response itself lets you know what is the path that you need to get it.

No context kept between requests

After coming up with the protocol, Asim's messages could be processed independently. They don't rely on previous knowledge by the building site, or information contained in a separate request.

If our architect hired a larger team of architects working remotely from Alexandria and opened several building sites in the future, the current message protocol would still be reliable.

This is possible because all the requests are stateless, and it's another key design characteristic in the REST pattern. Client context and knowledge cannot be stored on the server between requests. This property keeps client and server decoupled, making the whole system tidier and easier to manage.

This has deeper implications. The client does not even need to know who is the server, or if there are different servers taking care of different requests. The server does not need to what is being done with the responses and any implementation details on the client side.

This also helps with scalability on the server side ( imagine a bunch of services being ran by several servers, but all under the same API umbrella ) and the client side ( both a mobile app and a desktop can consume the same API but do different things with the data they consume.

This is just the beginning - go start building!

This pyramid story is an accessible yet incomplete analogy. My drawing skills are questionable to say the least. The explanations above are by no means exhaustive of what is REST and what it solves for. I have not covered other key concepts like cacheability, versioning or code on demand. Yet, I hope it gave you a better starting point to explore a design pattern that is crucial in web development and the modern API economy. I hope this post helped you if you were trying to make sense of what REST is and the problem it solves for, thanks so much for reading!

Modern Ruby Web Automation and Scraping with Ferrum

Miguel Jimenez — Tue, 23 Jun 2020 11:49:15 +0000

This is a little step-by-step tutorial meant to help our bootcamp students during their project weeks. It covers two things:

Web Browser Automation - During your project weeks, we would like you to spend as much time as possible shipping features, and little time doing manual testing. Our first case in the tutorial covers Foot Traffic, a gem developed by Le Wagon that will help you automate user interaction with your web app with ruby code.
Scraping - Your project might need better data that what the Faker Gem can provide, which means you need to scrape data from somewhere (legally of course). The second part covers how to use Vessel, a gem optimized for scraping.

If you are the reader type, follow along! If you prefer to see it live before diving into the code, check out the videos recorded by our lead teacher Prima Aulia Gusta (Web Browser Automation Video and Scraping Video).

For the curious

Both Foot Traffic and Vessel are built on top of Ferrum, a gem that gives you a high-level API to interact with Chrome. It's easy to use, super fast, thread safe and feature rich.

Foot Traffic is a wrapper for Ferrum that extends its API to manipulate different tabs at the same time. While it's no substitute to integration tests, using Foot Traffic is awesome to simulate how your application behaves when multiple users access it at the same time.

Vessel is a web crawling framework built on top of Ferrum. It gives you an easy way to extract information from websites. Perfect if the data you need for your project is not provided by an API.

You can learn more here:

Enough with the intro, let's dive into it.

1. Web Browser Automation with Foot Traffic

We are going to get started with Foot Traffic, we'll be using scrapethissite for the example, which allows for automated browsing without restrictions.

1.1 Install Foot Traffic

On your terminal, run the following

mkdir foot-traffic 
cd foot-traffic
bundle init

This will create a Gemfile. Open it in your code editor and add

gem 'foot_traffic'

Proceed to install the gem with

bundle install

1.1 Simulating a Login

We'll try to login to this website automatically with Foot Traffic.

Let's create the file that will hold our script on the terminal

touch foot_traffic.rb

After that, we need to require the gem, declare that we are using FootTraffic on the global namespace, and start a session.

The session will give us access to a window object, and that window object can instantiate tabs that work in parallel. For now, we'll just work with one tab and we'll go to the website


require 'foot_traffic'
using FootTraffic

FootTraffic::Session.start do |window|
  window.tab_thread { |tab| tab.goto "https://scrapethissite.com/pages/advanced/?gotcha=login"}  
end

When you run this script on ruby, an instance of chrome on autopilot will display something like this.

On the login page, we can inspect its css to understand which elements we need to interact with. If you check it out with your dev tools, we have two inputs with '[name="user"]' and '[name="password]' . Ferrum gives us the #at_css method to target an element, and we can then subsequently user #focus and #type to enter an input.

#type takes multiple parameters, and you can enter key actions like enter or tab. We'll use :enter after writing the password to submit the form.

require 'foot_traffic'
using FootTraffic

FootTraffic::Session.start do |window|
  window.tab_thread do |tab| tab.goto "https://scrapethissite.com/pages/advanced/?gotcha=login"
        tab.at_css('[name="user"]').focus.type('primaulia')
        tab.at_css('[name="pass"]').focus.type('secret', :enter)
  end

When you do this, it might be that Chrome perform the actions before all resources are loaded, resulting in errors and unexpected behavior. You can add options to throttle the speed of your actions and customize timouts.

require 'foot_traffic'
using FootTraffic

opts = { 
    process_timeout: 10, # How long to wait for Chrome to respond on startup
    timeout: 10, # How long to wait for a response
    slowmo: 0.3, # pace of the actions
    window_size: [1024, 768] 
} 

FootTraffic::Session.start(options: opts) do |window|
  window.tab_thread do |tab| tab.goto "https://scrapethissite.com/pages/advanced/?gotcha=login"
        tab.at_css('[name="user"]').focus.type('primaulia', :tab)
        tab.at_css('[name="pass"]').focus.type('secret', :enter)
  end
end

If you run the script from your terminal with ruby foot_traffic.rb , you should be able to login successfully and see something like this.

1.2 Navigating

Now, let's imagine we just want to browse through this site and make sure all the data on the tables display correctly. Let's open a new tab that goes to the site

require 'foot_traffic'
require 'pry-byebug'

using FootTraffic

opts = {
  process_timeout: 10,
  timeout: 100,
  slowmo: 0.1,
  window_size: [1024, 768]
}

FootTraffic::Session.start(options: opts) do |window|
  window.tab_thread do |tab| tab.goto "https://scrapethissite.com/pages/advanced/?gotcha=login"}  
    tab.at_css('[name="user"]').focus.type('primaulia', :tab)
    tab.at_css('[name="pass"]').focus.type('secret', :enter)
  end

  window.tab_thread do |tab| tab.goto "https://scrapethissite.com/pages/ajax-javascript/"
  end
end

This should take you to a database of Oscar Award winning movies.

As the url indicates, all the lists are loaded via AJAX requests. All our elements have ids that go from 2010 to 2015. We can iterate through the elements at a slower pace to make sure the ajax request comes back.

Using css selectors with numbers is tricky, so we'll use xpath this time to stay safe when going through the different years.

require 'foot_traffic'
using FootTraffic

opts = { 
    process_timeout: 10,
    timeout: 100,
    slowmo: 0.2,
    window_size: [1024, 768]
} 

FootTraffic::Session.start(options: opts) do |window|
  window.tab_thread do |tab| tab.goto "https://scrapethissite.com/pages/advanced/?gotcha=login"}  
        tab.at_css('[name="user"]').focus.type('primaulia', :tab)
  end

    window.tab_thread do |tab| tab.goto "https://scrapethissite.com/pages/ajax-javascript/"
      2010.downto(2005) do |year|
            tab.at_xpath("//*[@id=#{year}]").click          
            sleep 2
        end
    end
end

Now we should be able to browse through the tables programmatically, while at the same time the login happens on a separate tab.

And that's it! Feel free to take it from here to automate interactions with your own project 🚀. A great thing about Foot Traffic is that the browser will remain open after finding an error, so you can go back to manual mode to see what happened and explore logs.

Scraping with Vessel

Foot Traffic is fantastic for automating user interaction, but it gets cumbersome if you want to extract data from a website. For that, you might want a tool like Vessel.

Let's imagine that you want to build an aggregator that assesses all the food delivery platforms, and rates them according to a number of dimensions.

For such purpose, you might want to get some data from deliveroo.sg . As of time of writing, they provide an API for their partners so they can manage their orders, but they don't expose their restaurant data. Time to scrape.

Important note:

Make sure that when you scrape a website, you are actually allowed to do it. You can check the website's robots.txt to see permissions. Always make sure you understand the legal constraints of scraping. This article makes a great summary of what to bear in mind. When this article was written, deliveroo.sg did not hold any scraping restrictions. Make sure you check before scraping their website, or any other website.

2.1 Install Vessel

Go to your Gemfile and add the following

gem 'vessel'

In your terminal, create a new file that will hold the Vessel scraper and install the gem

touch scraper.rb
bundle install

To scrape with Vessel, you need a class that:

Inherits from Vessel
Has a parse method
Has a domain
Has start_urls to go and scrape

require 'vessel'

class DeliverooScraper < Vessel
    domain 'deliveroo.sg'
    start_urls # need some urls to scrape

    def parse
        # need code that does magic data extraction
    end
end

2.2 Finding some URLs to Scrape

Now, we need to check what is the url structure of the pages we want to scrape. When we arrive at delilveroo, we are asked for a postal code number. After submitting, we'll be shown a collection of restaurants that we can scrape. The url looks like this:

https://deliveroo.com.sg/restaurants/singapore/kallang-lavender?fulfillment_method=DELIVERY&postcode=339696

So we can go an assume that there are two dynamic variables involved, the district name and the postal code. Let's try these on our browser

https://deliveroo.com.sg/restaurants/singapore/katong?fulfillment_method=DELIVERY&postcode=424876
https://deliveroo.com.sg/restaurants/singapore/novena?fulfillment_method=DELIVERY&postcode=308215

They work! To figure out the postal code names, you can enter a valid Singaporean postal code, and you will get how the district is named on the url.

2.3 Setting up our Scraper

First, let's add the urls we got to the Scraper class

require 'vessel'

class DeliverooScraper < Vessel
    domain 'deliveroo.sg'
    start_urls ["https://deliveroo.com.sg/restaurants/singapore/katong?fulfillment_method=DELIVERY&postcode=424876",
                         "https://deliveroo.com.sg/restaurants/singapore/novena?fulfillment_method=DELIVERY&postcode=308215"]

    def parse
        # need code that does magic data extraction
    end
end

This is the job of our parse method. We can use xpath and css selectors. All css attributes are stamped on deliveroo, which makes the structure of the website harder to parse. We'll go with xpath to extract the data within the cards.

Now that we have the xpath, let's add the code that will collect the data for us automatically.

require 'vessel'

class DeliverooScraper < Vessel
    domain 'deliveroo.sg'
    start_urls "http://deliveroo.sg/"

    def parse
        restos = xpath('/html/body/div[1]/div/div/div[2]/div/div[2]/div/ul/li[3]/span/div/div/div[2]/div/ul/li')
        restos.each do |resto| 
        (name, distance, rating, category) = resto.at_css('a').attribute("aria-label".to_sym).split('. ')
        yield({
        name: name,
        rating: rating,
        distance: distance,
        category: category
      })
        rescue
        next
    end
    end
end

xpath selects all the elements that respond to our xpath, which we call restos. For each resto, we can fetch the name, distance, rating and category by manipulating the info stored in the aria-label attribute.

After that, we use yield the data we got into a hash. We add a rescue to prevent the scraper from crashing in case one element does not respond exactly to the pattern we identified.

2.4 Running our Scraper

To fetch the data, we just need to call run on the Scraper and make sure we have a place where we can store the data.

require 'vessel'

class DeliverooScraper < Vessel
 # ....
end

restaurant_data = []

DeliverooScraper.run { |resto|  restaurant_data << resto.to_json }

puts restaurant_data

Now, in the terminal you can do something like this.

ruby scraper.rb >> restaurant_data.json

And the restaurant will be waiting for you in a json file that you can use for your project seeds. Thanks deliveroo! 🤗🦘

Thanks for Reading!

This tutorial has been brought to you by Prima Aulia Gusta and Miguel Jimenez. We are part of Le Wagon in Singapore 🇸🇬. Our immersive coding bootcamps build the tech skills and product mindset you need to kick-start your tech career, upskill in your current job, or launch your own startup.

If you want to exchange thoughts on how to create outstanding learning experiences in tech feel free to contact me at miguel.jimenez@lewagon.org.

4 ways to clean ranged comparisons in Ruby conditionals

Miguel Jimenez — Mon, 15 Jun 2020 08:14:26 +0000

What is the best way to go when we find conditionals that deal with ranges?

fruits = 0
if age > 5 && age < 10
        fruits += 100
elsif age >= 10 && age < 15
    fruits += 200
end

One part of the problem is that there are way too many ways to express the conditions

# all these conditions are the same
# first
if age > 5 && age < 10
if 5 < age && 10 > age
if age > 5 && 10 < age
if 5 < age && age < 10
# second
elsif age >= 10 && age < 15
elsif age >= 10 && 15 > age
elsif 10 <= age && age < 15
elsif age => 10  && age < 15

A few tips that I find helpful:

1. No greater than `>`

You can make the boundaries of the range more readable if you limit yourself to the < operator.

fruits = 0
if 5 < age && age < 10 # 5 |---- age is here -----| 10
    fruits += 100
elsif 10 <= age && age < 15 # 10 |---- age is here -----| 15
    fruits += 200
end

Llewelyn Falco has a nice blog post where he covers this technique in depth.

2. Use `Range`

Using Ruby ranges are a good way to represent the conditions, and using .. versus ... can act as a substitute for ≥ or ≤

fruits = 0
if (6...10).include?(age) # 6 |---- age is here -----| 10
    fruits += 100
elsif (10...15).include?(age) # 10 |---- age is here -----| 15
    fruits += 200
end

3. Use `case` statements

Took me a while to realise this, but when you use case statements, what you are really doing is comparing two things with the threequals operator ===

The cool thing about it is that when you use === with ranges, you are checking for inclusion within the range.

(1..5) === 2

#=> true

Which means we can write something like this

fruits = 0
case age
when 6...10
    fruits += 100
when 10...15
    fruits += 200
end

4. Use `#between?`

The #between method gives us an idiomatic way to resolve comparisons. Even if it does not work perfectly well for our example due to the mixed presence use of > and ≥ in both conditions, it's good to know we have this in the Ruby toolkit

fruits = 0
case age
if age.between?(6,10)
    fruits += 100
elsif age.between?(10,15)
    fruits += 200
end

Tracking global variables in Ruby with #trace_var

Miguel Jimenez — Fri, 12 Jun 2020 06:43:50 +0000

An not-so-well-known feature of Ruby is #trace_var, which allows to listen to changes in a variable and execute a callback.

$counter = 0

trace_var :$counter do |number|
    puts "the counter is on #{number}"
end

10.times { $counter +=  1 }

#=> the counter is on 1
#=> the counter is on 2
#=> the counter is on 3
# ...

The concept of tracing changes in a variable is interesting - Different objects can listen to these changes, and coordinate their work without stepping in each other's toes. Let's build a simplified Fizz! and Buzz! yellers using #trace_var

class FizzBuzzer
  def initialize(*predecessors)
    trace_var :$counter, ->(number) do
      yell if yelling_condition
    end
  end

end

class Fizz < FizzBuzzer
  def yell
    puts "Fizz!"
  end

  private

  def yelling_condition
    $counter % 3 == 0
  end

end

class Buzz < FizzBuzzer
  def yell
    puts "Buzz!"
  end

  private

  def yelling_condition
    $counter % 5 == 0
  end

end

class NoFizzBuzz < FizzBuzzer
  def yell
    puts "#{$counter}"
  end

  private

  def yelling_condition
    $counter % 3 != 0 && $counter % 5 != 0
  end

end

$counter = 0

fizz = Fizz.new
buzz = Buzz.new
no_fizz_buzz = NoFizzBuzz.new

15.times { $counter += 1 }

While the idea of listening to global variables to drive business logic does not seem sound for production code, you can certainly use #trace_var during debugging to see what could be messing with global variables.

trace_var :$some_global_variable do |value|
  puts "$some_global_variable = #{value}"
  puts caller
end

But if you are certainly in need of tracing variables and set callbacks in depth, Ruby takes this concept further with its TracePoint API.

Composition in Ruby with the >> operator

Miguel Jimenez — Thu, 11 Jun 2020 15:09:14 +0000

In Ruby, you can compose behavior and make arguments flow from to proc to proc using the >> operator.

Let's say I want the addition of two numbers

add = proc { |first, second| first + second }
add.call(1,2)
# => 3

Let's say I would also like my program to square numbers

square = proc { |number| number ** 2 }  
square.call(2)
# => 4

Now, I would like the program to perform one action after the other. First add two numbers, and then square them

add_then_square = square.call(add.call(1,2))
# => 9

I tried composing two simple functions and I don't like where this is going. Now need to read the line from left to right. This is when the >> operator comes in to make our day.

add_then_square = add >> square
add_then_square.call(1,2)
# => 9

You can also reverse the order of operations by using <<

greet = proc { |name| "Hello, #{name}!" }
sanitize_name = proc {|name| name.capitalize }

say_hello = greet << sanitize_name
say_hello.call("BENDER")

# =>  "Hello, Bender!"

And we do not even have to assign multiple procs to a variable in order to call them.

total = 0
appetizer = proc { total += 10 }
salad = proc { total += 15 }
dessert = proc { total += 6 }

(appetizer >> salad >> dessert).call

# => 31

All this makes composing and pipelining behavior really easy. Procs are, however, one of the very few things in Ruby that are not objects. We need to add a bit of indirection to our methods if we want to make them compatible with >>.

def sanitize_name
    proc { |n| n.capitalize }
end

def verify_robot
    robot_names = %w(Bender Marvin Kitt)
    proc {|n| n if robot_names.include?(n) }
end

def greet
    proc {|n| "Hello ,#{n}!" }
end

join_robot_army = sanitize_name >> verify_robot >> greet
join_robot_army.call("BENDER")

# =>  "Hello, Bender!"

Ruby is famous for being an OOP-first language, but it has tremendous support for function composition and creating pipes. The >> operator is part of it, but you also have beautiful pieces of handy syntax like #then, #yield_self and ===.

Array Set Operators in Ruby

Miguel Jimenez — Tue, 09 Jun 2020 11:01:26 +0000

Ruby comes equipped with a bunch of amazing operators for Arrays.

Let's say I am working on lists of animals.

animals_list = %w(duck tiger snake)
other_animals_list = %w(wolf duck tiger)

I might want to merge both lists, without duplicates.

master_list = animals_list.concat(other_animals_list).uniq

#=> ["duck", "tiger", "snake", "wolf"]

Semantically, it feels too heavy to do two method calls for something so intuitive as a list without duplicates. Gladly, Ruby gives us the union operator

master_list = animals_list | other_animals_list

#=> ["duck", "tiger", "snake", "wolf"]

How neat is that?

I might also want to extract which animals are common to both lists. Let's say I do something like

all_animals = animals_list.concat(other_animals_list)
common_to_both = all_animals.keep_if { |animal| all_animals.count(animal) > 1 }.uniq

#=> ["duck", "tiger"]

common_to_both = all_animals.select {|animal| all_animals.count(animal) > 1 }

#=> ["duck", "tiger"]

Both approaches are heavy-handed and require two variable declarations. Again, Ruby has us covered with the intersection operator

common_to_both = animals_list & other_animals_list

#=> ["duck", "tiger"]

We also can use the subtraction operator to compare arrays and see elements that are not shared

uniq_to_animals_list = animals_list - other_animals_list
#=> ["wolf"]

uniq_to_other_animals_list = other_animals_list - animals_list
#=> ["snake"]

Another neat thing is that we can combine these operators with the equals operator. Let's say I want to update a list with elements of other lists, but I don't want to keep any duplicates.

dirty_animal_lists = [["dolphin", "duck", "duck", "duck"],["lemur", "snake", "snake", "snake"]] 

dirty_animal_lists.each_with_object([]) { |list, clean_list| clean_list |= list }

#=> ["duck", "tiger", "snake", "dolphin", "lemur"]

The only downside to this approach is that animals_list gets reassigned every single iteration and it might be too inefficient if you are working with huge things. For such cases, take a look at the Set documentation.

Learning AJAX made easy - Build an app with htmx

Miguel Jimenez — Mon, 08 Jun 2020 10:34:02 +0000

I recently stumbled upon htmx. It's a javascript library allows you to run ajax requests, server side events and websockets directly from your html. No extra JavaScript needed, clean and to the point. Why do I think it's one of the coolest things I've seen lately?

For one, at the moment most of my dev work involves building small apps, prototypes and automating processes. I love anything that reduces the amount of work on the front end.

Beyond that, I take care of running a coding bootcamp in Singapore. My students, who arrive with 0 web development knowledge, often struggle with understanding AJAX. Any tool that eases the learning process is more than welcome.

Thus, I decided to write a get-started tutorial about htmx.

About htmx

htmx is the heir to intercooler.js. It uses html attributes to trigger AJAX calls. You can use the attributes to target an element in the dom, and replace it with the html that comes back in your response. The library supports websockets and server-side events too.

It's beautiful simplicity. Basically you can write html like this

<form class="nes-select is-dark">
    <!-- have the selection form send a value via AJAX -->
      <select hx-get="/fighters"
                      name="fighter"
                      hx-target="#fighter-avatar"
                      hx-swap="outerHTML">
          <option selected> -- select a fighter -- </option>
          <option value="ryu">Ryu</option>
          <option value="sagat">Sagat</option>
          <option value="chunli"> Chun-Li </option>
    </select>
  </form>

And start building something like this. No page reloads, no additional JS.

htmx does not bring the sophistication of React or Vue, and it doesn't have to. The library excels at reducing the amount of moving pieces when implementing common UI patterns. There's excellent examples in their documentation.

Wait, what's AJAX?

AJAX stands for Asynchronous JavaScript and XML. It's a technique for creating dynamic webpages. The client and the server can exchange data in the background, and the browser's javascript can parse what the server sends to update the website without page reloads.

Features like infinite page scrolls or immediate search suggestions are powered by AJAX. The cool thing about htmx is that we can implement these features writing any javascript ourselves.

A to-do list for Ryu

Here's a tutorial on how to build a yet-another-crud-to-do app with htmx. Sinatra will work as our backend and nes.css will help us with styling. By the end of the walkthrough, we'll end up with something like this.

If you are familiar with the stack and want to jump directly to the htmx code examples, skip to the second feature right away or get the code. Take it from here if you want to build it step by step.

Setup

1. Install Sinatra

Sinatra is a lightweight web application framework written in Ruby that wraps all the goodness of Rack middleware into a convenient DSL. It's super handy for building small apps and APIs. Assuming you have Ruby and Bundler installed, start a new project folder and type the following in your terminal.

bundle init

open your Gemfile and add:

gem "sinatra"

and install the gem with:

bundle install

Now, let's create an app.rb file where we will keep the app and routing logic, and a folder named public where we will keep our css ( Sinatra uses this folder to serve assets by default )

# in your project folder 

touch app.rb && mkdir public

In the app file, we'll require sinatra and write our first route

# app.rb

require 'sinatra'

get '/' do
    "Welcome to your app!"
end

Now run:

ruby app.rb

That will run the app on port 4567 in your localhost. Go to your favorite browser and type http://localhost:4567. You should see something like this.

2. Install htmx

For now, we are going to import htmx directly in our main page. First, let's create a folder named views (sinatra uses ./views as a default for rendering templates) and touch a file called index.erb inside

mkdir views
touch views/index.erb

erb (embedded Ruby) allows us to write Ruby into our html. Our index.erb file work as a template where we will inject other html dynamically.

Within you index file, start an html skeleton and add the htmx llibrary in the document head.

<!-- views/index.erb --> 

<html>
    <head>
      <meta charset="UTF-8">
      <title>htmx + sinatra ftw</title>
        <script src="https://unpkg.com/htmx.org@0.0.4"></script>
    </head>
    <body>

    </body>
</html>

3. Set up the Front End

We'll use nes.css, an 8-bit themed library to style our app. Add it on the head of your index.erb file. Also, create a style.css file in your public folder.

touch public/style.css

<!-- views/index.erb --> 

<html>
    <head>
      <meta charset="UTF-8">
      <title>htmx + sinatra ftw</title>
        <script src="https://unpkg.com/htmx.org@0.0.4"></script>
        <link href="https://unpkg.com/nes.css@latest/css/nes.min.css" rel="stylesheet">     
        <link rel="stylesheet" href="./style.css">
    </head>

    </body>
    </body>
</div>
~~<~~/html>

The tutorial is focused on the interaction of between htmx and sinatra, so I won't be covering the css in depth. Copy the code on this gist and paste it on your style.css file. On your html, make sure you are importing the style.css after the nes.css library. You can go here to have an overview of how the css components work.

We're all set up, let's go into building the app!

Spec 1: Displaying Tasks

1. Create a Task Model

We need to represent the notion of a task. Let's keep it really simple:

A task has a description
A task can be done or not.
A new task should not be done by default.
We can mark a task as done
We can check if it's done or not.

In a file called task.rb we'll create a Task class that benefits from ruby Structs to get the job done

touch task.rb

# task.rb

class Task < Struct.new(:description, :done)
    def initialize(description, done = false)
      super
    end

    def mark_as_done!
      self.done = true
    end

    def done?
      done
    end
end

2. Create a Task Repository

There needs to be a place where we keep our tasks and manage them. The task repository will do exactly that. First, create a task_repo.rb file.

For now, we'll start off the class with a couple of tasks already so we can show them on the index page. We will also set an #all method that allows us to access the tasks. A #seed method called on initialization will set a couple of tasks in the list for us already.

touch task_repo.rb

# task_repo.rb

require_relative 'task'

class TaskRepo
    def initialize
    @tasks = []
    seed
  end

  def all
    @tasks
  end

  private

  def seed
    @tasks << Task.new("Meet Ken") << Task.new("Practice my hadouken")
  end
end

Now, we have two jobs to do. First, getting access to the repository that we just created, and then passing the tasks over to a template. Go to the app.rb file and add the following before your first get route:

#app.rb

require_relative 'task_repo'

class Sinatra::Application
    def initialize
      @tasks = TaskRepo.new
      super
    end
end

get '/' do

This little trick will make a new instance of our repository available across the Sinatra App, keeping our tasks alive as long as the server runs.

4. Create the tasks list

Add the following lines to your app.rb file. They will make the get route to 'localhost:4567' render the tasks file into index.erb file we wrote before.

#app.rb

#...

get '/' do
    erb :tasks, layout: :index
end

Now, let's flesh out the view. We need to iterate through the tasks on the repo, and display their descriptions. Create a tasks.erb file in your views folder and add the following:

touch views/tasks.erb

<!-- views/tasks.erb --> 

<ul class="nes-list is-disc">
  <% @tasks.all.each do |task| %>
    <li> </p> <%= task.description %> </p>
  <% end %>
</ul>

The <% %> tags that you see are the syntax that allow you to use ruby code within html. The subtle differences are:

Whenever we wrap code in <% %>, we execute it as ruby code, but we don't render it on the page
When we use <%= %>, we render the ruby code that sits inside the tags.

So with the snippet above we are iterating through the tasks, and rendering each of the tasks within an unordered list.

Now we, can adjust the index.erb layout so the tasks show up.

<!-- views/index.erb -->

<body> 
    <div class="nes-container main">
    <div class="list">
      <div class="list-title">
        <h2> Ryu's to-do list </h2>
        <img class="ryu" src="./ryu_8_bit.png" alt="ryu">
                <!-- you might have to source your own ryu image --> 
      </div>
      <%= yield %>
    </div>
</body>

The keyword yield is what Ruby uses to call blocks that have been passed to a method. In this context, yield will call the template that we are choosing on the get '/' route and render it.

When you run your server with ruby app.rb on your terminal, you should be be able to see the tasks.

Spec 2: Adding Tasks

For now it's all been static. Let's spice things up with htmx.

We can start by creating a form where we can write tasks and a button that allows us to submit them. Add the following after to your .list element in index.erb, but still within .nes-container

<!-- views/index.erb --> 

<div class="nes-container main">
    <div class="list">
    ....
 </div>

    <form class="nes-field">
          <input class="nes-input" id="task-form" name="task" type="text" placeholder="new task"/>

    **      <button hx-post="/tasks"
                  hx-include="input[name='task']"
                  hx-target=".nes-list"
                  hx-swap="outerHTML"
                  class="nes-btn is-primary">
              Add Task
          </button>
     </form>

</div>

Now, check out all the hx- attributes on the button. Whenever click the button is clicked, the following will happen:

Send a post request to /tasks
In the parameters of the post request, include the value in the input with the name 'task'. ( You can pass any css selector into hx-include )
Inject the response into the element with the class .nes-list, which is in our tasks template.
hx-swap="outerHTML" indicates that the whole element should be replaced

And all that interactivity beautifully expressed in 4 lines of markup. There's no need to declare the click event, since requests are triggered by the "natural" event of an element.

Now, if you try that out, you will get a 404 error. We need Sinatra to handle the request and send html back. Go to app.rb and add the following.

#app.rb

post '/tasks' do
    @tasks.all << Task.new(params['task'])
    erb :tasks
end

This will refresh our tasks with the new addition. The good news is that now we can add new tasks via AJAX. The bad news is that we can also add empty tasks, and our form stays filled after submitting the task.

Spec 3: Form Cleaning and Simple Validation

Time to get something more proper. First, we need to make sure the user actually sent a task. Change your post route for the following.

#app.rb

post '/tasks' do
  if params['task'].length.positive?
    @clear_form = true
    @tasks.all << Task.new(params['task'])
  else
    @error = "please enter a task"
  end
    erb :tasks
end

So, if we have a task in the params, we will set a flag to clear the form in the view, and we'll create a new task. Otherwise, we'll pass an error message to the view. Let's replace the markup in our view/tasks.erb file for the following.

<!-- views/tasks.erb --> 

<% if @clear_form  %>
  <input class="nes-input form-error" id="task-form" hx-swap-oob="true" name="task" type="text" placeholder="new task">
<% end %>

<ul class="nes-list is-disc">
  <% @tasks.all.each do |task| %>
      <li>  <p class="nes-text"> <%= task.description %> </p> </li>
  <% end %>
 </ul>

The hx-swap-oob attribute means out-of-box swap. It allows you to do html swaps outside of the target we declared on our form, which was .nes-list. It's important that you don't nest elements with hx-swap-oob attributes if you want them to work.

It will target the element with the id #task-form and replace it, while the rest of the html will be replacing the old .nes-list element. We now get an updated list of tasks plus a fresh form.

Now, the unhappy path. Inside your .nes-list element, add the following:

<!-- views/tasks.erb --> 

<ul class="nes-list is-disc">
    <% if @error %>
      <p class="nes-text is-error"> <%= @error %> </p>
    <% end %>

    ....
</ul>

This should render the same to do list with a validation error message. The app now should be in this state.

Spec 4: Marking a Task as Done

To check off tasks, we need some way of interacting with our task list. What about inserting a span that, when clicked, sends a request for marking a given task as done? With htmx we can do something like this.

<!-- heads up, this won't work in our app --> 

<ul class="nes-list">
<% @tasks.all.each_with_index do |task, index| %>
  <li> <%= task.description %>  
        <span hx-patch=<%= "task/#{index}" %> mark as done </span>
  </li>
    <% end %>
</ul>

Unfortunately, our Sinatra backend will struggle with parsing this request. It will not recognize the patch value natively, since many browsers only support get and post.

We need a workaround to override the post method - We can include _methodas a key in the params and set "patch" as the value, which Sinatra will recognise. Frameworks like Rails also use this technique.

Thus, the view could go as follows:

When the task is not done, give the user the abilty to mark it as done.
When the task is done, let the user know with a visual cue

Let's add the following into our iterator:

<!-- views/tasks.erb --> 

<ul class="nes-list">
     ....

    <% @tasks.all.each_with_index do |task, index| %>
        <% if task.done? %>
          <li>
            <p class="nes-text is-disabled"> <%= task.description %> </p>
          </li>
      <% else %>
          <li>
            <p class="nes-text"> <%= task.description %>
              <span class="nes-text is-primary"
                        hx-post=<%= "tasks/#{index}"%>
                        hx-target=".nes-list"
                        hx-swap="outerHTML"
                        hx-include=<%="[name=_method][data-mark='#{index}']"%>> done
              </span>
              <input type="hidden" name="_method" value="patch" data-mark=<%="#{index}" %>>
            </p>
          </li>
      <% end %>
    <% end %>
</ul>

By doing so, now Sinatra can recognise the patch action, and assign it to the right to-do via the index on the array. We'll use the task id as the reference to know which task is the one to check.

patch '/tasks/:id' do
  @tasks.all[params[:id].to_i].mark_as_done!
  erb :tasks
end

By now, we can mark tasks as done.

Spec 5: Deleting a Task

Finally, let's close the tour on htmx with deleting. We'll use the same approach we had on marking tasks as done. In the same vein, we need to include an element that affords the delete action. We'll add a small 'X' icon next to the tasks that have been done to allow deletion.

<!-- views/tasks.erb --> 

<ul class="nes-list is-disc">

....

    <% @tasks.all.each_with_index do |task, index| %>
        <% if task.done? %>
      <li>
        <p class="nes-text is-disabled"> <%= task.description %>
          <i hx-post=<%= "tasks/#{index}"%>
                hx-target=".nes-list"
                hx-swap="outerHTML"
                class="nes-icon close is-small"
                hx-include=<%= "[name=_method][data-delete='#{index}']" %>>
          </i>
        </p>
          <input type="hidden" name="_method" value="delete" data-delete=<%= "#{index}" %>>
      </li>
      <% else %>
            <!-- view logic for marking task as done -->
            ....
      <% end %>
    <% end %>
</ul>

And on Sinatra, you need a route for deleting

delete '/tasks/:id' do
  @tasks.all.delete_at(params[:id].to_i)
  erb :tasks
end

Now, if the task has not been done, we can mark it as done. If the task is done, we can delete it from the list. Ryu's to-do app should now look like this

Thanks for reading!

htmx allows you to implement modern UI patterns with simple, straightforward html. I truly hope that the library continues to evolve and grow. Take a look at their documentation over here. If you feel like playing around with the app, you can get the code here. A few things you could try out with htmx to take the app further:

Add a button to delete all tasks
Make a better validation, now you could add a task made of spaces!
Disable the .task-form button by default, and only enable it when there's text on the input
Fade in the tasks when they show on screen

I’m Miguel and I take care of Product and Growth for Le Wagon in Singapore 🇸🇬. Our immersive coding bootcamps build the tech skills and product mindset you need to kick-start your tech career, upskill in your current job, or launch your own startup.