Add custom event fields to capture additional information
MDJM Event Management offers easy customisation of the admin event screen allowing you to add and remove custom fields easily, determine when the custom fields should be displayed, and save the data. The data can then be called via custom content tags within your content, documents and emails.
Adding custom fields enables you to capture and display data that your business needs but that is not provided by default within the MDJM plugin.
The following guide walks through the process of hooking into the hooks that MDJM provides to enable developers to customise and manipulate data and default behaviour.
Field Placement
The first step in adding your custom field(s) is to determine the placement.
MDJM provides a number of hooks on the admin event screen. Each hook can be reviewed within the /includes/admin/events/metaboxes.php file.
For the purpose of this document, we’ll focus on the Event Details metabox which can be manipulated by hooking into the mdjm_event_details_fields hook.
Hooks in WordPress are called by adding add_action( 'hook_name', callback_name', priority, args ) to your code.
- hook name refers to the hook name.
mdjm_event_details_fieldsfor our example - callback name refers to your custom function which will provide the output you want. In our case a field
- priority is the priority in which the callback should execute. One hook can have multiple callbacks and that is where the priority comes into play. MDJM starts at priority 10 and as a general rule increments in 10’s. For example, the Event Date and Event Name row use a priority of 10 and the Start Time and End Time row uses a priority of 20. Therefore to output your field before the Event Date / Event Name row, you would use a priority of lower than 10 and to output your field between the Event Date / Event Name and Start Time / End Time rows you would use a priority between 11 and 19
- args refers to the number of arguments your custom function should receive from the hook. MDJM only delivers 1 argument for each hook which is the default and therefore this can be ignored
Helper Functions
In order to display input fields, retrieve data and perform actions only in specific conditions, MDJM provides a number of helper functions.
During this document, we’ll focus on two specific helper functions…
- MDJM_HTML Elements – This is a helper class that outputs input fields in the MDJM standard format
MDJM_Event->get_meta()– A method to retrieve custom data for the event and enables the display of that data
[heading element=”h3″ style=”bordered” remove_margins=”top,bottom”]Examples[/heading]
So let’s take a look at a few examples.
Example One
Adding a single field in between the time and cost rows within the Event Details metabox to record the expected number of event guests.
Remember how we increment out priority by 10? Well based on that, our date row has a priority of 10, our time row a priority of 20 and our cost row a priority of 30. To output our custom field between the time and cost rows, we’ll use a priority of 25 for our callback. Our code would be similar to the following…
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
/**
* Add a custom field to the event details metabox that displays
* and saves the number of guests in attendance.
*
* @global obj $mdjm_event The MDJM_Event class object
* @global bool $mdjm_event_update True if this event is being updated, false if new.
* @param int $event_id The event ID. Passed to this action by the hook
*
*/
function mah_add_number_guests( $event_id ) {
global $mdjm_event, $mdjm_event_update;
?>
<div class=“mdjm_field_wrap mdjm_form_fields”>
<label for=“_mdjm_event_number_guests”>Number of Guests:</label><br />
<?php echo MDJM()->html->text( array(
‘name’ => ‘_mdjm_event_number_guests’, // If we want to save data, we need to prefix our name with ‘_mdjm_event_’
‘class’ => ‘mdjm-input’,
‘value’ => $mdjm_event->get_meta( ‘_mdjm_event_number_guests’ )
) ); ?>
</div>
<?php
} // mdm_add_number_guests
add_action( ‘mdjm_event_details_fields’, ‘mah_add_number_guests’, 25 );
|
Example Two
For this example, we’ll follow the same principle, but this time we’ll add an additional text field, Average Age and we’ll make the Number of Guests field a select list.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
|
/**
* Add a custom field to the event details metabox that displays
* and saves the number of guests in attendance.
*
* @global obj $mdjm_event The MDJM_Event class object
* @global bool $mdjm_event_update True if this event is being updated, false if new.
* @param int $event_id The event ID. Passed to this action by the hook
*
*/
function mah_add_number_guests( $event_id ) {
global $mdjm_event, $mdjm_event_update;
?>
<div class=“mdjm_field_wrap mdjm_form_fields”>
<div class=“mdjm_col col2”>
<label for=“_mdjm_event_average_age”>Average Age:</label><br />
<?php echo MDJM()->html->text( array(
‘name’ => ‘_mdjm_event_average_age’,
‘class’ => ‘mdjm-input’,
‘value’ => $mdjm_event->get_meta( ‘_mdjm_event_average_age’ )
) ); ?>
</div>
<div class=“mdjm_col col2”>
<label for=“_mdjm_event_number_guests”>Number of Guests:</label><br />
<?php echo MDJM()->html->select( array(
‘name’ => ‘_mdjm_event_number_guests’,
‘selected’ => $mdjm_event->get_meta( ‘_mdjm_event_number_guests’ ),
‘options’ => array(
’50’ => ‘Up to 50’,
‘100’ => ‘Up to 100’,
‘200’ => ‘Up to 200’,
‘201’ => ‘More than 200’
)
) ); ?>
</div>
</div>
<?php
} // mdm_add_number_guests
add_action( ‘mdjm_event_details_fields’, ‘mah_add_number_guests’, 25 );
|
Example Three
In our final example, we’ll output the same two fields, but this time we’ll only do so if the event type is set to Child Birthday Party.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
|
/**
* Add a custom field to the event details metabox that displays
* and saves the number of guests in attendance.
*
* @global obj $mdjm_event The MDJM_Event class object
* @global bool $mdjm_event_update True if this event is being updated, false if new.
* @param int $event_id The event ID. Passed to this action by the hook
*
*/
function mah_add_number_guests( $event_id ) {
global $mdjm_event, $mdjm_event_update;
if ( ‘Child Birthday Party’ != $mdjm_event->get_type() ) {
return;
}
?>
<div class=“mdjm_field_wrap mdjm_form_fields”>
<div class=“mdjm_col col2”>
<label for=“_mdjm_event_average_age”>Average Age:</label><br />
<?php echo MDJM()->html->text( array(
‘name’ => ‘_mdjm_event_average_age’,
‘class’ => ‘mdjm-input’,
‘value’ => $mdjm_event->get_meta( ‘_mdjm_event_average_age’ )
) ); ?>
</div>
<div class=“mdjm_col col2”>
<label for=“_mdjm_event_number_guests”>Number of Guests:</label><br />
<?php echo MDJM()->html->select( array(
‘name’ => ‘_mdjm_event_number_guests’,
‘selected’ => $mdjm_event->get_meta( ‘_mdjm_event_number_guests’ ),
‘options’ => array(
’50’ => ‘Up to 50’,
‘100’ => ‘Up to 100’,
‘200’ => ‘Up to 200’,
‘201’ => ‘More than 200’
)
) ); ?>
</div>
</div>
<?php
} // mdm_add_number_guests
add_action( ‘mdjm_event_details_fields’, ‘mah_add_number_guests’, 25 );
|
In the final example, the fields will only display after an event type is set to Child Birthday Party and the event is saved.