NAME

DDG::Block - Block to bundle plugins with triggers

VERSION

version 1018

SYNOPSIS

  package DDG::Block::MyType;

  use Moo;
  with qw( DDG::Block );

  sub request { ... }

  1;

as another type of Block (not needed, checkout DDG::Block::Words and DDG::Block::Regexp).

  my $block = DDG::Block::MyType->new( plugins => [qw(
    DDG::Goodie::A
    DDG::Goodie::B
    DDG::Goodie::C
  )] );

or

  package DDG::Block::MyType::BlockA;

  use Moo;
  extends 'DDG::Block::MyType';

  sub _build_plugins {[
    DDG::Goodie::A
    DDG::Goodie::B
    DDG::Goodie::C
  ]}

  1;

DESCRIPTION

This is the Moo::Role of the so called Block concept. Its mission is to allow a list of plugins to get used based on specific trigger types. As an extend you can see DDG::Block::Regexp and DDG::Block::Words.

A class with DDG::Block needs a request function to handle a DDG::Request. It gets as only parameter the request object and needs to return a list of results or an empty list. Dont forget that returning undef on the request function means something depending of the context the DDG::Block is used.

ATTRIBUTES

plugins

The list of the plugins used for this block, its an array with a list of strings or hashes. A string defines a class which just gets regular instantiated via new, if you define a hash the parameter given in this hash are given to the instantiation process of the class defined by the key "class" inside the hash.

allow_missing_plugins

This attribute defines if the block should die on missing plugins, or if he should just go on. If given a CODEREF, then this CODEREF will get executed with the block as first parameter, and the missing class name as second. By default this is disabled.

return_one

This attribute defines if the block should stop if there is a hit which gives a result. By default this is on.

allow_duplicate

This attribute defines if the block is only allowing one instance of every plugin be called once, even if they hit cause of several cases. By default this is off, and should stay off.

debug_trace

before_build

A coderef that is executed before the build of the plugins. It gets the block object as first and the class name to instantiate as second parameter.

after_build

A coderef that is executed before the build of the plugins. It gets the block object as first and the object of the plugin as second parameter.

plugin_objs

This private attribute contains an array with an arrayref of trigger and plugin, its the main point where all subclasses of Blocks fetches the plugin => triggers definition. Do never set this attribute yourself, or you are doomed ;). The generation of this array also instantiates the plugins, which makes it an important point for the general handling plugins who needs "after_build" and "before_build". It gets triggered on instantiation of the Block.

The function goes through all plugin class names given on the setup of the blog

only_plugin_objs

This read-only attribute contains an arrayref of all plugins in a row. This can be used to iterate over all objects more easy then using "plugin_objs". It gets generated only on usage and takes "plugin_objs" as source.

METHODS

get_triggers_of_plugin

Get called to find all the triggers given by a specific plugin. If your Block subclass requires a special handling here, then it can be overloaded and just behave like you require. It gets the object of the plugin as first parameter.

parse_trigger

Gets called for every single trigger of a plugin to parse out and sort out. By default it doesnt do anything, but as the other functions you can overload this behaviour.

empty_trigger

Gets called, if the plugin doesnt deliver any trigger, here you can wrap this to your own specific definition. Its so far only used in the DDG::Block::Words, to disallow empty triggers totally. By default it returns undef.

handle_request_matches

This function is used for calling handle_request_matches on the plugin, which is implemented there via DDG::Meta::RequestHandler.

AUTHOR

DuckDuckGo <open@duckduckgo.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2013 by DuckDuckGo, Inc. https://duckduckgo.com/.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

cpanm DDG

perl -MCPAN -e shell
install DDG