View on GitHub

QCObjects-SDK

A software library with a set of Controllers, Views and Components that are elementary and useful to assist developers to build applications under MVC patterns using QCObjects.

logo

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.quickcorp.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.quickcorp.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.quickcorp.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.quickcorp.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.quickcorp.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.quickcorp.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.quickcorp.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.quickcorp.components.ModalEnclosureComponent

org.quickcorp.components.ModalComponent

org.quickcorp.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.quickcorp.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.quickcorp.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.quickcorp.components.GridComponent

org.quickcorp.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=""/>
<h3></h3>
<p></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.quickcorp.controllers.ModalController

org.quickcorp.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.quickcorp.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.

[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>&#x1F9D1; Full Name</b></label>
  <input slot="field-control" type="text" pattern="^[a-zA-Z]+(([',. -][a-zA-Z ])?[a-zA-Z]*)*$" title="Please write your full name" placeholder="Full Name" name="name" data-field="name" aria-labelledby="name_label" required>
  <label slot="field-control" id="email_label" for="email"><b>&#x1F4E7; Email</b></label>
  <input slot="field-control" type="email" pattern="^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$" title="Please write a right email address" placeholder="Enter Email" name="email" data-field="email" aria-labelledby="email_label" required>
  <label slot="field-control" for="comment" id="comment_label"><b>&#x1F4DD; Comment</b></label>
  <textarea slot="field-control" name="comment" title="Please write a comment" rows="10" cols="100" data-field="comment" aria-labelledby="comment_label"></textarea>
  <p slot="field-control">By submitting this form you agree to our <a href="#" style="color:dodgerblue">Terms & Privacy</a>.</p>
	<div class="clearfix">
	    <button aria-label="Cancel" onclick="location.href='/#'" role="button" tabindex="-1" type="button" class="cancelbtn"><p>Cancel</p></button>
	    <button  aria-label="Send" role="button" tabindex="-1" type="button" class="signupbtn submit"><p>Send</p></button>
	</div>
</component>

org.quickcorp.controllers.SwaggerUIController

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>

SDK Effects

QCObjects has an Effect definition to handle and produce new effects and transitions for the components. Below are some custom effect definitions that will help you to build amazing visual features to your components. To improve the performance, effects are changing CSS internally to apply the effect in a smart way. And all the effects engine is based on the requestAnimationFrame definition, read more here

org.quickcorp.tools.effects.Move

Moves a DOM object from one position to another.

Usage:
Move.apply(element, xfrom, yfrom, xto, yto)
Example:
// The next line will move all the images from (0,0) to (10,10)
Tag('img').map(img => Move.apply(img,0,0,10,10))

org.quickcorp.tools.effects.MoveXInFromRight

Moves an element from the right side in X axis to the original position of the object.

Usage:
MoveXInFromRight.apply(element)
Example:
// the next line will move every canvas on the document from right side to its original position
Tag('canvas').map(canvas => MoveXInFromRight.apply(canvas));

org.quickcorp.tools.effects.MoveXInFromLeft

Moves an element from the left side in X axis to the original position of the object.

Usage:
MoveXInFromLeft.apply(element)
Example:
// the next line will move every canvas on the document from left side to its original position
Tag('canvas').map(canvas => MoveXInFromLeft.apply(canvas));

org.quickcorp.tools.effects.MoveYInFromBottom

Moves an object of the DOM from bottom to its original position using Y axis.

Usage:
MoveYInFromBottom.apply(element)
Example:
// the next line will move the body of every component named "comp1" from bottom to its original position
Tag('component[name=comp1]').map(componentBody => MoveYInFromBottom.apply(componentBody));

org.quickcorp.tools.effects.MoveYInFromTop

Moves an object of the DOM from top to its original position using Y axis.

Usage:
MoveYInFromTop.apply(element)
Example:
// the next line will move the body of every component named "comp1" from top to its original position
Tag('component[name=comp1]').map(componentBody => MoveYInFromTop.apply(componentBody));

org.quickcorp.tools.effects.RotateX

Rotates an object in X axis.

Usage:
RotateX.apply(element, angleFrom, angleTo)

angleFrom and angleTo represent an angle value expressed in degrees, starting from 0 (zero) to 360.

Example:
// the next line will rotate in X axis the div called #id from 180 degrees to 240 degrees
Tag('div#id').map(div => RotateX.apply(div, 180, 240));

org.quickcorp.tools.effects.RotateY

Rotates an object in Y axis.

Usage:
RotateY.apply(element, angleFrom, angleTo)

angleFrom and angleTo represent an angle value expressed in degrees, starting from 0 (zero) to 360.

Example:
// the next line will rotate in Y axis the div called #id from 0 degrees to 270 degrees
Tag('div#id').map(div => RotateY.apply(div, 0, 270));

org.quickcorp.tools.effects.RotateZ

Rotates an object in Z axis.

Usage:
RotateZ.apply(element, angleFrom, angleTo)

angleFrom and angleTo represent an angle value expressed in degrees, starting from 0 (zero) to 360.

Example:
// the next line will rotate in Z axis the div called #id from 0 degrees to 60 degrees
Tag('div#id').map(div => RotateZ.apply(div, 0, 60));

org.quickcorp.tools.effects.Rotate

Rotates an object in X, Y, Z axes. All axes will rotate in paralell at the same time producing a 3d visual effect perception.

Usage:
Rotate.apply(element, angleFrom, angleTo)

angleFrom and angleTo represent an angle value expressed in degrees, starting from 0 (zero) to 360.

Example:
// the next line will rotate in X, Y and Z axes the div called #id form 0 to 270 degrees
Tag('div#id').map(div => Rotate.apply(div, 0, 270));

org.quickcorp.tools.effects.Fade

Produces a fade effect by lowering the opacity of the element.

Usage:
Fade.apply(element, alphaFrom, alphaTo)

alphaFrom and alphaTo are numbers between 0 (zero) and 1.

// the following line will fade a <b class="header"> element from 0.5 (mid visibility) to 1 (full visibility)
Tag('b.header').map(header=>Fade.apply(header, 0.5, 1))

org.quickcorp.tools.effects.Radius

Rounds the corner of an element

Usage:
Radius.apply(element, radiusFrom, radiusTo)

radiusFrom and radiusTo are numeric values.

Example:
// the next line will round the corners of every image in the document
Tag('img').map(element => Radius.apply(element, 0, 100))

org.quickcorp.tools.effects.Resize

Usage:
Resize.apply(element, scaleFrom, scaleTo)

scaleFrom and scaleTo are numeric values. A value of 1 is regular size, a value of 2 is double size, a value between 0 and 1 is a small scale.

Example:
// the next line will make a zoom-out effect on every image in the document
Tag('img').map(element => Resize.apply(element, 2,0))

// the next line will make a zoom-in effect on every image in the document
Tag('img').map(element => Resize.apply(element, 0,1))

// the next line will make a zoom-in-out effect on every image in the document
Tag('img').map(element => Resize.apply(element, 2,1))

org.quickcorp.tools.effects.WipeLeft

Makes a Wipe effect from Left side to the origin of the element.

Usage:
WipeLeft.apply(element, scaleFrom, scaleTo)

scaleFrom and scaleTo are numeric values. A value of 1 is regular size, a value of 2 is double size, a value between 0 and 1 is a small scale.

Example
Tag('img').map(element => WipeLeft.apply(element,0,1))

org.quickcorp.tools.effects.WipeRight

Makes a Wipe effect from right side to the origin of the element.

Usage:
WipeRight.apply(element, scaleFrom, scaleTo)

scaleFrom and scaleTo are numeric values. A value of 1 is regular size, a value of 2 is double size, a value between 0 and 1 is a small scale.

Example
Tag('img').map(element => WipeRight.apply(element,0,1))

org.quickcorp.tools.effects.WipeUp

Makes a Wipe effect from down to up the origin of the element.

Usage:
WipeUp.apply(element, scaleFrom, scaleTo)

scaleFrom and scaleTo are numeric values. A value of 1 is regular size, a value of 2 is double size, a value between 0 and 1 is a small scale.

Example
Tag('img').map(element => WipeUp.apply(element,0,1))

org.quickcorp.tools.effects.WipeDown

Makes a Wipe effect from up to down the origin of the element.

Usage:
WipeDown.apply(element, scaleFrom, scaleTo)

scaleFrom and scaleTo are numeric values. A value of 1 is regular size, a value of 2 is double size, a value between 0 and 1 is a small scale.

Example
Tag('img').map(element => WipeDown.apply(element,0,1))

SDK Misc Tools

org.quickcorp.tools.canvas.CanvasTool

org.quickcorp.tools.layouts.BasicLayout

SDK Views

Below are a set of pre-defined views for common use.

org.quickcorp.views.GridView

A generic GridView definition for use with grids.

SDK i18n messages

The QCObjects i18n engine allows you to define custom messages . Learn more in this article in the DevBlog called i18n Internationalisation for your Progressive Web Apps

org.quickcorp.i18n_messages.i18n_messages

Used to call the i18n engine.

Usage:
  Class('i18n_messages_<custom lang>', i18n_messages,{
		...
	})
Example
'use strict';
// file: js/packages/org.quickcorp.i18n_messages.es.js
Package('org.quickcorp.i18n_messages.es', [
  Class('i18n_messages_es', i18n_messages, {
    messages: [
       // ... your custom language dictionary is here
      {
         "en":"This is a paragraph",
         "es":"Esto es un párrafo"
      },
      {
         "en":"Welcome to my new app",
         "es":"Bienvenido a mi nueva app"
      }
    ]
  }),
  {
		// the next line generates an instance of the i18n engine and attaches it automatically in the package
    _i18n_messages_es: New(i18n_messages_es)
  }
]);

##