NAME

BusyBird::Manual::Config - how to configure BusyBird

SYNOPSIS

In your ~/.busybird/config.psgi

    use BusyBird;
    
    busybird->set_config(
        timeline_list_per_page => 100,
        time_zone => "UTC",
        time_locale => "en_US",
    );
    
    timeline("home")->set_config(
        time_zone => "+0900"
    );

    end;

DESCRIPTION

Config File

By default, BusyBird reads the file ~/.busybird/config.psgi for configuration. If it doesn't exist, busybird command automatically generates it.

You can use an arbitrary config file by specifying it to busybird command.

    $ busybird another_config.psgi

The configuration file is just a Perl script (actually it's PSGI application script). Its basic structure is:

    use BusyBird;

    ## Your configuration here

    end;

Leave every statement busybird command generated unless you know what you're doing.

Create/Get Timelines

To create a timeline, call timeline() function.

    timeline("timeline A");
    timeline("timeline B");

timeline() function returns a BusyBird::Timeline object. You can call its methods to manipulate the timeline.

    my $timeline = timeline("timeline A");
    $timeline->add({text => "Hello."});

Timeline names are unique. If you call timeline() the second time with the same timeline name, it just returns the existing timeline.

Global and Per-Timeline Configurations

Global config parameters are set by busybird->set_config() method.

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

A global config parameter affects all timelines and the overall behavior of the BusyBird instance.

Per-timeline config parameters are set by timeline(...)->set_config() method.

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

Per-timeline config parameters always take precedence over global ones. Any per-timeline config parameter can be set as a global config parameter.

Under the Hood

Config parameters are stored in BusyBird::Main and BusyBird::Timeline objects. The keyword busybird is a function that returns the singleton object of BusyBird::Main class. See "AS A MODULE" in BusyBird for detail.

When BusyBird needs some config parameters, it reads them by calling get_config() and get_timeline_config() methods on BusyBird::Main.

GLOBAL CONFIG PARAMETERS

Below is the complete list of the global config parameters.

Internally, those config parameters are accepted by BusyBird::Main.

`default_status_storage` => BusyBird::StatusStorage OBJECT

Default: BusyBird::StatusStorage::SQLite object at ~/.busybird/statuses.sqlite3

A StatusStorage object used for Timelines by default.

A StatusStorage is an object where timelines save their statuses. When a timeline is created by BusyBird::Main's timeline() method, the default StatusStorage is used for the timeline.

Note that the default StatusStorage object is referred to only when creating timelines via timeline() method. Existing timelines are not affected by changing the default StatusStorage object.

A StatusStorage object is an implementation of BusyBird::StatusStorage interface. For example, the following modules can be used as StatusStorage.

BusyBird::StatusStorage::SQLite - storage backed by SQLite database
BusyBird::StatusStorage::Memory - storage in the process memory

See each module's documentation for details.

`sharedir_path` => PATH

Default: sharedir in your BusyBird installation directory

File path to "share" directory.

"share" directory contains static files used by BusyBird, which include HTML templates, JavaScript files and image files.

See BusyBird::Manual::Config::Advanced for an example to use this parameter.

`timeline_list_per_page` => INT

Default: 30

Number of timelines shown in a single page of the timeline list.

`timeline_list_pager_entry_max` => INT

Default: 7

Maximum number of page entries shown in the pagination of the timeline list page.

PER-TIMELINE CONFIG PARAMETERS

Below is the complete list of the per-timeline config parameters.

Note that any of the per-timeline config parameters can be used as a global config parameter, too.

Internally, those config parameters are accepted by BusyBird::Main and BusyBird::Timeline.

`time_zone` => TIMEZONE_STR

Default: "local"

Timezone used to render status timestamps. TIMEZONE_STR accepts various timezone names such as "UTC", "America/Chicago", "+0900", "-0300". See DateTime::TimeZone and DateTime::TimeZone::Catalog for the list of valid timezone names.

You can set special value "local" to TIMEZONE_STR. This means the timezone of the local environment is used.

`time_format` => STRFTIME_FORMAT_STR

Default: "%x (%a) %X %Z"

Format used to render status timestamps. The format string conforms to the strftime(3) specification.

`time_locale` => LOCALE_STR

Default: LC_TIME environment variable or "C"

Locale used to render status timestamps.

LOCALE_STR is a valid locale string such as "en_US", "ja_JP" etc.

`post_button_url` => URL_STR

Default: "https://twitter.com/intent/tweet"

Link URL attached to the "Post" button in the navigation bar.

`status_permalink_builder` => CODEREF($status)

Default: return $status->{busybird}{status_permalink}, or build permalink to the status page of twitter.com, or return undef

Subroutine reference that is supposed to build permalink URL to the status.

The builder subroutine reference is called with the status object, as in:

    $url_str = $builder->($status)

$url_str is a string. If the result $url_str is undef or does not look like a valid URL, it is ignored.

`urls_entity_url_builder` => CODEREF($text, $entity, $status)

Default: return $entity->{url}

`media_entity_url_builder` => CODEREF($text, $entity, $status)

Default: return $entity->{url}

`user_mentions_entity_url_builder` => CODEREF($text, $entity, $status)

Default: build URL to the user page of twitter.com

`hashtags_entity_url_builder` => CODEREF($text, $entity, $status)

Default build URL to the hashtag search page of twitter.com

The above four configurations specify how Twitter Entities in a status object generate link URLs attached to the status text.

The builder subroutine reference is called in the following way

    $url_str = $builder->($text, $entity, $status)

where $text is the segment of status text the entity is attached to, $entity is the Twitter Entity object, and $status is the whole status object. $url_str is a string.

If the result $url_str is undef or does not look like a valid URL, it is ignored, i.e., the text is not linked.

`urls_entity_text_builder` => CODEREF($text, $entity, $status)

Default: return $entity->{display_url}

`media_entity_text_builder` => CODEREF($text, $entity, $status)

Default: return $entity->{display_url}

`user_mentions_entity_text_builder` => CODEREF($text, $entity, $status)

Default: return $text

`hashtags_entity_text_builder` => CODEREF($text, $entity, $status)

Default: return $text

The above four configurations specify how Twitter Entities in a status object convert status texts to be displayed.

The builder subroutine reference is called in the following way

    $text_to_be_displayed = $builder->($text, $entity, $status)

where $text is the segment of status text the entity is attached to, $entity is the Twitter Entity object, and $status is the whole status object. $text_to_be_displayed is a string.

If $text_to_be_displayed is undef, the original $text is used for display.

If a *_entity_url_builder subroutine reference returns non-URL for the $entity, the text is not linked and the corresponding *_entity_text_builder is not called.

`timeline_web_notifications` => STRING

Default: "simple"

Specifies how Web Notifications are used in timeline views.

If set to "simple", number of new statuses are notified using Web Notifications. Setting it to any other value stops Web Notifications.

`hidden` => BOOL

Default: 0 (false)

If set to true, the timeline is hidden from the timeline list. Hidden timelines are still accessible via Web API.

`attached_image_urls_builder` => CODEREF($status)

Default: return media_url fields in Twitter Entities in $status->{entities}{media} and $status->{extended_entities}{media}.

Subroutine reference that is supposed to return a list of URL strings to the images attached to the $status.

    @image_urls = $builder->($status)

If it returns a string that doesn't look like a valid URL, that string is ignored.

`attached_image_max_height` => INT

Default: 360

The maximum height of images attached to statuses (in pixels). If the original height is larger than this value, it shrinks the image and renders it.

`attached_image_show_default` => STRING

Default: "hidden"

Specifies how attached images are rendered in a timeline.

If set to "visible", the attached images are visible by default. Setting it to any other value hides the attached images.

`acked_statuses_load_count` => INT

Default: 20

The number of acked statuses loaded at once.

This affects the number of acked statuses loaded at initialization and when you click the "More..." button.

`default_level_threshold` => INT

Default: 0

The default level threshold for the timeline.

EXAMPLES

Customize Timestamps

Status timestamps are rendered using time_zone, time_format, time_locale parameters. By default BusyBird guesses the "correct" config for your system.

    busybird->set_config(
        time_zone => 'America/Los_Angeles',
        time_format => '%Y-%m-%d %A %H:%M:%S %Z',
        time_locale => 'en_US',
    );

Expand URLs for Links in Statuses

By default BusyBird renders Twitter Entities in status objects just like Twitter does, but you can customize this behavior by changing *_entity_url_builder and *_entity_text_builder parameters.

For example, Twitter truncates the displayed text for urls and media entites. If you want to see fully expanded URLs in statuses, do the following.

    my $builder_expanded_url = sub {
        my ($text, $entity) = @_;
        return $entity->{expanded_url};
    };
    
    busybird->set_config(
        urls_entity_text_builder => $builder_expanded_url,
        media_entity_text_builder => $builder_expanded_url,
    );

Storage File Location

By default, BusyBird stores statuses in the file ~/.busybird/statuses.sqlite3.

To change the storage file location, change default_status_storage global config parameter.

    use BusyBird::StatusStorage::SQLite;
    busybird->set_config(
        default_status_storage => BusyBird::StatusStorage::SQLite->new(
            path => "$ENV{HOME}/.busybird/another_statuses.sqlite3"
        )
    );

The example uses ~/.busybird/another_statuses.sqlite3 for the status storage. See BusyBird::StatusStorage::SQLite for detail.

Note that you should change default_status_storage parameter before you call timeline() function.

AUTHOR

Toshio Ito <toshioito [at] cpan.org>

To install BusyBird, copy and paste the appropriate command in to your terminal.

cpanm

cpanm BusyBird

CPAN shell

perl -MCPAN -e shell
install BusyBird

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Config File

Create/Get Timelines

Global and Per-Timeline Configurations

Under the Hood

GLOBAL CONFIG PARAMETERS

default_status_storage => BusyBird::StatusStorage OBJECT

sharedir_path => PATH

timeline_list_per_page => INT

timeline_list_pager_entry_max => INT

PER-TIMELINE CONFIG PARAMETERS

time_zone => TIMEZONE_STR

time_format => STRFTIME_FORMAT_STR

time_locale => LOCALE_STR

post_button_url => URL_STR

status_permalink_builder => CODEREF($status)

urls_entity_url_builder => CODEREF($text, $entity, $status)

media_entity_url_builder => CODEREF($text, $entity, $status)

user_mentions_entity_url_builder => CODEREF($text, $entity, $status)

hashtags_entity_url_builder => CODEREF($text, $entity, $status)

urls_entity_text_builder => CODEREF($text, $entity, $status)

media_entity_text_builder => CODEREF($text, $entity, $status)

user_mentions_entity_text_builder => CODEREF($text, $entity, $status)

hashtags_entity_text_builder => CODEREF($text, $entity, $status)

timeline_web_notifications => STRING

hidden => BOOL

attached_image_urls_builder => CODEREF($status)

attached_image_max_height => INT

attached_image_show_default => STRING

acked_statuses_load_count => INT

default_level_threshold => INT