NAME

WWW::Workflowy - Faked up API interface to the workflowy.com collaborative outlining webapp

SYNOPSIS

This module does not use an official Workflowy API! Consult workflowy.com's Terms of Service before deciding if it is okay to access their servers programmatically!

    use WWW::Workflowy;

    my $wf = WWW::Workflowy->new( 
        url => 'https://workflowy.com/shared/b141ebc1-4c8d-b31a-e3e8-b9c6c633ca25/',
        # or else:  guid => 'b141ebc1-4c8d-b31a-e3e8-b9c6c633ca25',
    );

    $node = $wf->dump;

    $node = $wf->find(
        sub {
            my $node = shift;
            my @parent_nodes = @{ shift() };
            return 1 if $node->{nm} eq 'The node you are looking for';
            return 1 if $node->{id} eq 'Jxn637Zp-uA5O-Anw2-A4kq-4zqKx7WuJNBN';
        },
    );

    $node_id = $wf->create( 
        parent_id => 'Jxn637Zp-uA5O-Anw2-A4kq-4zqKx7WuJNBN',
        priority  => 3,    # which position in the list of items under the parent to insert this node
        text      => "Don't forget to shave the yak",
    );


    $node = $wf->edit(
        save_id => 'Jxn637Zp-uA5O-Anw2-A4kq-4zqKx7WuJNBN',
        text      => "Think of an idea for a color for the bikeshed",
    );

    $wf->delete( node_id => $node->{id} );

    sleep $wf->polling_interval;  $wf->sync;

    $wf->fetch;

DESCRIPTION

All methods Carp::confess on error. Trap errors with Try::Tiny, eval { }, or similar to attempt to recover from them.

Each node has this structure:

  {
    'lm' => 1270,                                     # time delta last modified; usually not too interesting
    'nm' => 'Test 2.1',                               # text
    'id' => '63c98305-cd96-2016-4c4f-a20f7384ad9c'    # id
  }

It may also have a 'ch' containing an arrayref of additional nodes. To make things interesting, the root node does not have a 'ch' of nodes under it. Use the get_children() method to avoid dealing with this special case.

The value from the id field is used as the value for save_id, node_id, or parent_id in other calls.

new

Takes url resembling https://workflowy.com/shared/b141ebc1-4c8d-b31a-e3e8-b9c6c633ca25/ or a Workflowy guid such as b141ebc1-4c8d-b31a-e3e8-b9c6c633ca25.

May also be initialized from a serialized copy of a previous $wf-outline>. See t/002-concurrent-remote-ops.t for an example of that.

Returns a coderef.

dump

Produces an ASCII representation of the outline tree.

find

Recurses through the entire outline tree, calling the callback for each item. The callback is passed the node currently being examined and an arrayref of parents, top most parent first.

edit

Changes the text of a node.

create

Created a new node.

delete

Deletes a node.

move

No class method yet. The thing handles move commands sent down by the Workflowy server (when data was moved by another Workflowy client) but doesn't yet let you send that command to the server.

sync

sync fetches changes other people have made to the current Workflowy outline and attempts to merge them into the local outline.

create, edit, and delete minipulate data locally but only queue it to later be sent to the Workflowy server. Executing a sync causes pending operations to be sent.

Check the return value! sync returns false and does nothing if $wf->polling_interval seconds have not yet passed since the last request to the Workflowy server. Calling new generally results in a request to the Workflowy server. To avoid sync returning false and doing nothing, use this idiom:

    sleep $wf->polling_interval;
    $wf->sync;

$wf->last_poll_time contains a timestamp of the time that the last request was made. The value for $wf->polling_interval may change in response to a request to the server.

fetch

Fetches the latest copy of the outline from the Workflowy server, blowing away any local changes made to it that haven't yet been pushed up. This happens automatically on new.

get_children

Takes a node id. Returns an arrayref of a node's children if it has children, or false otherwise.

SEE ALSO

BUGS

Remote changes are not merged with forgiveness. For example, if you delete a node, someone else edits the node concurrently, and then you do a sync operation, WWW::Workflowy will blow up when it can't find the node to edit. Forgiveness should be optional.

Workflowy versions their protocol. This module targets 10. The protocol is not a documented API. This module will likely stop working without notice. This module does things like parse out JSON from JavaScript code using regexen.

AUTHOR

Scott Walters, <scott@slowass.net>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Scott Walters

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.9 or, at your option, any later version of Perl 5 you may have available.

cpanm WWW::Workflowy

perl -MCPAN -e shell
install WWW::Workflowy