What does the Before compile event inside the Contact Form plugin do? I see there is an undocumented event called onBeforeMessageCompile in the Contact Form plugin source:

Craft::import('plugins.contactform.events.ContactFormMessageEvent');
$event = new ContactFormMessageEvent($this, array('postedMessage' =&gt; $postedMessage));
craft()-&gt;contactForm-&gt;onBeforeMessageCompile($event);


My questions are:


How does one use this event? What can it be used for? and
Why is an $event object being instantiated at this point in the controller?
How does one use this event? What can it be used for?


It gives plugins a chance to manipulate the posted message to however they want instead of using the plugin's default implementation.  A plugin would listen to it like they listen to any other event. Something like:

public function init()
{
    craft()-&gt;on('contactForm.onBeforeMessageCompile', function(Event $event) {
        $postedMessage = $event-&gt;params['postedMessage'];
        $event-&gt;messageFields = $postedMessage;

        // Do your thing.

        $event-&gt;message = "Your custom compiled message";
        $event-&gt;htmlMessage = "Your custom compiled HTML message";
    });
}



  Why is an $event object being instantiated at this point in the controller?


The short answer is "because that's how events work". :) Is there a particular thing that's confusing you?