end build a URL shortener in Amber


In this tutorial, we will create a URL shortening service in Amber - one of the popular Crystal web application frameworks.</p>
</span>
</p>
Along the way, we’ll do the following:</p>


Set up a new Amber project</li>
Use the built-in scaffold generator</li>
Run through the basics of routing, controllers and templates</li>
Validate user-entered data</li>
Use UUID primary keys for generating random URLs</li>
Redirect and respond to requests </li>
</ul>
Setting up a new project</h2>
If you haven’t already, follow the instructions to install Crystal, Amber and Node as seen here</a>. This tutorial uses Crystal 0.27.0 and Amber 0.11.1 but works with Crystal 0.26.1 and Amber 0.10.0 as well. You’ll also need PostgreSQL installed as well for the database.</p>
First let's create a new Amber application, run the following command in your terminal to get started.</p>
amber</span> new shortly
</span></code></pre>
This will generate a new app named shortly using the Amber defaults, PostgreSQL for the database, and Slang for the templates. If you prefer, you can use amber new shortly -t ecr</code> to use HTML templates rather than Slang.  ECR is less efficient than Slang but more convenient if you have a HTML template to work from.</p>
Most of the code is in the src</code> directory, this includes Models, Views and Controllers. Similarly to Ruby on Rails, the routes are located in the config</code> directory.</p>
To get the server up and running use the following commands. The first one downloads Crystal dependencies, the second creates the database, and the third runs the HTTP Server and Webpack with live reloading.</p>
Note: If you want to edit the database configuration, now is the time to do so. Open config/environments/development.yml</code> and look for the database_url</code> key</em></p>
shards</span> install
</span>amber</span> db create
</span>amber</span> watch
</span></code></pre>
Open http://0.0.0.0:3000</code> to see the default home page.</p>
A brief introduction to routing</h2>
Amber uses a similar approach to Elixir Phoenix when it comes to routing by using plugs</code> and pipelines</code>.</p>
A plug is a piece of middleware that runs during a request. Lots of these will run one after the other, transforming the request depending on what was sent from the client and which route the request matches against.</p>
Some example plugs include:</p>

Amber::Pipe::Logger.new</code> - Handles the logging functionality.</li>
Amber::Pipe::CSRF.new</code> - Prevent form requests from Cross-Site Request Forgery</li>
plug Amber::Pipe::Flash.new</code> - Handles flash messages</li>
</ul>
Applying plugs to each individual route wouldn’t be an efficient way of doing things. Instead, You can group common sets of plugs together in a pipeline</em>. </p>
Amber comes with three pipelines that provide common functionality - but you can create your own, too.</p>

web</code> is for standard web requests and includes most things you’ll need.</li>
api</code> is similar to web but takes out the unnecessary plugs for APIs such as CSRF and Flash messages. It also adds in the CORS plug.</li>
static</code> is for requests to static assets.</li>
</ul>
Other useful pipelines you might want to build include authentication</code> for requests that sit behind a log-in system. Or admin</code> for requests that need user-level permissions to view admin functionality.</p>
The routes</code> function takes a pipeline’s name and a block of routes. When a route resides within the web</code> routes block, it will run all of the web</code> pipeline plugs on a matching web request.</p>
  pipeline </span>:web </span>do
</span>	plug </span>Amber</span>::</span>Pipe</span>::</span>PoweredByAmber</span>.</span>new
</span>	plug </span>Citrine</span>::</span>I18n</span>::</span>Handler</span>.</span>new
</span>	plug </span>Amber</span>::</span>Pipe</span>::</span>Error</span>.</span>new
</span>	plug </span>Amber</span>::</span>Pipe</span>::</span>Logger</span>.</span>new
</span>	plug </span>Amber</span>::</span>Pipe</span>::</span>Session</span>.</span>new
</span>	plug </span>Amber</span>::</span>Pipe</span>::</span>Flash</span>.</span>new
</span>	plug </span>Amber</span>::</span>Pipe</span>::</span>CSRF</span>.</span>new
</span>  </span>end
</span>
</span>  routes </span>:web </span>do
</span>	get "</span>/</span>", </span>HomeController</span>, </span>:static
</span>  </span>end
</span></code></pre>
If your already familiar with other web frameworks then you’ll probably know the types of requests to expect. These include get</code>, post</code>, update</code>, put</code>, delete</code> and resources</code>.</p>
For all except resources, the first parameter is URL to match against, the second is the controller class to load, and the third is the method to run.</p>
Resources, on the other hand,  takes 2 parameters: the base URL which will be expanded into various URLs for CRUD actions, and the controller class to use each request with. These will need class methods matching each URL. </p>
There is also a third, optional, parameter which lets you include or exclude specific CRUD actions.</p>
resources "</span>/user</span>", </span>UserController</span>, </span>only: </span>[</span>:index</span>, </span>:show</span>]
</span></code></pre>
Creating a new controller</h2>
Although a full scaffold</code> command exists in Amber, for this application doing the process manually allows each step to be explained and understood more thoroughly.</p>
Run the following command to create a new controller. </p>
amber</span> g controller Shortener index:get show:get create:post
</span></code></pre>
This controller will generate 3 end points:</p>

index</code> which will replace the root URL and have a form for the user to enter their desired shortened web address.</li>
create</code> which will handle the post request to generate a shortened URL.</li>
show</code> will be where the user is redirected to after submitting a URL and will show their new address to copy and share.</li>
</ul>
Delete the create.slang</code> template file as it won’t be used.</p>
rm</span> src/views/shortener/create.slang
</span></code></pre>
Opening up src/controllers/shortener_controller.cr</code> we can see that the class has three methods and also inherits from ApplicationController</code>. </p>
Looking at the src/controllers/application_controller.cr</code> file,  we can see JasperHelpers</code> which makes a few useful helper methods available including form, input and link helpers. There's also a layout variable which sets the layout template to use. This class then inherits further functionality from Amber::Controller::Base</code>.</p>
Amber::Controller::Base</code> adds in several helper modules including functionality related to CSRF, Redirects, and Rendering. It also adds the validation params</code> which is used for checking request data from the user (More on that later)</p>
Back in the shortener_controller.cr</code> remove the render("create.slang")</code> as we won't be needing it.</p>
Adding routes</h2>
Re-open the config/routes.cr</code> file and replace the :web</code> block with this.</p>
routes </span>:web </span>do
</span>  resources "</span>/</span>", </span>ShortenerController</span>, </span>only: </span>[</span>:index</span>, </span>:create</span>, </span>:show</span>]
</span>end
</span></code></pre>
Run amber routes</code> in the terminal and the three routes we have added should show.</p>
You can also see the fallback wildcard route, /*</code>. When Amber can't find a matching route it will look for static assets in the public</code> directory.</p>
</p>
Creating the model</h2>
Use the amber g model</code> command to create a new model and migration file for ShortenedUrl</code>. Links can get quite long so its safer to use text</code> rather than string</code>, as VARCHAR</code> has a limit of 256 characters.</p>
amber</span> g model ShortenedLink original_url:text
</span></code></pre>
Open up the db/migrations/x_create_shortened_link.sql</code> file. Amber uses Micrate</code>, a shard which handles migrating the database. </p>
Micrate reads the commented SQL to handle what should be run. </p>
The SQL below -- +micrate Up</code> will run when amber db migrate</code> is entered and -- +micrate Down</code> gets run when you want to rollback with amber db rollback</code>. There's also amber db status</code> to see what state your database schema is in.</p>
In this tutorial we'll use id</code> for the shortened url code. Since integers starting from 1 aren’t an ideal format for this we'll store a shortened UUID</code>.</p>
Modify the id</code> to be VARCHAR</code>, optionally set a max length e.g. VARCHAR(8)</code>.</p>
-- +micrate Up
</span>CREATE TABLE </span>shortened_links</span> (
</span>  id </span>VARCHAR</span>(</span>8</span>) </span>PRIMARY KEY</span>,
</span>  original_url </span>TEXT</span>,
</span>  created_at </span>TIMESTAMP</span>,
</span>  updated_at </span>TIMESTAMP
</span>);
</span>
</span>
</span>-- +micrate Down
</span>DROP TABLE</span> IF EXISTS shortened_links;
</span></code></pre>
Note that UUID</code>s are supported with Postgres, however, since we're trimming the length down we'll be using varchar</code>.</p>
Run amber db migrate</code>.</p>
We'll need to modify the model class to support the new id format. Open src/models/shortened_link.cr</code> and update it to the following</p>
require </span>"</span>uuid</span>"
</span>class </span>ShortenedLink </span>< Granite::Base
</span>  adapter pg
</span>  table_name shortened_links
</span>  primary id : </span>String</span>, </span>auto: </span>false
</span>  field original_url : </span>String
</span>  timestamps
</span>  before_create </span>:assign_id
</span>
</span>  </span>def </span>assign_id
</span>	potential_id = generate_id()
</span>	</span>while </span>ShortenedLink</span>.find(potential_id)
</span>	  potential_id = generate_id()
</span>	</span>end
</span>	@</span>id </span>= potential_id
</span>  </span>end
</span>
</span>  </span>def </span>generate_id
</span>    </span>UUID</span>.random.hexstring.to_s[</span>0</span>..</span>7</span>]
</span>  </span>end
</span>end
</span></code></pre>
This file has a reasonable amount of code, here’s the breakdown.</p>

Line 1 includes the UUID</code> library which is used to generate nicer IDs and shortened URL codes.</li>
Line 2 opens the class and inherits from Granite, the default ORM for Amber.</li>
Line 3 specifies that PostgreSQL is the database that’s used.</li>
Line 4 declares the table name for the model.</li>
Line 5 is the primary key, notice it’s set to a string and auto increment is turned off</li>
Line 6 is the original_url</code> field included in the schema. Any other fields should go here too.</li>
Line 7 Adds timestamp functionality for created_at</code> and updated_at</code> columns.</li>
Line 8 adds a before hook. This runs a method of the same name before new models are saved.</li>
Line 10 is the above mentioned method. Here a UUID is generated, turned into a hex string, checked for duplicates and then updates the id</code> instance property ready to be saved.</li>
</ul>
Finishing the Shortener Controller</h2>
The index</code> will return the home page where users will enter their URL, the create</code> is where the form is posted to be validated and created, and the show</code> method will give the link to the user, ready for sharing.</p>
Update the create</code> method with the following</p>
  </span>def </span>create
</span>    </span>if</span> shortened_link_params.valid?
</span>      shortened_link = </span>ShortenedLink</span>.</span>new</span> shortened_link_params.validate!
</span>      shortened_link.save
</span>      redirect_to(
</span>        </span>location: </span>"</span>/links/</span>#{</span>shortened_link.id</span>}</span>",
</span>        </span>status: </span>302</span>,
</span>        </span>flash: </span>{"</span>success</span>" => "</span>Created short link successfully.</span>"}
</span>      )
</span>    </span>else
</span>      redirect_to(</span>controller: :shortener</span>, </span>action: :index</span>, </span>flash: </span>{"</span>danger</span>" => shortened_link_params.errors.first.message})
</span>    </span>end
</span>  </span>end
</span></code></pre>
And add this private method to the controller</p>
  </span>private def </span>shortened_link_params
</span>    params.validation </span>do
</span>      required </span>:original_url </span>{|</span>f</span>| !f.nil? && f.url? }
</span>    </span>end
</span>  </span>end
</span></code></pre>
The create</code> method calls the shortened_link_params</code> method to check if the posted data is valid, if it is then it saves it to the database and redirects the user to the show</code> page. If it isn’t, the user is redirected back and is sent an error message. Notice how the validation checks if :original_url</code> is sent, if it is nil and if it is a valid url string. This parameter validation functionality comes from the Amber::Controller::Base</code> class mentioned earlier.</p>
To finish off the controller add the following to the top of it</p>
  </span>getter</span> shortened_link : </span>ShortenedLink </span>= </span>ShortenedLink</span>.</span>new
</span>
</span>  before_action </span>do
</span>	only [</span>:show</span>] { set_shortened_link }
</span>  </span>end
</span></code></pre>
And another private method to the bottom</p>
  </span>private def </span>set_shortened_link
</span>	@</span>shortened_link </span>= </span>ShortenedLink</span>.find! params[</span>:id</span>]
</span>  </span>end
</span></code></pre>
Here we’re using a before hook to set relevant model for the show</code> method, ready to be used in the template. Since there is only one method using this we could put the functionality straight into the controller show</code> method. However, it's worth demonstrating it for usage with controllers that have edit</code>, update</code>, and delete</code> functionality as well.</p>
Templates</h2>
Amber uses Slang</code> templates by default. If you’re familiar with Slim</code>/Haml</code> in Ruby then you should be in familiar terrority. HTML (ecr</code> templates) can be used as well, however they are not as efficient as Slang</code>.</p>
Update views/layouts/application.slang</code></p>
doctype html
</span>html.min-h-screen
</span>  head
</span>	title Shortly using Amber
</span>	meta charset="utf-8"
</span>	meta http-equiv="X-UA-Compatible" content="IE=edge"
</span>	meta name="viewport" content="width=device-width, initial-scale=1"
</span>	link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tailwindcss/dist/tailwind.min.css"
</span>	link rel="stylesheet" href="/dist/main.bundle.css"
</span>	link rel="apple-touch-icon" href="/favicon.png"
</span>	link rel="icon" href="/favicon.png"
</span>	link rel="icon" type="image/x-icon" href="/favicon.ico"
</span>
</span>  body.flex.items-center.min-h-screen.bg-orange-lightest.text-black.pb-8
</span>	</span>.container.mx-auto
</span>	  - flash.each </span>do</span> |key, value|
</span>		div class="alert alert-#{key}"
</span>		  p = flash[key]
</span>	  == content
</span>
</span>	script src="/dist/main.bundle.js"
</span></code></pre>
views/shortener/index.slang</code></p>
div.container.mx-auto.text-center.mb-16
</span>  h1.text-3xl.mb-8 Link Shortener
</span>  == form(</span>action: </span>"</span>/links</span>", </span>method: :post</span>, </span>class: </span>"</span>w-full max-w-md mx-auto</span>") </span>do
</span>	== csrf_tag
</span>	</span>.flex.items-center.border-b.border-b-2.border-black.py-2
</span>	  == text_field </span>name: </span>"</span>original_url</span>", </span>value: </span>"", </span>placeholder: </span>"</span>http://</span>", </span>class: </span>"</span>appearance-none bg-transparent border-none w-full text-grey-darker mr-3 py-1 px-2 leading-tight</span>"
</span>	  == submit("</span>Create Link</span>", </span>class: </span>"</span>flex-no-shrink bg-teal bg-black border-black border-black text-sm border-4 text-white py-1 px-2 rounded</span>")
</span></code></pre>
views/shortener/show.slang</code></p>
div.container.mx-auto.text-center.my-8
</span>  h1.text-3xl.mb-8 Link Shortener
</span>  h2.text-2xl.mb-4 Your link
</span>  p
</span>	  == link_to "</span>http://</span>#{request.host_with_port}</span>/</span>#{@</span>shortened_link</span>.id}", "</span>http://</span>#{request.host_with_port}</span>/</span>#{@</span>shortened_link</span>.id}"
</span>  p.button-link
</span>	  == link_to "</span>Create a new link</span>", "</span>/</span>"```
</span></code></pre>
src/assets/stylesheets/main.scss</code></p>
.</span>alert-danger </span>{
</span>  background-color: </span>#e3342f</span>;
</span>  color: </span>#fff</span>;
</span>}
</span>.</span>alert-success </span>{
</span>  background-color: </span>#38c172</span>;
</span>  color: </span>#22292f</span>;
</span>}
</span>
</span>.</span>button-link </span>a </span>{
</span>  text-decoration: none;
</span>  display: inline-block;
</span>  margin-top: </span>.5rem</span>;
</span>  background-color: </span>#22292f</span>;
</span>  background-color: </span>#22292f</span>;
</span>  border-color: </span>#22292f</span>;
</span>  border-color: </span>#22292f</span>;
</span>  font-size: </span>.875rem</span>;
</span>  border-width: </span>4px</span>;
</span>  color: </span>#fff</span>;
</span>  padding-top: </span>.25rem</span>;
</span>  padding-bottom: </span>.25rem</span>;
</span>  padding-left: </span>.5rem</span>;
</span>  padding-right: </span>.5rem</span>;
</span>  border-radius: </span>.25rem</span>;
</span>}
</span></code></pre>
A preview of the create page</em></div>
![Preview of creation page](/images/amber-shortly-create.png)
Handling the Redirect</h2>
Run the following command to create a new controller</p>
amber</span> g controller redirect show:get
</span></code></pre>
And add the new route to match the controller in confi/routes.cr</code> in the :web</code> block</p>
get "</span>/r/:id</span>", </span>RedirectController</span>, </span>:show
</span></code></pre>
Then update the RedirectController</code> to the following</p>
class </span>RedirectController </span>< ApplicationController
</span>
</span>  </span>getter</span> shortened_link : </span>ShortenedLink </span>= </span>ShortenedLink</span>.</span>new
</span>
</span>  before_action </span>do
</span>    only [</span>:show</span>] { set_shortened_link }
</span>  </span>end
</span>
</span>  </span>def </span>show
</span>    redirect_to(</span>location: </span>"</span>#{</span>@</span>shortened_link</span>.original_url</span>}</span>", </span>status: </span>302</span>)
</span>  </span>end
</span>
</span>  </span>private def </span>set_shortened_link
</span>    @</span>shortened_link </span>= </span>ShortenedLink</span>.find! params[</span>:id</span>]
</span>  </span>end
</span>end
</span></code></pre>
This code is a bit overkill for how small the controller is, however, it demonstrates using before_action</code> hooks again for an specific actions, defining a getter</code> with a default empty model on line 3, and redirecting to a new URL on line 10.</p>
The show</code> method triggers the before_action</code> which in turn...</p>

Attempts to find a Shortened link by the ID URL parameter</li>
Sets that model to the instance variable shortened_link</code></li>
</ul>
This means the show method then has access to this variable and can use it to redirect the user.</p>
Running the application</h2>
If you haven't already tried, then run the watch</code> command and view it in your browser.</p>
amber watch
</span></code></pre>
Amber watch will both start up the Crystal web server on port 3000 and run Webpack in the background to compile Javascript and CSS. Whenever you make a change the page in the browser will be refreshed.</p>
Summary</h2>
This tutorial has covered many aspects of Amber, including basic usage of controllers, routes, and templates. It’s also given a gentle introduction to controller hooks and tables with a UUID primary key.</p>
If this article interested you, please sign up for my newsletter below where I'll announce my latest programming articles (including Crystal!).</p>
You can also checkout my previous Crystal/Amber articles</a>, including using Tailwind CSS with Amber</a>, or look into a deeper look into UUID’s with Amber</a>.</p>

Using UUIDs with Crystal Amber

2018-09-09T00:00:00+00:00

In some situations it's ideal to be able to hide the ID number in a database table. Here's how to do it using Crystal Amber and the Granite ORM.

Create your model

amber</span> g model WebLink url:string
</span></code></pre>
Edit the migration file to use either a VARCHAR</code> or UUID</code> if it supports it (Hint: Postgres does!). To use a hex string instead, stick with VARCHAR</code>.</p>
-- +micrate </span>Up
</span>CREATE TABLE</span> web_links (
</span>  id </span>UUID PRIMARY KEY</span>,
</span>  url </span>VARCHAR</span>,
</span>  created_at </span>TIMESTAMP</span>,
</span>  updated_at </span>TIMESTAMP
</span>);
</span>
</span>
</span>-- +micrate </span>Down
</span>DROP TABLE IF EXISTS</span> web_links;
</span></code></pre>
Edit the model file to include the UUID</code> library, set the Primary Key as a string and turn off auto increment. Then add the before_create</code> macro to assign a new UUID</code> on creation.</p>
require </span>"</span>uuid</span>"
</span>class </span>WebLink </span>< </span>Granite::Base
</span>  adapter pg
</span>  table_name web_links
</span>
</span>  </span># id : Int64 primary key is created for you
</span>  primary id : </span>String</span>, </span>auto: </span>false
</span>  field url : </span>String
</span>  timestamps
</span>  before_create </span>:assign_id
</span>
</span>  </span>def </span>assign_id
</span>	@</span>id </span>= </span>UUID</span>.random.</span>to_s
</span>  </span>end
</span>end
</span></code></pre>
Alternatively, use UUID.random.hexstring.to_s</code> for an alternate style (e.g. 2d10e1a2fa89425197d62f94c6cf07dc</code>). The UUID</code> database data type will convert this automatically so make sure to set the data type to VARCHAR</code>.</p>
To use shorter IDs chop the hexstring</code> down by using the range syntax [0..6]</code>, replacing 6 with the desired length, and then check for duplicates before creating the table row.</p>
def </span>assign_id
</span>  potential_id = </span>UUID</span>.random.hexstring.</span>to_s</span>[</span>0</span>..</span>6</span>]
</span>	</span>while </span>WebLink</span>.find(potential_id)
</span>	  potential_id = </span>UUID</span>.random.hexstring.</span>to_s</span>[</span>0</span>..</span>6</span>]
</span>	</span>end
</span>  @</span>id </span>= potential_id
</span>end
</span></code></pre>
That's it! Make sure to run crystal db migrate</code> before running the application.</p>

Why Amber?</h2>
Coming from someone that enjoys using Ruby on Rails and is intrigued by Crystal, I really like Amber and how familiar it already is. Not to mention it’s blazing fast!</p>
Check out the docs for more information</a></p>

- Crystal

How to deploy a Crystal Lucky application with Dokku on Ubuntu 18.04

What is Lucky?</h3>
Lucky is a web framework written in Crystal</a>. Crystal is a programming language with syntax inspired by Ruby but with speeds similar to that of C.</p>

What is Dokku?</h3>
Dokku is a small PaaS service powered by Docker that you can run on your own servers. Think of it as a self-hosted command-line Heroku</a>.</p>

Adding RSS Feeds to a Lucky app

How to set up Crystal Amber framework with Tailwind CSS

Using UUIDs with Crystal Amber

- Crystal

How to deploy a Crystal Lucky application with Dokku on Ubuntu 18.04

What is Lucky?</h3> Lucky is a web framework written in Crystal</a>. Crystal is a programming language with syntax inspired by Ruby but with speeds similar to that of C.</p>

What is Dokku?</h3> Dokku is a small PaaS service powered by Docker that you can run on your own servers. Think of it as a self-hosted command-line Heroku</a>.</p>

Prequisites</h2> Crystal 0.34.0 installed locally</li> A fresh Lucky application installed and running locally.</li> Basic knowledge of Git.</li>

Adding RSS Feeds to a Lucky app

How to set up Crystal Amber framework with Tailwind CSS

Why Amber?</h2> Coming from someone that enjoys using Ruby on Rails and is intrigued by Crystal, I really like Amber and how familiar it already is. Not to mention it’s blazing fast!</p> Check out the docs for more information</a></p>

Using UUIDs with Crystal Amber

What is Lucky?</h3>
Lucky is a web framework written in Crystal</a>. Crystal is a programming language with syntax inspired by Ruby but with speeds similar to that of C.</p>

What is Dokku?</h3>
Dokku is a small PaaS service powered by Docker that you can run on your own servers. Think of it as a self-hosted command-line Heroku</a>.</p>

Why Amber?</h2>
Coming from someone that enjoys using Ruby on Rails and is intrigued by Crystal, I really like Amber and how familiar it already is. Not to mention it’s blazing fast!</p>
Check out the docs for more information</a></p>