view release on metacpan or  search on metacpan

lib/Valence.pm  view on Meta::CPAN

    $main_window->on(close => sub { exit });


=head1 DEBUGGING

If you set the C<VALENCE_DEBUG> value to C<1> or higher, you will see a prettified dump of the JSON protocol between the perl and electron process

    Sending to electron >>>>>>>>>>>>>>>>>
    {
       "args" : [
          "app"
       ],
       "cmd" : "call",
       "method" : "require",
       "save" : "1"
    }


    Sending to electron >>>>>>>>>>>>>>>>>
    {
       "args" : [
          "ready",
          null
       ],
       "args_cb" : [
          [
             1,
             1
          ]
       ],
       "cmd" : "call",
       "method" : "on",
       "obj" : "1",
       "save" : "3"
    }


    ...

                    <<<<<<<<<<<<<<<<< Message from electron
                    {
                       "args" : [
                          {}
                       ],
                       "cb" : 1,
                       "cmd" : "cb"
                    }

If you set C<VALENCE_DEBUG> to C<2> or higher, you will also see the standard error output from the electron process, which includes C<console.error()> output.


=head1 IPC

An essential feature of valence is providing bi-directional, asynchronous messaging between your application and the browser render process. It does this over the standard input/standard output interface provided by C<valence.js>. Without this suppor...

=head2 BROWSER TO PERL

In order for the browser to send a message to your perl code, it should execute something like the following javascript code:

    var ipcRenderer = require('electron').ipcRenderer;
    ipcRenderer.send('my-event', 'my message');

On the perl side, you receive these messages like so:

    my $ipcMain = $electron->attr('ipcMain');
    $ipcMain->on('my-event' => sub {
        my ($event, $message) = @_;

        print $message; ## prints 'my message'
    });

=head2 PERL TO BROWSER

Sending messages from perl to the browser should use code like this:

    my $web_contents = $main_window->attr('webContents');
    $web_contents->send('my-event' => 'my message');

And the javascript side can receive these messages like so:

    var ipcRenderer = require('electron').ipcRenderer;
    ipcRenderer.on('my-event', function(event, message) {
        console.log(message); // prints 'my message'
    });

=head2 IPC READY EVENTS

Before applications can send messages from perl to javascript, the C<ipcRenderer.on()> function must have been called to handle these messages. If you try to send a message before this, it is likely that the message will be delivered to the browser b...

For an example of how this is done, see the C<t/ipc.t> test and how the perl side subscribes to a C<ready> IPC message before attempting to send its C<ping> message, and how the C<t/static/remote.html> arranges for javascript to send the C<ready> mes...

=head1 TESTS

Currently this software has two tests, C<load.t> which verifies L<Valence> is installed and C<ipc.t> which starts electron and then proceeds to confirm bi-directional transfer of messages between javascript and perl.

=head1 BACKWARDS COMPATIBILITY

The extent to which this module is backwards-compatible depends on the underlying C<electron> project. The API was changed drastically between electron C<0.25.1> and C<1.0.1> (corresponding to L<Valence> releases C<0.100> and C<0.200>) so you will ha...

Presumably now that C<electron> has reached version C<1.0.0> it should now be more stable.

=head1 BUGS

A fairly large limitation with the proxying approach is that event handlers cannot prevent the default event from firing (ie with C<event.preventDefault()>). This is because the stub event handler in javascript simply forwards the event trigger and i...

As mentioned above, C<sub>s nested inside hashes or arrays will currently not properly get stubbed out (but this can be fixed if needed).

Attributes should ideally be accessed via a hash reference overload instead of the C<attr> special method.

C<new> methods cannot yet accept more than one parameter (due to a limitation in C<valence.js> -- how do you do this in JS?).

When a callback function is deleted on the javascript side, the perl-side doesn't know about this so its corresponding callback will remain forever. Is there a way to detect this in JS?

It currently always sends a C<save> (immediately followed by a C<destroy>) even when it doesn't need the value. This is inefficient and should be fixed using C<wantarray>.

Exceptions thrown in the JS side should be handled better (using L<Callback::Frame>).

=head1 SEE ALSO

L<The Valence perl module github repo|https://github.com/hoytech/Valence-p5>

L<Alien::Electron>

L<The electron project|https://github.com/atom/electron> - Official website

Valence was heavily inspired by the L<thrust|https://github.com/breach/thrust> project and some parts were ported over from my L<Thrust> module.

=head1 AUTHOR

Doug Hoyte, C<< <doug@hcsw.org> >>

=head1 COPYRIGHT & LICENSE

Copyright 2015-2016 Doug Hoyte.

This module is licensed under the same terms as perl itself.

The bundled C<valence/valence.js> library is Copyright (c) 2015-2016 Doug Hoye and is licensed under the 2-clause BSD license.

Electron itself is Copyright (c) 2014-2016 GitHub Inc. and is licensed under the MIT license.