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


In your ~/.busybird/config.psgi

    use BusyBird;
        timeline_list_per_page => 100,
        time_zone => "UTC",
        time_locale => "en_US",
        time_zone => "+0900"



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


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.


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.

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.


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: ""

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

Default: return $status->{busybird}{status_permalink}, or build permalink to the status page of, 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

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

Default build URL to the hashtag search page of

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.


Customize Timestamps

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

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

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};
        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;
        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.



Advanced topics about configuring BusyBird.


Toshio Ito <toshioito [at]>