README
QCObjects SDK
Copyright (c) Jean Machuca and QuickCorp info@quickcorp.cl
Please fork this project or make a link to this project into your README.md file. Read the LICENSE.txt file before you use this code.
If you like this code please DONATE !
Cross Browser Javascript Framework for MVC Patterns
QCObjects is a javascript framework designed to make easier everything about the MVC patterns implementation into the pure javascript scope.
QCObjects SDK is a set of Controllers, Views and Components that are elementary and useful to assist developers to build applications under MVC patterns using QCObjects.
If you like more code samples feel free to write your questions to info@quickcorp.cl
Installing with NPM:
> npm install qcobjects-sdk
Using the code in the straight way into HTML5:
<script type="text/javascript" src="https://qcobjects.dev/QCObjects.js"></script>
<script type="text/javascript" >
CONFIG.set('useSDK',true);
</script>
NOTE: This dependence is included by default in the QCObjects runtime execution. You only need to install it if your having issues with default paths
SDK
SDK Components
org.qcobjects.components.ShadowedComponent
ShadowedComponent Class is a custom component class designed to allow you to create a component using the Shadow DOM of browsers. Read more about Shadowed Components on [this article on Hackernoon] (https://www.hackernoon.com/shadowed-components-and-qcobjects-kd703yld).
Usage:
<component componentClass="ShadowedComponent"></component>
org.qcobjects.components.FormField
FormField is a Class for QCObjects custom components that allows you to inject a Form Field generic behavior to your components. It has a reverse data-binding feature to detect the values of the DOM fields inside your form and assign them to the data values of your component. By this way, you don't loose performance making an old-fashioned two-way data binding based on observables. To implement this advanced behavior. You only need to do the following:
1.- Assign a data-field attribute to the DOM tag inside the component body, with the corresponding field name in your data object.
2.- To your component tag, assign FormField in the componentClass attribute.
3.- To recover the data of the form inside your component, just use the componentInstance.data object. Every property of the componentInstance.data object will be linked by the binding events with the value properties on every DOM object of the form that has a data-field assigned.
Usage:
<!-- Where you place the component -->
<component name="myform" componentClass="FormField"></component>
<!-- template: myform.tpl.html -->
<label for="email"><b>Email</b></label>
<input data-field="email" type="email" placeholder="Enter Email" name="email" required>
<label for="psw"><b>Password</b></label>
<input data-field="name" type="text" placeholder="Enter Your Name" name="name" required>
data-field="name" will be matched with this.data.name inside the component class and will be updated everytime a data binding event is triggered. The same will happen to data-field="email" and so on.
FormField.executeBindings():
The method executeBindings of FormField component will find the data-field attribute values and match them with the corresponding data fields in the component instance.
Data Binding Event Change:
Inside of the body of your component, when it is a FormField component, every time the DOM dispatches a "change" event, it will trigger the executeBindings method of your component.
Data Binding Event Blur:
Inside of the body of your component, when it is a FormField component, every time the DOM dispatches a "Blur" event, it will trigger the executeBindings method of your component.
Data Binding Event Focus:
Inside of the body of your component, when it is a FormField component, every time the DOM dispatches a "Focus" event, it will trigger the executeBindings method of your component.
Data Binding Event Keydown:
Inside of the body of your component, when it is a FormField component, every time the DOM dispatches a "Keydown" event, it will trigger the executeBindings method of your component.
org.qcobjects.components.ButtonField
ButtonField is a sub-definition of FormField, that is commonly used for almost the same purpose of FormField. The main difference between ButtonField and FormField is that ButtonField has a <button>
DOM element as the body of the component by default. And FormField hasn't a pre-defined body.
Usage:
<component name="name_of_component" componentClass="ButtonField"></component>
org.qcobjects.components.InputField
InputField is a sub-definition of FormField, that is commonly used for almost the same purpose of FormField. The main difference between InputField and FormField is that InputField has a DOM element as the body of the component by default. And FormField hasn't a pre-defined body.
Usage:
<component name="name_of_component" componentClass="InputField"></component>
org.qcobjects.components.TextField
ButtonField is a sub-definition of FormField, that is commonly used for almost the same purpose of FormField. The main difference between InputField and FormField is that ButtonField has a <textarea>
DOM element as the body of the component by default. And FormField hasn't a pre-defined body.
Usage:
<component name="name_of_component" componentClass="TextField"></component>
org.qcobjects.components.EmailField
EmailField is a sub-definition of FormField, that is commonly used for almost the same purpose of FormField. The main difference between ButtonField and FormField is that ButtonField has a <input>
DOM element as the body of the component by default. And FormField hasn't a pre-defined body.
Usage:
<component name="name_of_component" componentClass="EmailField"></component>
org.qcobjects.components.GridComponent
GridComponent has a predefined name assigned to the value "grid", so be aware of it when you use this component class. Also, GridComponent is intended to be used in conjunction with GridController to expand its behavior to a CSS Grid.
Usage:
<component componentClass="GridComponent" ...></component>
Example:
<component rows="2" cols="2" componentClass="GridComponent" controllerClass="GridController">
<!-- It is recommended to use subcomponents as the Grid elements-->
<component name="name_of_subcomponent1"></component>
<component name="name_of_subcomponent2"></component>
<component name="name_of_subcomponent3"></component>
<component name="name_of_subcomponent4"></component>
</controller>
The above example will draw a css grid of two columns and two rows and place the subcomponents into it.
Don't forget this file:
<!-- file: grid.tpl.html, you can use the grid template either to draw the grid itself or to draw a loading information -->
<p>Loading grid...</p>
org.qcobjects.components.ModalEnclosureComponent
org.qcobjects.components.ModalComponent
org.qcobjects.components.SwaggerUIComponent
It is used to inject a swagger-ui DOM needed to the Swagger UI API. Learn more in this article of QCObjects DevBlog called Working with Swagger UI as a QCObjects Component
Usage:
<component componentClass="SwaggerUIComponent" controllerClass="SwaggerUIController" ></component>
org.qcobjects.components.splashscreen.VideoSplashScreenComponent
A powerful component definition to allow you create an awesome Video Splash Screen for your progressive web app.
Example:
<!-- Add the splash screen component tag as the first component in your HTML document -->
<component componentClass="VideoSplashScreenComponent"
data-background="./img/splash/splashscreen-aqua.png"
data-video_mp4="./img/splash/splashscreen-aqua.mp4"
data-video_webm="./img/splash/splashscreen-aqua.webm"
data-video_ogg="./img/splash/splashscreen-aqua.ogv" duration="5000">
<img slot="logo" alt="logo" src="./img/logo-qcobjects-white.svg"></div>
</component>
<!-- Then you can put your main component as always -->
<component name="main" cached=true controllerClass="MainController">
</component>
SDK Controllers
org.qcobjects.controllers.GridController
GridController is intended to be used in conjunction with GridComponent to allow you to create a CSS grid to place subcomponents. More info in org.qcobjects.components.GridComponent
org.qcobjects.controllers.DataGridController
DataGridController will take the data of your component and map a set of subcomponents to fill it up. This is commonly used to render a dynamic list of components. It used a subcomponentClass attribute value in the component tag to determine what component definition to use to build and render every sub-component. The data on every sub-component will be filled up with the value of the element mapped to the sub-component.
Usage:
<component name="name_of_component" controllerClass="DataGridController" subcomponentClass="SubComponentClass">
</component>
Example:
Suppose you have to render a list of profiles. Every profile has a profile picture, a name and an email. You want to use a card to represent every profile in the list.
So you define a CardComponent to render the picture, the name and email of an element in the list.
Class("CardComponent",Component,{
name:"card", // this will point to templates/components/card.tpl.html
data:{ // the value of this object will be overriden by DataGridController
name:"<name of contact>",
email:"email@example.com",
profilePicture:"img/photo.png"
}
})
<!-- template: card.tpl.html -->
<img src="{{profilePicture}}"/>
<h3>{{name}}</h3>
<p>{{email}}</p>
Then, you have to place a component to generate the list of cards.
<component name="loading_list" componentClass="MyListComponent" controllerClass="DataGridController"
subcomponentClass="CardComponent">
</component>
<!-- template: loading_list.tpl.html -->
<p>Loading list...</p>
Last, you have to define MyListComponent to assign the dynamic data of the list.
Class("MyListComponent",Component,{
data:[
{ // the value of this object will be mapped to a subcomponent by DataGridController
name:"<name of contact>",
email:"email@example.com",
profilePicture:"img/photo.png"
},
{ // the value of this object will be mapped to a subcomponent by DataGridController
name:"<name of contact>",
email:"email@example.com",
profilePicture:"img/photo.png"
},
{ // the value of this object will be mapped to a subcomponent by DataGridController
name:"<name of contact>",
email:"email@example.com",
profilePicture:"img/photo.png"
}
]
})
The resulting component will be a list of CardComponent with the data of every profile mapped into them by DataGridController.
org.qcobjects.controllers.ModalController
org.qcobjects.controllers.FormValidations
FormValidations is used to handle default validations for the FormController
Usage:
FormValidations.getDefault(validationName)
Where validationName is the name of the validation present in the validations property of the FormController
org.qcobjects.controllers.FormController
The FormController definition is intended to help you to handle dynamic forms. By using the normalised syntax of the FormController definition, you don't have to code the complexity of the logic of a submit form, as it is atomised here in three steps.
- Assign a serviceClass
- Define the formSettings
- Asign or code the field validations
[FormController].serviceClass
It is the string name of the Class definition. FormController will load this class using the ClassFactory helper function, so the name can be a complete package name plus definition.
[FormController].formSettings
It is an object with the special properties of the form. The default settings are: backRouting:'#', loadingRouting:'#loading', nextRouting:'#signupsuccessful'. These settings are meant to handle the flow behavior of the form.
loadingRouting is the name of the routing that will be triggered while the serviceClass is beign called until the service loader returns a response.
backRouting is the name of the routing that will be triggered if the call for the serviceClass fails.
nextRouting is the name of the routing that will be triggered when the call for the serviceClass finishes OK.
[FormController].validations
It is an object with the helper functions that you want to define to validate every form field. When you define a validation function for a field, FormController will ask if the execution of that function returns true before to submit the form.
To define validations for the fields of the form, you just need to add them as a part of the validations property.
Usage:
// Let's say you have a form field called "name"
validations: {
name (){
return (fieldName, dataValue, element)=> {
return [true ... or false condition];
}
}, //... add a validation for every form field that you want to be validated
}
You can also use FormValidations.getDefault for simplicity.
// Let's say you have a form field called "name"
validations: {
name (){
return FormValidations.getDefault('name')
}, //... add a validation for every form field that you want to be validated
}
[FormController].formSaveTouchHandler
This method is internally used by FormController to call the serviceClass as a submit action. It will be binded to any click or touch event of any element inside the form that has a CSS ".submit" class assigned.
Example:
<button class="submit"><p>Send</p></button>
When the click or touch event of the above button is triggered, FormController will call the service defined in serviceClass, this action will be done by formSaveTouchHandler. If you like to change this behavior just override this method in your custom controller.
A complete example of FormController
Below is a complete example of a definition for a Signup Form using FormController.
// First, define a service class that will be called on submit.
Class('SignupClientService',JSONService,{
name:'signup',
external:true,
cached:false,
method:'POST',
url:Service.basePath+'createaccount',
withCredentials:false,
_new_:()=>{
// service instantiated
},
done:(successfulResponse)=>{
// service loaded
_super_('JSONService','done').call(successfulResponse.service,successfulResponse);
console.log(successfulResponse.service.JSONresponse);
}
})
// To safe extend FormController, we extend first from Controller, then
// we use a defaultController to instance a new FormController
Class('SignupFormController',Controller,{
serviceClass: 'SignupClientService',
formSettings:{ /* routings that will be triggered once the serviceClass is called*/
backRouting:'#',
loadingRouting:'#loading',
nextRouting:'#signupsuccessful'
},
validations: { /* validation definitions for every field in the form to be validated before submit */
name (){
return FormValidations.getDefault('name')
},
email (){
return FormValidations.getDefault('email')
},
comment (){
return function (fieldName, dataValue, element){
return (dataValue !== '')?(true):(false);
}
}
},
defaulController:null,
_new_:function (o){
o.serviceClass = this.serviceClass;
o.formSettings = this.formSettings;
o.validations = this.validations;
// here we instance a defaultController with a New FormController
// passing the o object declaration coming from the components stack building process.
this.defaulController = New(FormController,o);
},
done: function (){
// we define a custom done callback function to inject a custom behavior as well as calling the defaultController behavior
logger.debugEnabled=true;
var controller = this.defaulController;
try {
controller.done.call(controller);
}catch (e){
logger.debug('Unable to execute default behavior');
}
}
})
<!-- A Shadowed Component to render the signup forms -->
<!-- template: signup-form.tpl.html -->
<form action="#" style="border:1px solid #ccc;border-radius:20px">
<div class="container">
<slot name="title">
<h1>Signup Form</h1>
</slot>
<slot name="subtitle">
<p>Please fill up this form to ask for a quote.</p>
</slot>
<hr />
<slot id="field_control" name="field-control">
</slot>
<hr />
<slot name="submit_button"></slot>
</div>
</form>
<!-- A signup form using the shadowed component signup-form -->
<!-- template: signup.tpl.html -->
<component name="signup-form" shadowed="true" controllerClass="SignupFormController">
<h1 slot="title">Signup Form</h1>
<p slot="subtitle">Please fill up this form to ask for a quote.</p>
<label slot="field-control" id="name_label" for="name"><b>🧑 Full Name</b></label>
<input slot="field-control" type="text" pattern="^[a-zA-Z]+(([',. -][a-zA-Z ])?[a-zA-Z]*)*