Background Quick Start

Requirements

The easiest way to get started with Mahalo is by starting from the mahalo-seed package. This is a pre-configured starte-kit that contains a shell for creating Mahalo applications.

Before you can start you have to be familiar with NPM the package manager of Node.js which has to be installed on your machine for Mahalo to work.

Another dependency of mahalo-seedGrunt which is responsible for running various tasks like starting the development server or building a deployable script file.

Once you have Node.js installed you can install Grunt globally with following command in a terminal 

npm install -g grunt-cli

Installing the Package

You can use one of two options to grab the files for mahalo-seed.

Option A: Using Git

This assumes that you are familiar with Git and have it running in your environment. Create a new folder on your local machine that will host your application. Inside of that folder execute the following two commands 

git init
git pull https://github.com/mahalo/mahalo-seed.git

You now have an initialized Git repository in that folder and copied the files from mahalo-seed to that folder.

Option B: Downloading

If you don't want to initialize a Git repository yet you can also download the mahalo-seed package here. Just extract all files to a folder of your liking.

Running Mahalo

After you have the mahalo-seed package somewhere on your machine you can install your applications dependencies with the following command executed in your mahalo-seed folder 

npm install

Congratulations! You can now start your Mahalo application in development mode by using the default Grunt task by typing the following command 

grunt

This command will bundle your files and start the development sever listening on port 8080 by default. Mahalo uses webpack as its module bundler and webpack-dev-server to serve your application and automatically refresh your browser when you make changes to your files.

Writing Your First Mahalo Component

If you made it this far you can finally write your first component. Components are the core concept of Mahalo. Everything is build around them. Create a new file named hello-world.html in your root folder and add the following content 

<h1>Hello World</h1>

Now open app.html which you should find in the root folder of your application. This file is still empty but used by mahalo-seed as a starting point for your application. Add the following content 

<use component="./hello-world"/>

<hello-world></hello-world>

Your new component should now be rendered in the browser. Pretty simple, wasn't it? But your component most likely wants to bind some data to the template hello-world.html. This is done by using a code behind file with the same name in the exact same folder.

Mahalo uses TypeScript for this. Or at least most parts of it with some awesome extensions that make Mahalo so powerful. Let's create hello-world.ts with the following content 

import {Component} from 'mahalo';

export default class HelloWorld extends Component {
    user = 'Marlo Brando';
}

With this file in place Mahalo will create an instance of the class that is the default export. In your template you now have access to all members of that instance.

To make use of the user property we need to update hello-world.html. Open that file and change its content to the following 

<h1>
    Hello World from ${user}
</h1>

Your Browser should have refreshed and should See a headline saying Hello World from Marlo Brando. Okay, that probably still didn't impress you much. How about injecting some data in your component? This can be achieved by using behaviors. You can define them in the HelloWorld class from hello-world.ts as follows 

import {Component} from 'mahalo';

export default class HelloWorld extends Component {
    static attributes = {
        user: ''
    };
}

The static property attributes of a component class can be defined as an object with a key for every attribute of the defining element that should be attached instances of the component. In the above example the value of the user attribute will be available as an instance member.

Whenever you define the component in another template you can now set its user property by adding a user attribute to its HTML tag. Let's do that in app.html which should now look like this 

<hello-world user="Marlo Brando"></hello-world>

Congratulations you just finished your first Mahalo application. A shitty one but none the less.