Total.js v5: Understanding standard routing

Welcome back to our Beginner’s Guide to Total.js! If you're just joining us, we highly recommend starting with our previous post, Installing Total.js v5: A beginner Guide, where we covered everything from setting up a Total.js V5 project to getting familiar with its basic components. Whether you're an experienced developer exploring Total.js V5 for the first time or someone completely new to web development, this series will guide you step by step.

In today’s post, we’ll dive into one of the most critical concepts in web development—routing. Specifically, we'll explore standard routing in Total.js V5. Along the way, we'll discuss different route methods and examine why routing plays such an important role in any web application. By the end of this post, you’ll have a solid understanding of routing mechanics in Total.js and be able to implement them confidently in your projects.

What is Routing and Why Is It Important?

At its core, routing is the backbone of any web application. It’s the mechanism that defines how your app responds to client requests for specific URLs. Imagine a postal system where a letter arrives at a central post office (the server) and needs to be routed to the correct address (the appropriate handler). That’s essentially what routing does—it maps incoming requests to corresponding code that processes and responds to those requests.

Without routing, every web page would be static, like a brochure that never changes, regardless of who's viewing it. Routing gives your application the ability to be interactive, serving dynamic content, data, and files. It enables your website to offer personalized experiences, fetch data from APIs, or render content based on user interaction.

In Total.js, routing is not only easy to implement, but it’s also highly flexible, supporting multiple methods and types of routing. Whether you're building a simple blog or a complex enterprise system, Total.js allows you to configure routes that map URLs to specific controller functions or action functions, ensuring your app delivers the right response to every request.

Supported Routing Types in Total.js

Before we dive into examples, let's first explore the different types of routing Total.js supports. Each type is designed for specific use cases, making the framework versatile for different project needs.

1) Standard Routing: This is the bread and butter of routing—handling standard HTTP requests with methods like GET, POST, PUT, PATCH, and DELETE. It’s used for most web applications to define what happens when a user accesses a specific page or submits a form.

2) File Routing: Optimized for serving static files like images, PDFs, and CSS, etc. When your app needs to deliver files to the client, Total.js offers efficient file routing mechanisms.

3) WebSocket Routing: For real-time, two-way communication between the client and server. Think of WebSockets as the underlying technology for chat apps, live updates, and other applications that require instantaneous data flow.

4) API Routing: Designed specifically for RESTful APIs, this allows your app to handle JSON requests and responses, making it ideal for building microservices or public APIs.

In this post, we'll focus on standard routing. Later in this series, we'll dive deeper into other routing types, including file and WebSocket routing.

Routing Methods: GET, POST, and More

In Total.js, routing is method-specific. This means you can define different behaviors for the same URL but with different HTTP methods. For example, a GET request to /submit might render a form, while a POST request to the same URL would process the form data. This separation of concerns helps keep your routes clean and logical.

Here’s a breakdown of some commonly used HTTP methods in routing:

• GET: Used to fetch data. In most cases, it’s employed to display views or retrieve information from the server without altering any server-side data.

• POST: Handles the submission of data, like form inputs. When a user submits data via a form, the server processes the request through a POST route.

• PUT and DELETE: Often used in REST APIs to update or delete existing data. They’re more specific in their usage compared to GET and POST.

Let’s see how you can define a basic route using the GET and POST methods in Total.js.

Basic Route Setup

In Total.js, routing is typically defined in the controllers folder. Here’s an example of setting up a simple GET route to render the homepage and a POST route to handle form submissions.

exports.install = function() {
    ROUTE('GET /', view_homepage);  // Handles GET requests to the root URL
    ROUTE('POST /submit', handle_submit); // Handles POST requests to /submit
};

function view_homepage($) {
    $.view('homepage');  // Renders the homepage view
}

function handle_submit($) {
    var data = $.body;  // Retrieves POSTed data
    $.plain('Data received: ' + JSON.stringify(data));  // Returns a plain text response
}

In this example:

• The ROUTE method is used to define the URL paths and the HTTP methods.
• The function view_homepage is responsible for handling GET requests to render the homepage view, while handle_submit processes form submissions via POST and returns a response.

Dynamic Routing and Query Parameters

Dynamic routing allows your application to accept variable inputs as part of the URL. This is particularly useful when you're dealing with dynamic content, such as user profiles or product pages where the URL might contain unique identifiers like user IDs or product names.

Example of Dynamic Routing with Query Parameters

Imagine we want to create a route where the URL includes a dynamic user ID:

exports.install = function() {
    ROUTE('GET /user/{id}/', view_user);
};

function view_user($) {
    $.view('user', { id: $.params.id });  // Passes the dynamic ID to the 'user' view
}

If a user visits http://localhost:8000/user/123/, the view_user function will be called with id = '123'. This allows you to render content dynamically based on the user ID.

We can enhance this further by adding query parameters to handle additional variables passed in the URL:

exports.install = function() {
    ROUTE('GET /search/', view_search);
};

function view_search($) {
    var query = $.query.q;  // Retrieves the 'q' query parameter
    $.plain('Search query: ' + query);
}

A request to http://localhost:8000/search/?q=totaljs will return the text Search query: totaljs, demonstrating how to retrieve query parameters in your routing.

Practical Example: Setting Up a Total.js Server with Standard & Dynamic Routing

Now that we’ve gone over the theory, it’s time to put it into practice. Let’s build a simple Total.js web server from scratch.

Step 1: Setting Up the Server

To begin, ensure you have a Total.js project set up. If you haven’t already done this, run the following command to install Total.js:

$ npm install total5

Next, create a server.js file and insert the following code:

require('total5');
Total.run({ port: 8000, release: false });

Start the server using the following command:

$ node server.js

Step 2: Organizing routes in the controller folder

Good practices in Total.js suggest organizing your routes in the controllers folder. This ensures your code remains clean and modular.

Create a folder called controllers in your project root, and inside it, create a file named default.js to define your routes:

exports.install = function() {
    ROUTE('GET /', view_homepage);
    ROUTE('GET /about', view_about);
    ROUTE('GET /contact', view_contact);
    ROUTE('GET /user/{id}/', view_user);  // Dynamic route
};

function view_homepage($) {
    $.view('homepage');
}

function view_about($) {
    $.view('about');
}

function view_contact($) {
    $.view('contact');
}

function view_user($) {
    $.view('user', { id: $.params.id });  // Return id value to the view file
}

Step 3: Creating the Views

Next, you need to create the HTML files for your views in the views folder. First, create a views folder at the root of your project. Then, create the following files inside this folder:

layout.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    @{body}
</body>
</html>

homepage.html

<h1>Welcome to the Homepage</h1>
<a href="/about">About Us</a> | <a href="/contact">Contact</a> | <a href="/user/1">User Profile</a>

about.html

<h1>About

 Us</h1>
<p>This is the about page.</p>

contact.html

<h1>Contact Us</h1>
<p>This is the contact page.</p>

user.html

<h1>User Profile</h1>
<p>User ID: @{model.id}</p>

Step 4: Running and Testing the Server

Finally, start your server again by running:

$ node server.js

Now, open your browser and test the following URLs:

• http://localhost:8000/ for the homepage.
• http://localhost:8000/about for the about page.
• http://localhost:8000/contact for the contact page.
• http://localhost:8000/user/1 for the dynamic user profile page.

Conclusion

Routing is a fundamental building block for any web application, and Total.js makes it incredibly easy to implement both standard and dynamic routing. Throughout this post, we’ve covered:

• The role and importance of routing in a web application.
• How to define routes with various HTTP methods (GET, POST, etc.).
• Setting up dynamic routes with query parameters.
• Building a basic Total.js web server with well-structured routes and views.

In the next blog, we’ll dive deeper into file routing, WebSocket routing, and other advanced features. Stay tuned, and thanks for reading!