Intro
Think about CSS... and forget Cascading.
A css is just a list of queries (css selection query) that apply styles to matched DOM elements.
A deep sheets it's all the same :
A list of queries (deep-queries for the moment) that apply something (and somehow) to matched javascripts properties from a particular root object.
You define it through a classical js object, where properties are sheets entries.
trough deep.sheets or deep.nodes(...).sheets(...)
dq.up & dq.bottom
Obviously the two more important sheet's actions ar 'up' and 'bottom'.
Simple example with up...
deep.nodes({ a:{ b:true } })
.up({
_deep_sheet_:true,
"dq.up::/a":{
hello:"world"
}
})
.log()
deep.nodes({ a:{ b:true } })
.query("/a")
.up({
hello:"world"
})
.query("/!")
.log()
Obviously, you could have severals entries in a sheet :
var sheet = {
_deep_sheet_:true,
"dq.bottom::./!":{
array:["from bottom"]
},
"dq.up::./a":{
test:123,
other:true
}
};
deep.nodes({
array:["base entry"],
a:{
test:1
}
}).up(sheet).log();
dq.transform
deep.nodes({ a:true, b:12 })
.up({
_deep_sheet_:true,
"dq.transform::./b":function(node){
return node.value + 20;
}
})
.log();
The callback if fired with each selected node.
RemarqueIf you need to perfom async stuffs in transformer callback, please read below.
Compilation rules
When you apply (deep.up) a sheet on an object, the sheet is executed.
When you apply a sheet on (deep.up) an sheet, the sheets are merged.
When you apply an object on (deep.up) a sheet, the sheet is ignored.
sheets & backgrounds
deep.nodes({
a:true,
_backgrounds:[
{
b:{
hello:'world'
}
},
{
_deep_sheet_:true,
"dq.up::./b":{ c:123 }
}
]
})
.flatten()
.log();
Sheets foregrounds
You could gives sheets list directly in your objects, at any levels (as backgrounds) that will be applied after backgrounds application. The difference from backgrounds application is that those sheets will be applied 'up'
Sheets list could contains, direct sheets, or any string reference to ressource (with its protocol) e.g. "json::/my/sheet/path.json"
deep.nodes({
a:true,
_transformations:[
{
_deep_sheet_:true,
"dq.up::./!":{ c:123 }
}
]
})
.flatten()
.log();
Async API
When you want to manipulate sheets that do async stuffs, you need to use deep.sheets in place of deep.up to apply sheets on objects.
The main reason is that deep.up and deep.bottom are absolutly sync and does not wait promises returned by sheet's application.
dq.transform
Each selected value is passed as argument in provided function AND the return of this function replaces original value
var sheet = {
"dq.transform::./*":function(node){
return deep.delay(100) // async simulation
.done(function(){
return "async:"+node.value;
});
}
};
deep.sheet([1,2,3,4,5], sheet)
.log();