Quoia Docs - Getting Started

Getting Started

To get started, set up a directory for your project and install Quoia with npm:

$ npm install quoia

Next, you'll need to set up a build file where you define various build parameters. In the root directory of your project, create new file quoia.build.js and set up the build process:

// Imports
const { build } = require('quoia');

// Configuration
let config = {
  outDir: './dist',
  rootPage: require('./src/home.quoia')
};

// Build with Quoia
build(config);

This is the file we'll run with node to build our project (node ./quoia.build.js).

In our file, we import the build function from Quoia, define a config object, then call build(config). The config object is what defines the main parameters of our project. In this example, two parameters are set:

outDir - The output directory where Quoia will build to.
rootPage - The component that serves as the root page of our site.

By now I'm sure you've noticed that the rootPage parameter has been set to a require statement. With Quoia, we want to have each component in our project to be a separate node-requirable file.

A component defines either a full page of HTML to act as one page on our site, or just a section of HTML that we can use inside of other components. Each component has its own scripts, styles, and template. In the example above, we are trying to reference a component found at ./src/home.quoia, so let's make one there now.

Create a src folder in the root directory of your project, and inside there create a home.quoia.js file:

// Imports
const { Component } = require('quoia');

/**
 * HomePage
 * Root page of the website
 */
let HomePage = new Component({
  template: './home.html',
  name: 'home'
});

module.exports = HomePage;

Here we are importing the Component class from Quoia, and using it define our home component. In this example, our component has the following properties defined:

template - Relative path to our template file.
name - Internal name of our component.

The template property is pretty self explanatory - that's just the HTML file this component will use. The name property represents the internal name of our component. Quoia uses this to identify the component internally, so it must be present on every component. When working with subpages, it also denotes how the component's URL will look.

To learn more about how name works with subpage URL's, check out the Components page.

Let's add a ./src/home.html template file for our home page:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="ie=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Built with Quoia</title>
  </head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

We now have a complete component! Let's build our project to make sure everything is set up right. Run the build script with node:

$ node ./quoia.build.js

After the build is complete, your project should now have a ./dist folder, and inside it you'll find index.html wihich has the contents of the template we made earlier.

Notice that the home component template was named as index.html in the root of our project. This was because we defined this component as the rootPage in our build config.

Subpages

Let's add a subpage to our website. Let's add a new folder ./src/pages to contain all subpages for our site. In there, let's add a new folder ./src/pages/about and populate it with a template and component file:

./src/pages/about/about.quoia.js

// Imports
const { Component } = require('quoia');

/**
 * AboutPage
 * About page of our website
 */
let AboutPage = new Component({
  template: './about.html',
  name: 'about'
});

module.exports = AboutPage;

./src/pages/about/about.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="ie=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Built with Quoia</title>
  </head>
  <body>
    <h1>About</h1>
  </body>
</html>

In order for Quoia to recognize this component, we need to add it as a child of our home component:

./src/home.quoia.js

// Imports
const { Component } = require('quoia');

/**
 * HomePage
 * Root page of the website
 */
let HomePage = new Component({
  template: './home.html',
  name: 'home',
  children: [
    require('./pages/about/about.quoia')
  ]
});

module.exports = HomePage;

If we build our project again, you'll see that our ./dist directory now has a folder about which contains and index.html with the about component template. Note that the folder name of the about component is the name we defined in the component.

Our website has a few pages now which is great, but let's optimize things a little. Both pages have the same exact <head> tag, so let's turn that into it's own component.

Component Importing

Let's make a new folder to hold our components ./src/components. In there, let's make a folder head-tag and add our component files:

./src/components/head-tag/head-tag.quoia.js

// Imports
const { Component } = require('quoia');

/**
 * HeadTagComponent
 * Defines the <head> tag of the document
 */
let HeadTagComponent = new Component({
  template: './head-tag.html',
  name: 'head',
  selector: 'quoia-head'
});

module.exports = HeadTagComponent;

./src/components/head-tag/head-tag.html

<head>
  <meta charset="utf-8">
  <meta http-equiv="x-ua-compatible" content="ie=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  <title>Built with Quoia</title>
</head>

In our template, we have the common <head> HTML code from each page. In our component file, we specify the template path and name as usual, but we also add the selector attribute. This is how we'll reference the component in our page templates, in this case by using <quoia-head>. Let's revise our page templates:

./src/home.html

<!DOCTYPE html>
<html lang="en">
  <quoia-head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

./src/pages/about/about.html

<!DOCTYPE html>
<html lang="en">
  <quoia-head>
  <body>
    <h1>About</h1>
  </body>
</html>

Quoia components do not have a closing tag!

Now when we build our project, the HTML of both pages will include the proper <head> tag from our head-tag component. If we change the head tag template, it will change everywhere else we use it.

What's next?

You have successfully created your first Quoia project! However, this guide only covers the basics, so feel free to continue browsing the docs to learn what else Quoia can do.

Read about build configuration >