Components
The component properties. The following properties are available on each component.
Name
Description
ajaxSetup: Object
-
An object containing the url property which will be called by the component during initialization. The endpoint should return a JSON containing the following properties:
- viewModel (optional)
- template (optional)
- Default: undefined
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
ajaxSetup: {
url: 'my-url'
}
// other configs
}); - or, you can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.ajaxSetup = {
url: 'my-url'
};
component.load(); // load the component manually since autoLoad is set to false
alias: String
- Ideally, this property should uniquely identify the component for which it was defined for. Imagine that we have multiple components of the same type. If we try to find the component by type we will end up with all of them, and sometimes this isn't the desired result. Here alias can come in handy and help us to find the correct component. Also, we can define the same alias for two out of four components and the system will match both of them based on it.
- Default: undefined
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
alias: 'my-alias'
// other configs
}); - or, we can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.alias = 'my-alias';
component.load();
attrs: Object[] / Object
- An optional extra attribute that will be added to the component's html. The value can be a single object containing name and value properties or an array of it.
- Default: []
- Accepts: Object[] / Object
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
attrs: {
name: 'data-my-attr'
value: 'my-value'
}
// other configs
}); - or, we can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.addAttr({ name: 'data-my-attr', value: 'my-value' });
autoLoad: Boolean
- A flag indicating whether the component should autoload itself upon creation.
- Default: false
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
autoLoad: true
// other configs
});
components: Object[]
- List of components to be initialized and created as child components of this component. The value is an array of objects describing the child component. Each child component is initialized and loaded automatically by the framework. Upon creation, this array will contain reference objects. Each object will contain the child component id, type and alias if defined. Actual component instances are stored in pz.application.instances collection.
- Default: undefined
- Usage:
-
var childDef = pz.define('my-child-component', {
ownerType: 'component'
// component config
});
pz.define('my-component', {
ownerType: 'component',
components: [{ type: 'my-child-component' } // or, we can pass in the definition childDef]
// other configs
}); - or, we can add component dynamically:
-
var component = pz.getInstanceOf('my-component');
// in case when we have our definition stored globally, we can use a declarative approach:
component.addChild({
type: 'my-child-component'
// other configs
});
// otherwise, we must use the actual definition as a parameter:
component.addChild(childDef);
containerElement: String
- It represents the CSS selector which will match the container element, located within the component's html, to which to append every child component by default. If renderTo is set on the child component, it will take primate over this config.
- Default: undefined
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
containerElement: 'div.my-container' // or any other CSS selector
// other configs
}); - or, we can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.containerElement = 'div.my-container';
component.load(); - This setting will not take effect if renderTo config is set. These two are mutually exclusive, and by setting this, renderTo will be set internally by the framework.
css: String[] / String
- An optional extra CSS class that will be added to the component's html. The value can be an array of class names, or a string with class name(s) separated by space. Use this option for adding customized styles to the component or any of its children.
- Default: []
- Accepts: String[] / String
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
css: ['my-class'] // or css: 'my-class'
// other configs
}); - or, we can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.addCss(['my-class', 'my-class2']);
// or
// component.addCss('my-class my-class2');
handlers: Object[]
-
An array of objects containing one or more event handlers to be added to this component during initialization. Each object should be
a valid handler. Handler object properties are:
- on required
- fn required
- selector optional
- Default: undefined
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
handlers: [{
on: 'click'
fn: 'onClick'
// this example uses component level declared function, however, we can declare inline function for the fn property of the handler
fn: function() {
// implementation
}
selector: 'my-css-selector' // selector is optional, if not set the handler will be attached to the component html element
}],
onClick: function() {
// implementation
}
}); - or, attach event dynamically:
-
var component = pz.getInstanceOf('my-component');
component.handle({
on: 'click'
fn: 'onClick'
selector: 'my-css-selector' // selector is optional, if not set the handler will be attached to the component html element
});
id (autogen): Guid (String format)
This is auto generated property. It uniquely identifies this component.
initialized (autogen): Boolean
This is autoge nerated property. It indicates that the component has been initialized.
ownerType: String
- It represent the parent class that this component extends. If your app doesn't have a custom base component, each component you create must, at some point, derive from component type.
- Default: undefined
- Usage:
-
pz.define('my-base-component', {
ownerType: 'component',
sayHello: function(text) {
alert(text);
}
// other configs
});
pz.define('my-component', {
ownerType: 'my-base-component',
sayHello: function(text) {
this.base(arguments);
}
// other configs
});
renderAfter: String
- Specify the CSS selector to match the element that this component will be rendered after. Note that parent scope is always included. If specified, this option will make the framework ignore renderTo config.
- Default: undefined
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
renderAfter: 'my-css-selector'
// other configs
}); - or, we can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.renderAfter = 'my-css-selector';
component.load();
renderBefore: String
- Specify the CSS selector to match the element that this component will be rendered before. Note that parent scope is always included. If specified, this option will make the framework ignore renderTo config.
- Default: undefined
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
renderBefore: 'my-css-selector'
// other configs
}); - or, we can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.renderBefore = 'my-css-selector';
component.load();
renderTo: String
- Specify the CSS selector to match the element that this component will be rendered into, or root keyword if this is a child component. If root keyword is used, the component will be rendered directly into the html element of it's parent, otherwise to the element found (if this is a child component parent scope will be included) based on specified CSS selector.
- Default: undefined
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
renderTo: 'my-css-selector'
// other configs
}); - or, we can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.renderTo = 'my-css-selector';
component.load();
replace: Boolean
- A flag indicating whether the component should replace the container element upon creation. Note that container taken into account is the one specified by renderTo config only. This config doesn't have any influence on renderBefore and renderAfter configs.
- Default: false
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
replace: true
// other configs
});
require: String[]
- An array of classes or components required by this component. Each string represents the type of the required component, and for each item this component will have one property created. The name of the property will be in camel case.
- Default: undefined
- Usage:
-
pz.define('required-item', {
ownerType: 'class',
myMethod: function() {
// implementation
}
// component config
});
pz.define('my-component', {
ownerType: 'component',
require: ['required-item']
// component config
});
var component = pz.getInstanceOf('my-component');
component.requiredItem.myMethod(); - Applicable only in non module environments where you should use import/export features instead.
showLoading: Boolean
- A flag indicating whether the component should show loading mask while loading.
- Default: false
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
showLoading: true
// other configs
});
style: String[] / String
- An optional extra CSS style that will be added to the component's html. The value can be an array or string of CSS styles. Use this option for adding customized inline styles to the component.
- Default: ''
- Accepts: String[] / String
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
style: [
'color: white',
'background-color: orange'
]
// or style: 'color: white; background-color: orange'
// other configs
}); - or, we can set it dynamically:
-
var component = pz.getInstanceOf('my-component');
component.addStyle(['color: white', 'background-color: orange']);
// or
// component.addStyle('color: white; background-color: orange');
template: String
- Html string which will be rendered and presented as the component html element.
- Default: undefined
- Usage:
-
pz.define('my-component', {
template: '<div class="my-class">Component body</div>'
// other configs
}); - Note that if you have more than one element within your template, you need to wrap it all together into one container. Only one HtmlElement is allowed at the root level.
templateSelector: String
- CSS selector which, preferably uniquely, identifies the html element. Based on this config the component html will be obtained. Use this option if you want to attach the already rendered html on the page to this component.
- Default: undefined
- Usage:
-
<div class="my-css-class">Already rendered html element!</div>
pz.define('my-component', {
templateSelector: 'div.my-css-class'
// other configs
}); - Note that component using pre-rendered template can not be destroyed in the current framework version.
viewModel: Object
- An object representing the data provider for this component and its children. Note that if a child component has one defined, that one will be used instead.
- Default: undefined
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
viewModel: {
name: 'John'
surName: 'Doe'
}
// other configs
});
The following events are dispatched by the framework during creation process of each component.
Name
Description
before-destroy
Published before destroying the component.
bindings-complete
Published after viewmodel binding has completed.
destroy-complete
Published after the component has been destroyed.
init-complete
Published after the component initialization process has completed.
load-complete
Published after Ajax request responsible for loading this component has completed. Note that this event will only be triggered when a template or/and viewmodel needs to be downloaded from the server.
render-complete
Published after a component has been rendered on the page.
The component built in methods. The following methods are available on each component.
Name
Description
addAttr (value, element)
- Adds an attribute to this component or to the passed HtmlElement (if any) within this component.
-
Parameters:
- ● value: Object[] / Object
- ● el: HtmlElement (optional)
addChild (child, index)
- Adds a child component to this container.
-
Parameters:
- ● child: Object
- ● index: Number (optional)
- Returns: child instance
- Fiddle:
addCss (value, element)
- Adds a CSS class to this component or to the passed HtmlElement (if any) within this component.
-
Parameters:
- ● value: String[] / String
- ● el: HtmlElement (optional)
addStyle (value, element)
- Adds a CSS style to this component or to the passed HtmlElement (if any) within this component.
-
Parameters:
- ● value: String[] / String
- ● el: HtmlElement (optional)
applyBindings
Applies bindings the component html. Optionally, you can override this if you are using a custom binder, for example KnockoutJS, and bind the viewmodel the way custom library requires.
base (..arguments)
- This method available within every function on this component. It will call the corresponding method located on the parent component, if found.
-
Parameters:
- ● Dynamic arguments passed in the function from which this method is being called
- Usage:
-
pz.define('my-base-component', {
ownerType: 'component',
template: '<div>Hello from template</div>',
renderTo: 'body',
helloWorld: function(text) {
alert(text);
}
// other configs
});
pz.define('my-component', {
ownerType: 'my-base-component', // this property is the link, the system will look for helloWorld function on 'my-base-component' type
autoLoad: true,
helloWorld: function(text) {
this.base(text);
}
// other configs
}).create();
// usage
var myComp = pz.getInstanceOf('my-component');
myComp.helloWorld('Hello from base!');
bindViewModel
Binds viewmodel (if any) object to this component html.
childAt (index)
- Finds a child component by the specified index.
-
Parameters:
- ● index: Number
childCount
Returns number of children this component has.
childIndex (component)
- Finds the index of the passed child component.
-
Parameters:
- ● component: PlazarJS component
- Returns: found index
clearHtml
Removes all child nodes (html elements) of this component.
constructor
- A method invoked upon component/class instantiation. It represents the component constructor.
- Usage:
-
pz.define('my-component', {
ownerType: 'component',
template: '<div>Hello from template</div>',
renderTo: 'body',
constructor: function(args) { // The args object will contain the config provided when creating the component
// implementation
}
// other configs
}); - This method should never be called manually. It is called by the framework after invoking myDefinition.create({ ... }) or new myDefinition({ ... }).
create (config) static
- Creates a new component instance based on the given config.
-
Parameters:
- ● config: Object (optional)
- Returns: created instance
destroy
Destroys this component and it's children.
destroyChildren
Destroys the component children.
extend (config) static
- Extends the parent component with the given properties and creates a new definition during the process.
-
Parameters:
- ● config: Object
- Returns: created definition
- Internally, it is used by the pz.define method.
firstChild
Finds and returns the first child of this component.
handle (handler)
- Dynamically attaches given handler to this component html or to any child element of it.
-
Parameters:
- ● handler: Object
- Passed handler can contain the following properties:
-
- ● fn: String / Function
- ● on: String
- ● selector: String (optional)
- ● scope: Object (optional)
- Example usage:
-
var component = pz.getInstanceOf('my-component');
component.handle({
on: 'click',
selector: '.my-class',
fn: function() {
// implementation
}
}); - If fn property of the handler object is passed as a String, it should be the name of the function of this component.
hideLoadingMask
Hides the loading mask applied to this component.
init internal
- Initializes the component.
- This method is used internally by the framework and it should not be called manually.
lastChild
Finds and returns the last child of this component.
load
Initializes loading process of this component.
publish (name, params)
- Dispatches custom event handler attached to this component via subscribe override.
-
Parameters:
- ● name: String
- ● params: Any
- Internally, pz.events.publish method is used.
removeChild (component, destroy)
- Removes child component from this container.
-
Parameters:
- ● component: PlazarJS component
- ● destroy: Boolean
- The second parameter tells the framework whether or not to destroy child component which is being removed.
render internal
- Renders this component on the page.
- This method is used internally by the framework and it should not be called manually.
showLoadingMask
Applies the loading mask to this component.
subscribe (name, listener)
- Subscribes this component to listen for a custom event.
-
Parameters:
- ● name: String
- ● listener: Function
- Example usage:
-
var component = pz.getInstanceOf('my-component');
component.subscribe('my-trigger-name', function() {
// implementation
}); - Internally, pz.events.subscribe method is used.
traceDown (value)
- Goes down recursively per level and returns child component(s) when found.
-
Parameters:
- ● value: String
- Returns: found component(s)
- Passed parameter can be component type, id or alias.
traceUp
- Goes up per level and returns parent component when found.
- This method is supporting one level up only. In the future, it will work recursively.
unapplyBindings
Unbinds previously bound viewmodel from the component html. Optionally, you can override this if you are using a custom binder, for example KnockoutJS, and unbind the viewmodel the way custom library requires.
Introduction
Each defined component within your application must have a template defined in one way or another. Components are one of the PlazarJS core asset types and they are responsible of the user interaction with your app. If you are familiar with the model-view-controller (MVC) or model-view-viewmodel (MVVM) concepts you should be able to embrace the component logic without the struggle. PlazarJS component, together with its viewModel property, plays a role of the controller/viewmodel and the template is the view.
There are three ways of defining the component template:
- ➊ Inline template (template property)
- ➋ Pre-rendered template (templateSelector property)
- ➌ Download the template and/or the viewmodel from the server (ajaxSetup property)
No matter which approach you choose, the template syntax is the same.
Each template has a couple of reserved keys:
- ➊ $index - The keyword we can use within each loop iteration. It holds the current iteration index.
- ➋ $current - The keyword we can use within each loop iteration. It represents the current item of the loop, the scope.
- ➌ $root - The keyword we can use anywhere in our template. It represents the root object (the viewmodel itself).
- ➍ as - The keyword used to create an iteration alias. <li data-each="animals as animal">...</li>
HTML Observations
PlazarJS templates are HTML-based which means that you can use all HTML available tags when defining one. <script> tag is an exception. From inline templates, if found, this tag will be removed. Template downloaded via AJAX will also be considered as an "inline" template since it wasn't pre-rendered on the page.
HTML vocabulary can be extended with built in or custom binders/directives. Check out the binder section for more details.
Note that template must be a single HTML element, meaning you cannot define a template like this:
<div>first text</div><div>second text</div>
A valid template would be with the wrapper element:
<div>
<div>first text</div>
<div>second text</div>
</div>
Interpolation
Basic data binding would be the text binding. With interpolations it's done via the single-curly braces.
<span>{message}</span>
The text above will be replaced with the corresponding property of the viewModel object definition, meaning that our component should have the viewmodel defined like so:
{
message: 'Welcome to PlazarJS'
}
JavaScript expressions are not supported at this point. If you need some logic you should create a function within the component viewModel and use it like so:
<span>{getMessage}</span>
The corresponding viewmodel:
{
getMessage: function() {
return 'Welcome to PlazarJS';
}
}
The custom delimiters
// in your application entry point set the custom delimiters
pz.binder.delimiters = ['{{', '}}'];
// after setting it, the template interpolation should look like this
<span>{{myProperty}}</span>
Binders/Directives
Binders or directives are custom HTML attributes with the data- prefix. The main role of these attributes is to reflect the viewmodel changes to the DOM. Below we have a text binder example.
<span data-text="message"></span>
Attribute binding
<a data-attr-href="url">...</a>
Multi-word attributes, like HTML5 data attributes, are bound like so:
<span data-attr-[data-id]="myId"></span>
Two way data binding example:
<input data-value="message" />
The directives are built on top of the same rules like the interpolation, therefore they do not support direct JavaScript expressions.
The custom prefix
// in your application entry point set the custom prefix
pz.binder.prefix = 'pz';
// at this point all directives will use the given custom prefix
<input pz-value="name" />
<span pz-text="name"></span>