iz3-candy v1.0.1

Candy

GtiHub

iZ³ blockchain connection provider for browsers

Summary

Candy provides connection with iZ³ blockchain platform based on WebSocket protocol. Candy can load binary and text resources from blockchain. For example: Images, CSS, Scripts, Sounds and other data.

By connecting to the blockchain, data is downloaded from the peer-to-peer network, reducing server overloading. By the way, you can completely upload site to the blockchain and load only proxy HTTP<->iZ³ page.

Example

You can found complete example in demo.html

• Just require candy.js script in page

<script src="candy.js"></script>

• Write connection code and attempt resource to loading

var candy = new Candy(['ws://127.0.0.1:6001']).start();
candy.onready = function () {
    candy.request('candy://block/432', null, function (err, data) {
        document.getElementById('demoImage').src = data;
    });
};

Documentation

API reference HERE

Creating Candy object

var nodeList = ['ws://127.0.0.1:6001'];
var candy = new Candy(nodeList);

• nodeList - initial list of iZ³ nodes with protocol string ws:// and port 6001

Connection initialization and starting

candy.start();

• start() - return current Candy object instance

OnReady event

candy.onready = function () {
    
}

• Fires once. onready event works like document.onready. Event fires if Candy already connected to blockchain.

Loading resources

You can load external resources by using request method with block url

candy.request('candy://block/432', null, function (err, data) {
    document.getElementById('demoImage').src = data;
});

Block url requests data directly from blokchain block by id with url candy://block/resourceId

Of course I'ts possible by old style method:

candy.loadResource(resourceId, function (err, data) {
    document.getElementById('demoImage').src = data.candyData;
});

• loadResource method loading resource from blockchain by resource id. At the moment resourceId is the index of the block which contain resource data.

where data is a blockchain block data field.

Sending broadcast messages

candy.broadcastMessage(messageData, id, reciver, recepient);

• messageData - data for broadcasting
• id - message id, used only by reciver
• reciver - reciver string. Uses as destination adress
• recepient - sender "reciver" string. For backward messaging

Candy Server Application requests

Candy Server App (CSA) - is a Node.js or CGI application running on decided server. CSA use iZ³ blockchain as communication level. Request to Candy Application very similar to jQuery ajax request.

request method provide simple interface for requesting CSA. I'ts uses special candy url syntax:

candy://host-name/pathname?query=string&like_get=sring

For example we request page from FastCGI Candy Server Application (FCSA) with php-fpm backend:

candy.request('candy://php/helloworld.php?get=parameter&inquery=string&z=123321', {structured: 'data','in':'JSON'}, function (err, data) {
    if(!err) {
        $('#phpRes').html(data);
    } else {
        console.log(err);
    }
});

This example load html data from helloworld.php script hosted on server with php alias.

Second param is data object like POST data. This syntax very similar to jQuery.post method.

For example see demoApp.html

Candy Autoloader

Candy Autoloader is a simple component that's monitoring page for unloaded candy resources and automatically load it.

For example we load html data from Candy Application Server with inline image code like

<img data-candy="candy://php/static/logo.png" src="#">

Autoloader detects unloaded image with data-candy attribute and attempt to load from php named host.

Also you can use block format url for loading resources

<img data-candy="candy://block/432" src="#">

Using autoloader

    var candy = new Candy(['ws://localhost:6001']).start();
    var candyAutoloader = new CandyAutoloader(candy);

...and... that's all :)

Contributing

1. Fork it ( https://github.com/izzzio/Candy/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Maintainers

• lailune Andrey Nedobylsky - maintainer