view release on metacpan or  search on metacpan

lib/BusyBird/Manual/Tutorial.pod  view on Meta::CPAN

Change the B<< level threshold >> by the buttons at the top-right corner.
If you set to the threshold to "Lv. 1", it shows the "mention" statuses only, and hides everything else.
That way, you can quickly review the mentions and reply to them.

You can use arbitrary integer values for the status level (C<busybird.level> field), including negative values.

=head1 Configuration

So far, we use L<BusyBird> with its default configuration,
but you can customize its behavior by writing a configuration file.

L<BusyBird> configuration file is B<~/.busybird/config.psgi>.
By default, it looks like:

    use BusyBird;
    timeline("home");
    end;

config.psgi is a Perl script, so you can write arbitrary Perl codes into it.
However, here is the basic rule:
B<< you must write your config between "use BusyBird;" and "end;" statements. >>
Follow this rule unless you know what you are doing.

=head2 Configure More Than One Timelines

You can have more than one timelines in a single L<BusyBird> instance.

To create a timeline, just add a line

    timeline("foobar");

which creates a timeline named "foobar".

To input statuses to the "foobar" timeline, try

    $ perl import2.pl | curl -d @- http://127.0.0.1:5000/timelines/foobar/statuses.json

Timeline's names must be unique. So if you repeat calling C<timeline()> function with the same name,

   timeline("foobar");
   timeline("foobar");

it creates only one timeline named "foobar".


=head2 Configuration Parameters

You can set various config parameters by C<set_config()> method.

To set a B<< global config parameter, >> use C<< busybird->set_config(...) >>.

    busybird->set_config(time_zone => "UTC");

A global config parameter affects all timelines and the overall behavior of the L<BusyBird> instance.
In the above example, status timestamps in all timelines are rendered in UTC time zone.

C<set_config()> method accepts more than one key-value pairs.

    busybird->set_config(
        time_zone   => "+0900",
        time_locale => "ja_JP"
    );

Some parameters are B<< per-timeline config parameters, >>
which can be set to individual timelines.

To set a per-timeline parameter, use C<< timeline(...)->set_config(...) >>.

    busybird->set_config(time_zone => "UTC");
    
    timeline("foobar")->set_config(time_zone => "+0900");

Per-timeline config parameters always take precedence over global ones.
So, in the above example, statuses are renderred in "+0900" time zone only in the timeline "foobar".
In other timelines, the time zone is "UTC".

See L<BusyBird::Manual::Config> for the complete list of config parameters.

=head1 Filters

You can set B<< status filters >> to timelines.

A status filter is a function that is executed when you input statuses into a timeline.
You can modify the input statuses with the filter before they are stored into the timeline.

    [ Statuses ] --HTTP POST--> [ Filter 1 ] --> [ Filter 2 ] --> ... --> [ Timeline ]

By default, timelines have no filters. Statuses are directly input to them.

To add a status filter to a timeline, use C<add_filter()> method.

    timeline("home")->add_filter(sub {
        my ($statuses) = @_;
        foreach my $status (@$statuses) {
            if($status->{text} =~ /\@my_name/) {
                $status->{busybird}{level}++;
            }
        }
        return $statuses;
    });

A status filter is just a subroutine reference in Perl.
It is called like

    $result_arrayref = $filter->($arrayref_of_statuses)

where C<$arrayref_of_statuses> is an array-ref of input statuses.

In the above example, the filter inspects each status's C<text> field.
If it finds your screen name ("@my_name"), it increments the status's level, meaning that it's important.
Then the filter returns the array of modified statuses.

A timeline can have more than one filters.
Those filters are executed in the order they are added, and the output of one filter becomes the input of the next filter.

    timeline("home")->add_filter(sub {
        my ($statuses) = @_;
        foreach my $status (@$statuses) {
            if($status->{text} =~ /\@my_name/) {
                $status->{busybird}{level}++;
            }