Loading
Overview
The component's Javascript files and HTML files need to be loaded to a browser. Here we will show you how to specify where these files come from. Also, we will explain how to organize component paths and file names.
Loading
There are four ways to load components.
- Place tags that has bm-autoload/bm-automorph attribute in HTML.
- Import Javascript files with <script> tag.
- Add “molds”/“components” settings to a component setting file.
- Add dynamically in Javascript code.
Place tags that has bm-autoload/bm-automorph attribute in HTML
Specify file name
This is how we loaded a component in "Create a sample component". Specify a URL to the Javascript file in bm-autoload attribute.
<pad-hello bm-autoload="/pad-hello.js"></pad-hello>
BitsmistJS library loads the file from the specified URL asynchronously. Then, the component is initialized and loads an interface HTML file, and shows it on your browser.
Though the path in this example is a relative path, you can use an absolute path also. However, the library uses XMLHttpRequest to load files, servers hosting components need to add “Control-Allow-Origin” headers when you are loading from cross-domain sites.
Load default files
When a URL is not specified in bm-autoload attribute, the files are loaded using default paths and names.
<pad-hello bm-autoload></pad-hello>
In the example above, the default path is the current path and the default file name is the tag name + extention “.js”, thus “pad-hello.js”. For example, if you are browsing https://example.com/index.html, the component is loaded from https://examples.com/pad-hello.js.
The default path can be changed in settings.
Import Javascript files with <script> tag
Just like usual Javascript files, import component script files using <script> tag in HTML.
<script type='text/javascript' src='/bar-hello.js'></script>
Since the script tag loads the component, bm-autoload attribute is not necessary for this case.
<pad-hello></pad-hello>
You can use this method to bundle several components in one file using a bundler like Webpack.
You can not use this method for HTML-only components.
Add “molds”/“components” settings to a component setting file
By adding “molds”/“components” to a component's settings, those components specified in the sections will be added to their parent component as the child components.
{ "components": { "PadSetting": { "loadings": { "rootNode": "#widgets" }, "settings": { "name": "PadSetting" } } } }
They will be inserted in the place specified by “rootNode” setting under its parent node.
“molds”/“components” sections are handled by LoaderOrganizer. Refer to the link below for details.
Add dynamically using Javascript code
Components can be added dynamically by code. There are two ways to do so.
Insert a tag
Add a tag to the HTML. If you need to load the component you need to set appropriate tag attributes to the tag. After inserting the tag you need to call component's loadTags() method to start auto loading the component. Pass the root node to loadTags().
document.querySelector("#pads").insertAdjacentHTML("afterbegin", "<pad-filter bm-autoload bm-path='common'></pad-filter>"); document.querySelector("#pads").loadTags(document.querySelector("#pads"));
Use addComponent() method
Use addComponent() method each component has to add child components to a component. The component's settings can be set by passing a setting object to the method.
document.querySelector("bm-router").addComponent("PadFilter", { "loadings": { "path":"common", "rootNode":"#pads" } });
In the example above, the PadFilter component is added to the #pads node under the bm-router component.
addComponent() method is offered by LoaderOrganizer.
Morph from another component
For simple components that do not have their own event handlers, you can create a new component based on another component and use that.
If a URL to an HTML file is specified in the bm-autoload attribute, a new class inheriting from the Component class is automatically created internally and the class is associated with the tag.
<pad-hello bm-autoload="/pad-hello.html"></pad-hello>
In the above example, a PadHello class inheriting from the Component class is created and tied to the pad-hello tag. The tag is then instantiated and the HTML file is loaded from the server and displayed within the custom tag during its initialization process.
To use the default path and file name, specify the bm-automorph attribute.
<pad-hello bm-automorph></pad-hello>
By default, it inherits from the Component class, but a superclass can be specified with the bm-automorph attribute.
<pad-hello bm-automorph='MyComponent'></pad-hello>
Note that if the specified class needs to be loaded, the bm-autoload attribute is needed to load the class.
<pad-hello bm-autoload='https://example.com/mycomponent.js' bm-automorph='MyComponent'></pad-hello>
In this case, a PadHello class that inherits from MyComponent is created and the class is associated with the tag after https://example.com/mycomponent.js is loaded.
Default path
In "Create a sample component", we placed all the files right under the root path. However, in the actual environment, you might want to organize components files to specific directories. You can take advantage of using the default path and reduce the amount of typing instead of specifying each component URL in bm-autoload attribute. We will explain the default path here.
Settings that decide a default path
There are some settings that decide a default path.
- Base application URL (system.appBaseUrl/loadings.appBaseUrl)
- Component path (system.componentPath/loadings.componentPath)
- Tempalte path (system.templatePath/loadings.templatePath)
- Path (loadings.path/bm-path attribute)
Those settings can be specified in both system settings and component settings. Since the component settings have higher priority than system settings, you can overwrite system settings with component settings so that the component can use a different default path from system-wide settings.
The component will be loaded from the path concatenated above settings. Each setting defaults to “” (empty string).
e.g.
Settings | Value |
---|---|
Base application url | https://example.com |
Component path | components |
Template path | templates |
Let's assume we have those settings and “bar-header” component in an HTML file like this.
<bar-header bm-autoload bm-path="common"></bar-header>
The component will be loaded from https://example.com/components/common/bar-header.js and its template file from https://example.com/templates/common/bar-header.html.
Specifying a default path
You can specify these settings in settings or tag attributes. The settings can be divided into two types in terms of scope. One is global settings that are shared by all components and the other is component settings that are specific to each component.
For the details of the settings, refer to the link below.
Basically, a base application URL and a component/template path should be specified in global settings.
BITSMIST.v1.settings.merge({ "system": { "appBaseUrl":"https://example.com", "componentPath":"components", "templatePath":"templates", }, });
Save the above settings in a file, “settings.js” for example, and load the file with a script tag.
<script type='text/javascript' src='/settings.js'></script>
Then specify a path in each component attribute.
<bar-header bm-autoload bm-path="common"></bar-header>
If you are adding components using “molds”/“components” settings or Javascript, those settings can be specified in “loadings” sections for each component.
{ "components": { "PadSetting": { "loadings": { "appBaseUrl": "https://util.example.com/", "componentPath": "", "templatePath": "", "path": "widgets" }, "settings": { "name": "PadSetting" } } } }
Note you can specify a base application URL, and a component/template path in this “loadings” section to override system settings. In the example above, the component will be loaded from https://util.example.com/widgets/ even though system settings refer to https://example.com/components/.
Default file names
If a URL is not specified in bm-autoload attribute, then the default file name will be used for the component. The default file name is the tag name. You can change the default file name by changing a setting.
Settings that decide a default file name
A file name can be specified in bm-filename attribute or “loadings.fileName” setting. An extension will be added to it when loading, “.html” for HTML file, and “.js” for Javascript file.
Specifying a default file name
Specify a file name in each tag attribute without an extension.
<bar-header bm-autoload bm-filename="header"></bar-header>
If you are adding components using “molds”/“components” settings or Javascript, those settings can be specified in “loadings” sections for each component.
{ "components": { "BarHeader": { "loadings": { "fileName": "header" }, "settings": { "name": "BarHeader" } } } }
Overrides of some settings when URL is specified
If you specify a URL in bm-autoload attribute, then the component's settings, “loadings.appBaseUrl”, “loadings.componentPath”, “loadings.templatePath”, “loadings.path”, “loadings.fileName” settings will be overwrittten. If the URL links to a HTML file “loadgins.autoMorph” is set to true also.
As an example, If you set a URL “https://example.com/component/transactions/pad-main.js” as bm-autoload value, settings will be overwritten as below.
Setting | Value |
---|---|
loadings.appBaseUrl | ““(Empty string) |
loadings.componentPath | ”“(Empty string) |
loadings.templatePath | ”“(Empty string) |
loadings.path | https://example.com/component/transactions |
loadings.fileName | pad-main |
Thus, its template HTML will be loaded from https://example.com/component/transactions/pad-main.html.