Event Organiser Pro 1.7 Released

1.7 marks a massive improvement to the plug-in’s handling of booking forms (though there should be no major alterations to the mark-up produced).

Event Organiser Pro now provides a robust API for modifying forms and form elements. This is all with the view of putting in place a strong foundation for some more advanced features that will hopefully be soon gracing Event Organiser (conditional logic, fields which duplicate according the number of tickets etc.)

There were also improvements to the booking form customiser. Additionally you can allow bookees the freedom to cancel their bookings (via the [booking_history] shortcode).

Form customiser UI changes

The booking form customiser has been completely rewritten to use Backbone (it maintains backwards compatibility with older versions of WordPress that don’t have Backbone included). The result of this is a much slicker interface (which has also had some cosmetic improvements).

The new an improved booking form customiser

Additionally the way fieldsets are now used has changed. To group field elements together inside a fieldset, simply drag them so they sit under the fieldset:

fieldset-refactor

Booking form API

Event Organiser’s handing of booking forms has been drastically improved, introducing a robust API to allow you to manipulate booking forms programatically. It also gives you the freedom to perform tasks you wouldn’t normally be able to do. Full documentation is to follow, but I’ve included a few snippets of common requests which are now possible:

Pre-populating a field if the user is logged-in:

function my_pre_populate_field( $form, $event_id ){

     if( $user_id = get_current_user_id() ){

          //These assumes you have a 'twitter' field for users...
          $user_value = get_user_meta( $user_id, 'twitter', true );

          //Retrieve the field element
          $element = $form->get_element( 170 );
          if( $element ){
               $element->set_value( $user_value );
          }
      }
}
add_action( 'eventorganiser_get_event_booking_form', 'my_pre_populate_field', 10, 2 );

‘Password’ protecting a form if the user is logged-in:

Ignoring details related to hashing and secure passwords, the following shows you how to programatically add an element to booking form, and then check its value against a ‘valid’ value. (In this example that valid value is expected to be stored as a custom field of the event, named ‘booking_password’).

When adding an element, the ID must be unique. To avoid potential collisions with IDs used by the core of the plug-in, it’s recommended that you prefix every ID with an underscore: _.

function my_add_field( $form, $event_id ){    

     //Check a password is given
     if( get_post_meta( $event_id, 'booking_password', true ) ){

          $element = new EO_Booking_Form_Element( array(
                'id'       => '_password', //a unique ID
                'type'     => 'password',  //the field type
                'required' => 1,           //make this field required
                'label'    => 'Please enter the password'
          ) );

          //Add the field element, optionally specify where
          $form->add_element( $element, array( 'at' => 1 ) );
      }
}
add_action( 'eventorganiser_get_event_booking_form', 'my_add_field', 10, 2 );

Next we hook on to the form validation filter, to check if our password is valid. Below we add an error message to both the form (which appears at the top) and the element (which appears next to the field element). Only one is necessary to prevent the booking from processing.

function my_validate_password( $form ){

     $password = $form->get_element( '_password' ); //get entered value using the ID we set
     $event_id = $form->get( 'event_id' );
     $expected_value = get_post_meta( $event_id, 'booking_password', true )

     if( $password && $password->get_value() != expected_value ){
          //Adds error to the form
          $form->add_error( 'invalid_password', 'Password is invalid' );

          //Adds error to the field
          $password->add_error( 'invalid_password', "Try again!" );

          //Only one is necessary!
     }

}
add_filter( 'eventorganiser_validate_booking_form_submission', 'my_validate_password', 10 );

Added options for the form customiser

The “Simple Booking Mode” has been moved from the form’s “Settings” tab to the Ticket Picker element (as it concerns only the ticket selection). Most elements also have a CSS class option for adding classes to the elements.

Booking history option: cancelling bookings

The booking history shortcode now supports the “bookee_can_cancel” attribute. By using the shortcode as follows:

 [booking_history bookee_can_cancel="1"]

an additional column appears on the booking form table, allowing users to cancel their booking. Only bookings for events which have not yet started may be cancelled by the bookee.

Event search form template function

The function eo_get_event_search_form( $args ) has been added. This function can be used in your templates to display an event search form, you can specify which filters appear by setting $args['filters']. Documentation for this function shall appears shortly on the codex.

Added filters

These filters replace the ones that are being deprecated with view of their removal in 1.8 (see ‘Breaking Changes’ below for details).

eventorganiser_validate_booking_form_submission – Triggered when the booking form is validated. This hook should be used to add any error messages and/or prevent a booking form submission from being processed.
eventorganiser_process_booking_form_submission – Triggered when the form has passed validation without any errors, and is about to be processed.

In both instances the callback is passed a EO_Booking_Form instance. Developer documentation for booking forms shall be written up in full shortly, but below is an example of the validation hook in action..

/**
 * Called when the form is being validated.
 * @param EO_Booking_Form $form Booking form instance.
*/
function my_validate_callback( $form ){

     //These are just examples of how to retrieve date..
     $form_id = $form->id;
     $event_id = $form->get( 'event_id' );
     $occurrence_id = $form->get( 'event_id' );

     //$tickets is an array of quantities (purchased), indexed by ticket ID
     $tickets = $form->get_element( 'ticketpicker' )->get_value();

     //You can add an error message to the form...
     $form->add_error( 'my-error-code', 'This appears at the top of the form' );

     //... or to a specific element. (Message appears beside
     //Below is an example of retrieving the element with ID 5 and adding an error to it
     $element = $form->get_element( 5 );
     if( $element ){
          $element->add_error( 'my-error-code-2', "This appears next to the element" );

          //The following shows you how to get, and change a value entered by the user
          $value = $element->get_value();
          $value = 'this value has been changed to this';
          $element->set_value( value );
     }

     //Adding an error to either an element or form will cause the booking to be aborted.

}
add_filter( 'eventorganiser_validate_booking_form_submission', 'my_validate_callback', 10 );

‘Breaking’ changes

The following changes have been made and may affect any third-party code you may be using. All official extensions are unaffected or will have updates available for them before 1.7.0 is released. In short, if you’ve not ‘added your own code’, you do not need to do anything.

Changed & deprecated hooks

The action eo_booking_form_submission has been deprecated and shall be removed in 1.8
The filter eventorganiser_validate_booking has been deprecated and shall be removed in 1.8. Its behaviour has changed, altering the passed $input array shall no longer changes the value stored with the booking. If you wish to change something a user as entered at the point of validating it (e.g. auto-correction), use eventorganiser_validate_booking_form_submission and see the example above.
eventorganiser_validate_element_input has been deprecated and shall be removed in 1.8. Use eventorganiser_validate_booking_form_submission instead.
The action eventorganiser_process_form has been deprecated and shall be removed in 1.8.

Potential strict errors

On some PHP versions, and if you have such warnings enabled (so this shouldn’t effect any production sites) you may get an a strict error if you have added your own form element type and provided your own save() method. This method is no longer passed an $input array.

//The old...
class MY_EO_Booking_Form_Element extends EO_Booking_Form_Element{
  ...
  function save( $booking_id, $input ){
      $value = $input[$this->id]; 
      ...
  } 
  ...      
}

//The new...
class MY_EO_Booking_Form_Element extends EO_Booking_Form_Element{
  ...
  function save( $booking_id ){
      $value = $this->get_value();
      ...
  }
  ...      
}

If there is anything you’re doing right now, which you think you will not be able to do after these updates, please get in touch. Similarly, if you’re not sure how to update any code you’ve added, please get in touch via the forums.

Minor bug fixes

These include removing the “You’ve made a previous booking for this event” when the booking in question has been cancelled. Additionally, confirmation e-mails weren’t sent when a booking when from a custom booking status to confirmed.