@apicart/brackets
Advanced tools
Readme
Content
Brackets are under development and therefore they are not yet available on npm. You can use the cdn link.
CDN
<!-- Master version from Github -->
<script src="https://cdn.jsdelivr.net/gh/apicart/brackets/dist/brackets.min.js"></script>
<!-- v1.0.0-alpha1 from jsdelivr.net -->
<script src="https://cdn.jsdelivr.net/npm/@apicart/brackets@1.0.0-alpha1/dist/brackets.min.js" integrity="sha256-TxTeKLp4t4vZVi131XgcBwX9LJfTg1N9zlMxPE2XE0o=" crossorigin="anonymous"></script>
Npm & Yarn
npm install @apicart/brackets
yarn add @apicart/brackets
Let's start with a simple example. We will render a text stored in the data object into the #app element. Notice that variables have dollar sign $ before the name.
<div id="app">
{{$text}}
</div>
<script>
Brackets.render({
el: '#app',
data: {
text: "I ❤️ Brackets!"
}
});
</script>
I ❤️ Brackets!
Cache speed's up the rendering process. There are two types of cache. Functions cache and results cache.
resultCacheEnabled to true.cacheKey name.<div id="app">
{{$text}}
</div>
<script>
Brackets.render({
el: '#app',
cacheKey: 'test',
resultCacheEnabled: true,
data: {
text: "I ❤️ Brackets!"
}
});
</script>
The template you want to render can be provided in a multiple ways. In the example above, the template was loaded from the target element #app.
Another way to provide the template is setting it directly as a text in the template parameter.
<div id="app"></div>
<script>
Brackets.render({
el: '#app',
cacheKey: 'test',
data: {
text: "I ❤️ Brackets!"
},
template: '{{$text}}'
});
</script>
Template parameter can also receive an id selector #elementId. If so, the template will be loaded from the given element (you shouldn't load complicated templates from a typical html elements because it can cause unexpected errors, we recommend to use <template>...</template> or <script type="text/plain">...</script> elements as template providers).
<div id="app"></div>
<template id="template">
{{$text}}
</template>
<script>
Brackets.render({
el: '#app',
cacheKey: 'test',
data: {
text: "I ❤️ Brackets!"
},
template: '#template'
});
</script>
In case you need some condition for providing a correct template (for example for A/B testing) you can use a function that returns the right template based on given conditions. This function is called only once and can return a template string or a selector as in examples above. You should not change any parameters or data inside this function, because the code can become unclear.
<div id="app"></div>
<template id="templateA">A</template>
<template id="templateB">B</template>
<script>
Brackets.render({
el: '#app',
cacheKey: 'test',
data: {
version: 'a',
text: "I ❤️ Brackets!"
},
template: function () {
return this.version === 'a' ? '#templateA' : '#templateB';
}
});
</script>
During the whole rendering process, there are triggered two events.
Both events triggers methods with the configuration object provided as this.
<div id="app">
{{$number}}
</div>
<script>
Brackets.render({
el: '#app',
data: {
number: 1
},
beforeRender: function () {
this.data.number += 1;
},
afterRender: function () {
alert("Generated number is " + this.data.number);
}
});
</script>
Every website needs some interactivity. For example after clicking on a button. Every element that should be interactive must have the b-on="" attribute. There you can set the target event and what should happen when is triggered.
The syntax is following b-on="<event name> <callback>; <event name> <triggered callback>, ...".
The callback can have two forms. Direct functionality, where the function is connected to the data object like b-on="click number++ or an independent function b-on="click updateNumber()". If you want the callback to be a function, you can provide arguments. Those arguments are passed into the target function and are always a string so you have to convert it if you want to get for example a number from it. b-on="click showAlert(Some text)"
<div id="app">
{{$number}}<br>
<button b-on="click showAlert(Clicked 1!); click number ++">{{$firstButtonText}}</button><br>
<button b-on="click secondButtonText = 'Clicked 2!'; click showAlert()">{{$secondButtonText}}</button>
</div>
<script>
Brackets.render({
el: '#app',
data: {
number: 0,
firstButtonText: 'Click me 1!',
secondButtonText: 'Click me 2!'
},
methods: {
showAlert: function (event, parameters) {
if (parameters) {
this.firstButtonText = parameters;
}
alert('Hello World!');
}
}
});
</script>
Filters are used for interaction with values from variables.
As an example, we will create a filter called firstToUpper and it will convert the first character to a capital letter.
<div id="app">
{{$text|firstToUpper}}
</div>
<script>
Brackets
.addFilter('firstToUpper', function (text) {
return text.charAt(0).toUpperCase() + text.slice(1);
})
.render({
el: '#app',
data: {
text: 'text'
}
});
</script>
Text
Filters can receive multiple arguments. The arguments must be added after the colon and must be separated by a comma. The example below returns the default first text and attaches the text 'second' and 'third'.
<div id="app">
{{$text|appendWords: 'second', 'third'}}
</div>
<script>
Brackets
.addFilter('appendWords', function (text, firstParameter, secondParameter) {
return text + ', ' + firstParameter + ', ' + secondParameter
})
.render({
el: '#app',
data: {
text: 'First'
}
});
</script>
First, second, third
There are the following macros defined by default.
| {{if $cond}} … {{elseif $cond}} … {{else}} … {{/if}} | If condition |
| {{for condition} … {{/for}} | For loop |
| {{foreach values as key, value}} … {{/foreach}} | Foreach loop, the this object is an iterator object with iterableLength and counter parameters and isFirst, isLast, isOddd and isEvent functions. |
| {{while condition}} … {{/while}} | While loop |
| {{continue}} | Jump to the next iteration |
| {{continueIf condition}} | Conditional jump to the next iteration |
| {{break} | Loop break |
| {{breakIf condition} | Conditional loop break |
| {{var foo = value}} | Creates variable |
| {{dump variable}} | Similar to console.log() |
| {{js code}} | Allows you to write pure javascript |
| {{component name, param1: value, parameter2: value}} | Allows you to reuse components |
Macro in the context of the template engine is a piece of executable code.
First we will create a simple macro that will execute alert function. The macro name will be alert and number its parameter.
Macro is separated into two parts {{<name> <parameters>}}. #0 is a placeholder on which place the <parameters> will be placed.
In the following case, the #0 will be replaced by 1.
<div id="app">
{{alert number}}
</div>
<script>
Brackets
.addMacro('alert', 'alert(#0);')
.render({
el: '#app',
data: {
number: 1
}
});
</script>
Macro can also be a function. In another example, we will use the _template variable available during the rendering.
The _template is used to return the generated template. We will used it, because we want to return a content from our macro.
The code during the compilation is separated by Template literals or by single quotes (depends on browser support). The correct separator is stored in the Brackets.templateLiteral variable and you should use it to prevent incompatibility with older browsers.
On the end of the macro, there is a semicolon. In case you do not provide it the compilation will end with an error.
<div id="app">
{{dumpNumber number}}
</div>
<script>
var sep = Brackets.templateLiteral;
Brackets
.addMacro('dumpNumber', function () {
return '_template +=' + sep + 'Number: ' + sep + ' + number;'
})
.render({
el: '#app',
data: {
number: 1
}
});
</script>
Number: 1
It is also possible to use _templateAdd function. This function automatically applies the escaping filter.
<div id="app">
{{dumpNumber number}}
</div>
<script>
var sep = Brackets.templateLiteral;
Brackets
.addMacro('dumpNumber', function () {
return '_template += _templateAdd(' + sep + 'Number: ' + sep + ' + number);';
})
.render({
el: '#app',
data: {
number: 1
}
});
</script>
The _templateAdd function also allows you to use your already defined filters. Just add it as a second parameter.
<div id="app">
{{dumpText text|firstToUpper}}
</div>
<script>
Brackets
.addFilter('firstToUpper', function (text) {
return text.charAt(0).toUpperCase() + text.slice(1);
})
.addMacro('dumpText', function () {
return '_template += _templateAdd(text, \'firstToUpper\');';
})
.render({
el: '#app',
data: {
text: 'text!'
}
});
</script>
Brackets.render({
afterRender: <function|null>,
beforeRender: <function|null>,
addData: <function|null>,
cacheKey: <string|null>,
data: <object|null>,
el: <string|Element|NodeList|function>,
instanceId <string|null>,
methods: <object|null>,
onStatusChange: <function|null>,
resultCacheEnabled: <function|null>,
template: <string|null>
})
Components helps to create your code more reusable. You can for example create a button with some functionality and use it on multiple places with different parameters.
In the first example, there is a component that returns a text. The text is different in each .app element.
Components can receive arguments. Arguments are placed behind a comma (,) and are also separated by a comma (,).
<div class="app">{{component text}}</div>
<div class="app">{{component text, text: 'Second app'}}</div>
<div class="app">{{component text, text: 'Third app'}}</div>
<script>
Brackets
.addComponent('text', {
data: {
text: 'First app'
},
template: '{{$text}}'
})
.render({
el: '.app',
data: {
text: 'First'
}
});
</script>
Now, let's take a look on nested components. If the component is nested inside another component, then it's parent component must have some root element in which the component is placed. The root element is not necessary for a plain text.
<div class="app">{{component shareArticle, articleName: 'Article 1'}}</div>
<div class="app">{{component shareArticle, articleName: 'Article 2'}}</div>
<div class="app">{{component shareArticle, articleName: 'Article 3'}}</div>
<script>
Brackets
.addComponent('shareButton', {
data: {
number: 0
},
methods: {
updateNumber: function () {
this.number ++;
}
},
template: '<button b-on="click updateNumber()">Share ({{$number}})</button>'
})
.addComponent('shareArticle', {
template: '<div>{{$articleName}} => {{component shareButton}}</div>'
})
.render({
el: '.app'
});
</script>
Brackets.render({
afterRender: <function|null>,
beforeRender: <function|null>,
addData: <function|null>,
cacheKey: <string|null>,
data: <object|null>,
instanceId <string|null>,
methods: <object|null>,
onStatusChange: <function|null>,
resultCacheEnabled: <function|null>,
template: <string>
})
This keywords you must not use in the configuration object _create, _data, _destroy, _instanceId, _hash, _type, _parent, _setStatus, _status.
Rendering instances are interactive objects that were used during the rendering process of each template or component.
Each rendering instance have an id. Because there can be multiple instances during the rendering process, you can set instanceId parameter. This parameter will be than used as a prefix for the instance so the instance id will be <your-id>-<unique hash>. This will help you to find the instance you want to work with.
The following example shows how to work with instances.
Brackets.getRenderingInstances() // Returns an object containing all rendering instances
var myInstance = Brackets.getRenderingInstance('my-instance-1234') // Returns the selected instance
myInstance.data.number += 2 // Changing data structure in the renderingInstance will trigger the selected instance redrawal
myInstance.addData('key', 'value'); // This will add new data by key into the data object
Instances have also some statuses. You can use string or pass the constant from brackets object Brackets.renderingInstancesStatuses.<status>
The default state after creating is pending. Then, before the whole rendering process starts and before the beforeRendermethod, the instance is set to processing. After the rendering the instance is set to rendered.
You can listen to these changes by providing onStatusChange parameter, that must be a function. The rendered instance is passed as this parameter and the status parameter is passed as a function argument. The usage is as follows.
Brackets.render({
...
onStatusChange: function (status) {
console.log(this) // Will log the whole instance
console.log(status) // Logs current instance status
}
...
})
Every variable passed into the template is autoescaped! If you want to disable the autoescaping for your variable add the noescape filter.
{{$variable|noescape}}
FAQs
Small, flexible, easy to use, component-oriented javascript template engine.
The npm package @apicart/brackets receives a total of 1 weekly downloads. As such, @apicart/brackets popularity was classified as not popular.
We found that @apicart/brackets demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST's new AI Risk Management Framework aims to enhance the security and reliability of generative AI systems and address the unique challenges of malicious AI exploits.
Security News
This episode of the Risky Biz podcast discusses how the rise of small open source packages and the shift towards individual maintainers makes the ecosystem more vulnerable to supply chain attacks.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.