Today, we’re not talking theory or starter projects. We’re building our very own, first ever, Oats~i web app in a tutorial.

If you’re reading this for the first time, briefly check out the start of the “Build a Web with Oats~i” series to learn what Oats~i is, a bit of how it works and how to set it up in your frontend development environment.

In this tutorial, we’re going to build our very own Oats~i web app that will have two pages, one where we’ll show random cat pictures and another where we’ll search and show movies based on titles, all using publicly available APIs.

However, with so much to learn, we’ll be taking things one step at a time. So, in lesson 1, our objective is to set up our routing and fragments and showcase how to set up a default route.

Our final project for today’s lesson will look something like this.

Note:

If you want to run the final code before we get started, or want to follow along directly, find the source code here: https://github.com/Ian-Cornelius/Oats-i-Lesson-1---Fragments-Routes-and-Default-Route

Clone the repo, navigate to the project’s root folder, open the terminal, then run

npm install

Wait for the installation to complete, then run

npm run dev

Open the url given in the terminal in your browser, navigate around, then follow along.

Also, in this whole series, I’ll assume you’re familiar with html and css in general, to ensure we only stick to the bits of code that matter when creating an Oats~i web app. There are no advanced HTML or CSS knowledge needed to get started with Oats~i. Just the basics.

Also, I assume you have node and npm installed already.

Now, let’s dive in!

Setting Up

We’ll quickly set up our project using the Oats~i cli. Create a new folder where you want to run Oats~i, navigate to it, open the terminal, then run

npx oats-i-cli

Follow the prompts and wait for the installation to complete.

You’ve just set up a complete Oats~i development environment. Now let’s get to deleting and editing the files in the starter project that we don’t need.

Deleting Files

First, navigate to src -> app -> index -> assets and delete all files under that folder.

Then, navigate to src -> app -> fragments and delete the about and home folders.

Create the Cats and Movies Fragments

Oats~i renders views or pages primarily through a fragment system. A fragment is basically a view unit, comprising of components or elements necessary to show visual detail or data.

Let’s take the case of our tutorial project.

We’ll have a page where a user can click on a button and have random cat images shown to them based on randomly selected http codes, using the http-cat API. This will be the home page or “/” route.

On the other page, the user will have a search bar and button where they can input a movie title and search for it using the movies API. This is the movies page or “/movies” route.

We want the user to be able to navigate between these two pages, with the right view being shown when in the home page or “/” route and movies page or “/movies” route respectively.

These views are our fragments. Here’s a visualization to help make this concept clearer.

By this logic, our Oats~i web app for this project will have two fragments. Let’s create these two, each having its own folder where its complete code is contained.

The Cats Fragment Folder

Navigate to src -> app -> fragments then create a new folder named “http-cats”. This folder will hold the source code for the http-cats fragment in our Oats~i app, shown when the user navigates to the
“/” route.

Inside the “http-cats” folder, create new folders named views, styles, assets, and scripts.

The views folder will hold the view templates for our http-cats fragment. The styles folder will hold the css files, the assets folder will hold the asset files (images, etc), and the scripts folder will hold our javascript files.

Note: These folder structures are not a strict enforcement by Oats~i but rather a logical project structure that I find to work best for most cases.

Now, let’s write the JavaScript source file that will actually render our http-cats fragment.

Write the Http-Cats Fragment Source File

Inside the scripts folder, create a new file named http_cats_main_fragment.js. Paste the following code inside it:

//@ts-check
//import styles
import "../styles/http_cats.css";

import AppFragmentBuilder from "oats-i/fragments/builder/AppFragmentBuilder";
import AppMainFragment from "oats-i/fragments/AppMainFragment"

class HTTPCatsMainFragment extends AppMainFragment{

    async initializeView(cb){

        //@ts-expect-error cannot find module (for view)
        const uiTemplate = require("../views/http_cats_fragment.hbs")();
        this.onViewInitSuccess(uiTemplate, cb);
    }
}

const httpCatsMainFragmentBuilder = new AppFragmentBuilder(HTTPCatsMainFragment, {

    localRoutingInfos: null,
    viewID: "http-cats-main-fragment",
});
export default httpCatsMainFragmentBuilder;

Now, let’s break it down.

Importing CSS Files (Styling)

The first line imports our css file, used to style our http-cats fragment view. Webpack handles loading this file into our final HTML file using the css loader, style loader, and html webpack plugin we’d configured before.

AppMainFragment, AppFragmentBuilder (and AppChildFragment Classes - Fragment Classes)

The next lines import the AppMainFragment class and the AppFragmentBuilder class.

When building Oats~i fragments, you’ll be extending from either of two fragment classes. These are the main fragment or child fragment class.

The main fragment is the parent fragment view of your page or route. Its content is encapsulated within a div element, given the id passed in as the viewID when instantiating the AppFragmentBuilder class. This content is then placed inside the tag which you put inside the tag.

There can only be one main fragment per route or page. Any other view that will be rendered by a fragment afterwards must be from a child fragment. You can picture it this way using a HTML markup tree.

HTTP Cats
                Movies