Bitsmist Frameworks
Docs » Create a sample component

Create a sample component

Overview

Let's create a simple sample component before we go on to details to see how the component is like. We create a component that has a button under a heading and says “Hello, World!” when the button is pushed.

The full source is attached at the bottom of this page. If you are an experienced programmer, taking a look at the full source first might be helpful since it's so simple.

We create the component following these steps:

  1. Decide names.
  2. Create a component HTML file.
  3. Create a component JS file.
  4. Add settings.
  5. Add an event handler.
  6. Create a container HTML file.
  7. Deploy files to a web server.

1. Decide names

Before we start creating a component, we need to decide the names of materials needed for the component.

A BitsmistJS component usually consists of a Javascript file that defines the component's action and an HTML file that describes the appearance of the component. A component's HTML file can be one or more and can be switched, or none at all. If a component takes no actions, the component has no javascript files and has only an HTML file.

We need to decide names for:

  • tag name
  • class name
  • filename

Tag name

The BitsmistJS components are built on top of the custom elements in the standard Web Components technology. Each component requires its own tag name. We need to follow the custom tag naming rules. There must be one “-” in the tag name.

Using custom elements | MDN Web Docs

We name the tag “pad-hello” here.

Class name

A component needs a class if the component has actions (event handlers). BitsmistJS treat the name that removes the “-” from the tag name and capitalizes the first letter of each word as the default class name. In this project, it is “PadHello” since the tag name is “pad-hello”.

Internally, the BitsmistJS library automatically creates a class according to the tag name for the component that doesn't have any javascript files.

Filename

The tag name + “.js” is the default javascript file name for the component and the tag name + “.html” is the default HTML file name. Though you can use any filenames you want, we follow the defaults for simplicity.

In this project, we create one javascript file and one HTML file each name is “pad-hello.js” and “pad-hello.html”.

2. Create a component HTML file

We create a component HTML file that is displayed on a browser. There is a button under a heading.

<h1>Hello Component</h1>
<button id="btn-greet">Greet</button>

We name the file “pad-hello.html” as we decided in the previous section.

Write only contents of <pad-hello> tag. This HTML will be inserted in the <pad-hello> tag.

3. Create a component JS file

If a component has some actions, you need a Javascript file that defines a class and those actions. The class must inherit the BitsmistJS component.

Inherit a base component

In BitsmistJS, we inherit one of the base components to create our custom components. As of now, BitsmistJS core offers only one base component called “Component”. You can make your own base classes by inheriting the Component class and can use it as your base component.

Define a class

The base component we inherit is in BITSMIST.v1 global object, we inherit like this:

class PadHello extends BITSMIST.v1.Component
{
}

The file name is “pad-hello.js”.

Then we pair the tag name and the class we defined. Thus, a browser will use this class when it finds “pad-hello” tag in the HTML.

class PadHello extends BITSMIST.v1.Component
{
}
 
customElements.define("pad-hello", PadHello);

4. Add settings

Next, we add component settings in “pad-hello.js”. Override _getSettings() function, and return an object that contains the settings.

There are other ways to configure components' settings.

  • COMPONENT - Settings - Specifying settings
class PadHello extends BITSMIST.v1.Pad
{
    _getSettings()
    {
        return {
            "settings": {
                "name": "PadHello"
            },
            "events": {
                "btn-greet": {
                    "handlers": {
                        "click": "onBtnGreet_Click"
                    }
                }
            }
        };
    }
}

We set the component name in the “settings” section here.

The name of a component is the constructor name by default. However, we recommend setting the name explicitly since the name could be lost when you mangle the source file.

Also, we specified which function would run when a button is pushed in “events” section. Refer to EventOrganizer reference how to specify event handlers in detail.

5. Add an event handler

Next, we create an event handler in “pad-hello.js”. Write the action taken when the button is pushed. The function name is “onBtnGreet_Click” as described in the settings we added earlier.

class PadHello extends BITSMIST.v1.Pad
{
    ...
 
    onBtnGreet_Click(sender, e, ex)
    {
        alert("Hello, world!");
    }
}

Every event handlers have the same function signature.

  • COMPONENT - Events - Event handler syntax

6. Create a container HTML file.

Create a container HTML file that contains a component we created. The file name is “sample.html”.

<html>
    ...
<body>
<pad-hello bm-autoload="/pad-hello.js"></pad-hello>
</body>
</html>

We put a custom tag we created and specify where the component JS file is placed in bm-autoload attribute. In this project, we are assuming all files are located right under the root path.

7. Deploy files to a web server

Finally, put these three files we created, sample.html, pad-hello.js, and pad-hello.html, directly under a web server's document root.

We deploy the files directly under the root for simplicity. You can place these files anywhere you like.

  • COMPONENT - Loading

Once you deploy, access sample.html with your browser. Confirm a message pops up when you push the button.

The full source

These are the source files for this sample project.

sample.html
<html>
<head>
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/bitsmist/bitsmist-js_v1@0.9.9/dist/bitsmist-js_v1.min.js"></script>
<title>BitsmisJS Sample</title>
</head>
<body>
<pad-hello bm-autoload="/pad-hello.js"></pad-hello>
</body>
</html>
pad-hello.html
<h1>Hello Component</h1>
<button id="btn-greet">Greet</button>
pad-hello.js
class PadHello extends BITSMIST.v1.Component
{
    _getSettings()
    {
        return {
            "settings": {
                "name": "PadHello"
            },
            "events": {
                "btn-greet": {
                    "handlers": {
                        "click": "onBtnGreet_Click"
                    }
                }
            }
        };
    }
 
    onBtnGreet_Click(sender, e, ex)
    {
        alert("Hello, world!");
    }
}
 
customElements.define("pad-hello", PadHello);
Previous Next

© 2019-2023 Masaki Yasutake

Bitsmist Frameworks

Table of Contents

Table of Contents

  • Create a sample component
    • Overview
    • 1. Decide names
      • Tag name
      • Class name
      • Filename
    • 2. Create a component HTML file
    • 3. Create a component JS file
      • Inherit a base component
      • Define a class
    • 4. Add settings
    • 5. Add an event handler
    • 6. Create a container HTML file.
    • 7. Deploy files to a web server
    • The full source

GENERAL

  • Overview
  • Installation
  • Create a sample component

COMPONENT

  • Loading
  • Settings
  • Events
  • Extending with organizers

REFERENCE - COMPONENT

  • Component

REFERENCE - ORGANIZER

  • EventOrganizer
  • LoaderOrganizer
  • OrganizerOrganizer
  • SettingOrganizer
  • StateOrganizer
  • TemplateOrganizer

REFERENCE - STORE

  • Store
  • ChainableStore

REFERENCE - UTILITY

  • AjaxUtil
  • ClassUtil
  • Util