Gem based Components

DEPRECATION NOTICE: This is old documentation relevant to Adhearsion 1.x and will soon be removed. See the main documentation for up-to-date info.

This page describes how to create, distribute and use Adhearsion Components via RubyGems. If you are looking for components to use in your own projects, check out http://AhnHub.com for a searchable listing.

RubyGems is a packaging system for Ruby libraries. For more information visit http://rubygems.org.

Starting with Adhearsion 1.0, the re-usable plugins known as "components" can be distributed as Gems.

##1. Create##

Start by checking out the minimalist example component at http://github.com/adhearsion/ahn_test_component. Note the very basic structure: you have a .gemspec file that defines the package and your functionality that lives in lib/my_component.rb. The initial file should be named the same as your component, though it is not required.

Follow the standard component format, using methods_for to expose methods to Adhearsion's various namespaces. There are 5 namespaces available:

  :global     # Methods defined here are available everywhere in Adhearsion
  :dialplan   # Methods exposed in dialplan.rb
  :events     # Methods exposed in events.rb
  :rpc        # Methods for use in Adhearsion's restful_rpc component
  :generators # FIXME where is this used?

##2. Share##

Making your component easy to install is as easy as pushing changes with Git. See the RubyGems documentation on publishing gems into their repositories.

If your project is hosted on Github you can get extra exposure and let the community know about your amazing new component by publishing on AhnHub.com. Instructions can be found at http://ahnhub.com/how

##3. Use##

Let's demonstrate this with an example: If you want to use the ahn_test_component gem, you would do the following:

$ sudo gem install ahn_test_component
Successfully installed ahn_test_component-0.0.1
1 gem installed
Installing ri documentation for ahn_test_component-0.0.1...
Installing RDoc documentation for ahn_test_component-0.0.1...
$ cd my_ahn_app

From here, you'll want to edit two files.

In config/startup.rb add a line similar to this:

  config.add_component "ahn_test_component"

Then create a file in config/components/ahn_test_component.yml that contains any configuration needed by the component.

That's it! You can start calling the component's methods in your own dialplan.rb. Consult the component's documentation for more information.