Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kitsunetech-com/framejs

ES6 custom-element-based SPA framework
https://github.com/kitsunetech-com/framejs

custom-elements es6-javascript spa

Last synced: 2 months ago
JSON representation

ES6 custom-element-based SPA framework

Awesome Lists containing this project

README 

          
# FrameJS

## ES6 custom-element-based SPA framework



## Version: 2.0 (alpha) _Testing only - not suitable for production use_



### Overview



FrameJS is a single-page-application framework based on ES6 classes and custom elements. It's designed to allow an

application to be split into multiple modules, each of which can be loaded on demand. Custom elements are used to

isolate the code and style in each module within a shadow DOM while still allowing the module to interact with the

rest of the application as needed.



Each element is represented by two classes: a controller class and its corresponding custom element. The application

can be defined either by instantiating the controller classes directly or by using the custom elements. The

controller classes are responsible for managing the state of the application and the custom elements are responsible

for rendering the application. The controller classes are also responsible for loading the custom elements that

they need.



#### Custom Elements



If defining the application using the custom elements, the application is defined by creating a `` element

for the application, with a name attribute specified to identify the application. The configuration of the application

is specified by creating a `` element as a child of the `` element. Within this element, configuration

details can either be provided through `` elements representing named directives or by specifying the same

directives in an external JSON file and referencing this file in the src attribute of a `` element. The

`` elements can be used to override the values specified in the external configuration file.



The `` element can also contain a `` element in which the application's content frame can be defined.

This content frame will remain on-screen while the application is running, and all pages will be loaded within a

`` element within this frame. Transitions can be effected by using three `` elements, each with a

unary attribute specifying the transition phase: "previous", "main", or "next". If such elements are specified, the

`` will be used to display the currently active content, while `` and ``

will be used to display the content that is being transitioned away from and transitioned to, respectively. The attributes

will be modified as the transition progresses; when all content for the `` element has been loaded, its

attribute will be changed to "main" and the `` element will be changed to "previous". Finally, the

`` element will be removed from the DOM, and a new `` element will be created for the

next transition. FrameJS will force a reflow of the page when the attributes are changed so that any defined CSS

transitions based on these attributes will be triggered. Backward navigation swaps the roles of the "previous" and "next"

pages to invert the transition direction.



In addition to `` elements, the `` element can also contain `` elements, which are self-contained

elements that can be loaded/unloaded outside the typical navigation flow. `` elements can be used to define

dialogs, popups, or scripts that can either be loaded at startup or on demand, depending on when they are attached to

the DOM.



Content for the `` and `` elements is loaded either by referencing external HTML documents using the

src attribute or by specifying the content directly within the element. All such content is treated as a complete

HTML document, with the `` or `` element being the root element. (Note: if the content is specified

directly within the element, a `` tag is not required, and certain tags such as ``, ``, ``, and others

that can only appear once in a document, as well as any `` or `<style>` tags that are not intended to be run immediately

when the application is loaded, must be prefixed with "fjs-".) Any modules loaded in this manner may be added to either

a `<fjs-loaded-modules>` or `<fjs-cache>` element within the `<fjs-app>` element (only one of each such element is allowed

within the `<fjs-app>` element, and these will be created automatically if not specified). Modules placed in `<fjs-loaded-modules>`

will be loaded and run immediately when the application is loaded, while modules placed in `<fjs-cache>` will be loaded

immediately but will not be run until initialized by the application. Modules that are intended to be cloned and

initialized independently should be placed in `<fjs-cache>`, while modules that are primarily intended to be used to

compartmentalize application-wide code and style should be placed in `<fjs-loaded-modules>`.



#### Controller Classes



If defining the application using the controller classes, the application is defined by creating an instance of the

`FrameJSApp` class, using the desired app name as the single argument to the constructor. If a `<fjs-app>` element already

exists in the DOM with the given name, this element will be associated with the `FrameJSApp` instance. Otherwise, a new

`<fjs-app>` element will be created with the given name; this will need to be added to the DOM in order to initialize the

application. This element (of class `FrameJSAppElement`) can be accessed through the `FrameJSApp.rootElement` property.



The configuration of this application is specified in the `FrameJSApp.config` property, which is an object containing

the configuration directives as they would be defined in an external JSON file. (Such a file can be used instead by

calling the `FrameJSApp.config.fromFile()` method using the path to the file as the argument.) Modules and pages can

be defined by creating instances of the FrameJSModule and FrameJSPage classes, respectively, and added to the application

using either the `FrameJSApp.loadModule()` or `FrameJSApp.addToCache()` methods, depending on whether the module should

be loaded immediately or not. (FrameJSPage instances can only be added with the latter.) Modules and pages can also

be autoloaded en masse by referencing them in an external JSON file and specifying the path to this file as the argument

to the `FrameJSApp.autoload()` method, in a `<fjs-property name="autoload">` element in the `<fjs-config>` element, or as an

autoload property in an external JSON configuration file.



The FrameJSApp class also provides methods for loading and unloading modules and pages, as well as for navigating

between pages. `FrameJSApp.back()` and `FrameJSApp.forward()` can be used as functional equivalents for the browser's

back and forward buttons, respectively. The `FrameJSApp.navigate()` method can be used to navigate to a specific page

or module identified by name, and the `FrameJSApp.reload()` method can be used to reload the current page or module.

The `FrameJSApp.loadModule()` and `FrameJSApp.unloadModule()` methods can be used to load and unload modules that are

not part of the navigation flow. The `FrameJSApp.addToCache()` and `FrameJSApp.removeFromCache()` methods can be used to

add and remove modules or pages from the cache, respectively. (Note: removing a module or page from the cache will

not unload it if it is currently loaded. To unload a module or page, use the `FrameJSApp.unloadModule()` method, or

the equivalent `unload()` method on the `FrameJSModule` or `FrameJSPage` instance.)