Intro

Warning deep sheets is the conjonction of layers, queries and protocols tools. So please read and understand those sections before reading this.

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.

  • 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()
    
    Which is equivalent to :
    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();