AddCal
Back to all articles

Integrating Wordpress Advanced Custom Fields (ACF) with AddCal Smart Links

By AddCal Team•

This guide will walk you through the process of using the Advanced Custom Fields (ACF) plugin in WordPress to dynamically populate the event details for your AddCal Smart Links. This is incredibly useful for creating event listings, appointment booking pages, or any content where event details are managed within WordPress and need to be easily added to a user's calendar via AddCal.

Why Integrate ACF with AddCal?

Instead of manually creating a Smart Link for every event or hardcoding details, this integration allows you to:

  • Manage Event Data in WordPress: Keep all your event-related information directly within your WordPress posts, pages, or custom post types using ACF fields.
  • Automate Smart Link Generation: Dynamically generate AddCal Smart Link buttons or URLs that pull event details directly from your ACF fields.
  • Streamline Content Creation: Reduce manual data entry and potential errors, making your workflow more efficient.

Prerequisites

Before you begin, ensure you have the following:

  1. A WordPress Website: Your self-hosted WordPress installation.
  2. AddCal Account: An active AddCal account with a Smart Link created.
  3. Advanced Custom Fields (ACF) Plugin: Installed and activated on your WordPress website. The free version is sufficient for most cases.
  4. Basic WordPress Theme Knowledge: Familiarity with editing WordPress theme files (specifically functions.php or using a custom plugin).

Step 1: Create Your Smart Link in AddCal

First, you need to set up your Smart Link in the AddCal dashboard.

  1. Log in to your AddCal account.
  2. Navigate to the Smart Links section.
  3. Create a New Smart Link or select an existing one.
  4. Note your Smart Link Key: This is the unique identifier for your Smart Link (e.g., z2xrwph2pl). You'll find it in the "Shareable Link" or "Embeddable Button" section.
  5. Identify the Parameters You'll Use: Review the "Parameter Information" section in AddCal to see the available parameters (title, date_start, date_end, duration, is_all_day, timezone, location, description). You'll map your ACF fields to these.

Step 2: Set Up Advanced Custom Fields (ACF) in WordPress

Now, you'll create the ACF fields that will hold your event details in WordPress.

  1. Log in to your WordPress admin dashboard.
  2. Go to ACF > Field Groups.
  3. Click Add New to create a new field group (e.g., "Event Details").
  4. Add the following fields (or a subset relevant to your needs):
    • Event Title:
      • Field Label: Event Title
      • Field Name: event_title
      • Field Type: Text
      • (Required for AddCal)
    • Event Start Date & Time:
      • Field Label: Event Start Date & Time
      • Field Name: event_start_date
      • Field Type: Date Time Picker
      • Display Format: YYYY-MM-DD HH:mm:ss (Crucial for ISO format)
      • Return Format: YYYY-MM-DDTHH:mm:ss (Crucial for AddCal's YYYY-MM-DDTHH:mm:ss ISO 8601 format)
      • (Required for AddCal)
    • Event End Date & Time (Optional, if using Duration):
      • Field Label: Event End Date & Time
      • Field Name: event_end_date
      • Field Type: Date Time Picker
      • Display Format: YYYY-MM-DD HH:mm:ss
      • Return Format: YYYY-MM-DDTHH:mm:ss
      • (Use this OR 'Event Duration', not both for the same event)
    • Event Duration (Optional, if using End Date):
      • Field Label: Event Duration (minutes)
      • Field Name: event_duration
      • Field Type: Number
      • (Use this OR 'Event End Date & Time', not both for the same event)
    • All-day Event:
      • Field Label: Is All-day Event?
      • Field Name: is_all_day_event
      • Field Type: True/False (or Select with 0 and 1 options)
      • Return Value: 0 for false, 1 for true (if using True/False field type, it will return true or false strings, which AddCal understands, but a Select field might offer more control for 0 or 1 specifically.)
    • Event Timezone:
      • Field Label: Event Timezone (IANA)
      • Field Name: event_timezone
      • Field Type: Text
      • Instructions: Enter IANA timezone (e.g., Australia/Sydney, America/New_York).
      • (Optional)
    • Event Location:
      • Field Label: Event Location
      • Field Name: event_location
      • Field Type: Text
      • (Optional)
    • Event Description:
      • Field Label: Event Description
      • Field Name: event_description
      • Field Type: Text Area
      • (Optional)
  5. Location Rules: Under "Location Rules," set where these fields should appear (e.g., Post Type is equal to Post or a specific custom post type).
  6. Publish your Field Group.

Step 3: Populate ACF Fields on Your Content

Now, create or edit a WordPress post/page and populate your newly created ACF fields with event data.

  1. Go to Posts > Add New (or edit an existing post/page where you applied the ACF field group).
  2. Scroll down to find your "Event Details" custom fields.
  3. Enter the relevant information for your event into each field.
    • Important for Date/Time: Ensure the dates and times are accurate and consider the time portion carefully, especially if it's not an all-day event. Remember the YYYY-MM-DDTHH:mm:ss format is crucial for the "Return Format" in your ACF Field settings.
  4. Publish or Update your post/page.

Step 4: Create a WordPress Shortcode

This step will guide you through creating a WordPress shortcode. This allows you to easily insert the AddCal button into any post, page, or even widget areas using the block editor or classic editor, without touching theme files directly for each instance.

  1. Access your theme's functions.php file or a custom plugin file:
    • It's generally recommended to use a child theme's functions.php file or a custom site-specific plugin to add shortcodes, so your changes aren't overwritten when you update your theme.
    • You can access functions.php via Appearance > Theme File Editor in your WordPress admin.
  2. Add the shortcode function: Copy and paste the following PHP code into your functions.php file (or custom plugin file).
  3. <?php
/**
 * Custom Shortcode for AddCal Button with ACF Integration
 *
 * This shortcode pulls event details from Advanced Custom Fields
 * and generates the AddCal embed button.
 *
 * Usage: [addcal_button smart_link_key="YOUR_SMART_LINK_KEY"]
 * Replace YOUR_SMART_LINK_KEY with your actual AddCal Smart Link Key.
 */
function addcal_acf_button_shortcode($atts) {
    // Define default attributes for the shortcode
    $atts = shortcode_atts(
        array(
            'smart_link_key' => '', // MANDATORY: User must provide their Smart Link Key
        ),
        $atts,
        'addcal_button'
    );

    $smart_link_key = esc_attr($atts['smart_link_key']);

    // Check if a Smart Link Key is provided
    if (empty($smart_link_key)) {
        return '<p style="color: red;">Error: AddCal Smart Link Key is missing for the `[addcal_button]` shortcode.</p>';
    }

    // Output buffer to capture HTML
    ob_start();

    // Ensure ACF functions are available before proceeding.
    if (function_exists('get_field')) :
        // Get the current post ID. For shortcodes, it's usually the global post ID.
        $post_id = get_the_ID();

        // Retrieve ACF field values for the current post.
        // Ensure these field names match what you set up in Step 2 of the guide.
        $event_title        = get_field('event_title', $post_id);
        $event_start_date   = get_field('event_start_date', $post_id); // Format: YYYY-MM-DDTHH:mm:ss
        $event_end_date     = get_field('event_end_date', $post_id);   // Format: YYYY-MM-DDTHH:mm:ss
        $event_duration     = get_field('event_duration', $post_id);  // In minutes
        $is_all_day         = get_field('is_all_day_event', $post_id); // Boolean (true/false) or 0/1
        $event_timezone     = get_field('event_timezone', $post_id);
        $event_location     = get_field('event_location', $post_id);
        $event_description  = get_field('event_description', $post_id);

        // --- AddCal Specific Formatting and Logic ---

        // Convert boolean 'is_all_day_event' to 'true'/'false' string for AddCal
        $is_all_day_string = $is_all_day ? 'true' : 'false';

        // Handle date_end vs. duration logic based on AddCal parameters
        $end_time_element = '';
        if (!empty($event_duration)) {
            // If duration is set, prioritize it over end date
            $end_time_element = '<span class="duration">' . esc_attr($event_duration) . '</span>';
        } elseif (!empty($event_end_date)) {
            // Otherwise, use the end date if available
            $end_time_element = '<span class="end">' . esc_attr($event_end_date) . '</span>';
        }

        // Check if the essential fields for an event exist before displaying the button
        if (!empty($event_title) && !empty($event_start_date)) :
        ?>
        <div class="addcal-button-container" style="text-align: center; margin-top: 20px;">
            <div class="addcal-btn"
                data-base="addcal.co"
                data-smart-link-key="<?php echo $smart_link_key; ?>"
                data-theme="default">

                <?php if (!empty($event_title)) : ?>
                    <span class="title"><?php echo esc_html($event_title); ?></span>
                <?php endif; ?>

                <?php if (!empty($event_start_date)) : ?>
                    <span class="start"><?php echo esc_attr($event_start_date); ?></span>
                <?php endif; ?>

                <?php echo $end_time_element; // This will be duration OR end date ?>

                <?php if (!empty($event_timezone)) : ?>
                    <span class="timezone"><?php echo esc_attr($event_timezone); ?></span>
                <?php endif; ?>

                <?php if (!empty($event_description)) : ?>
                    <span class="description"><?php echo esc_html($event_description); ?></span>
                <?php endif; ?>

                <?php if (!empty($event_location)) : ?>
                    <span class="location"><?php echo esc_html($event_location); ?></span>
                <?php endif; ?>

                <span class="is_all_day"><?php echo esc_attr($is_all_day_string); ?></span>
            </div>
            <script src="https://cdn.addcal.co/embed/1.1.0/button.min.js" async defer></script>
        </div>
        <?php
        else :
            // Message if essential event data is missing
            echo '<p style="color: gray;">AddCal button not displayed: Essential event details are missing for this content. Please complete the event ACF fields.</p>';
        endif; // End check for essential fields
    else :
        // Message if ACF is not active
        echo '<p style="color: red;">Error: Advanced Custom Fields (ACF) plugin is not active. The AddCal shortcode requires ACF.</p>';
    endif; // End function_exists('get_field') check

    return ob_get_clean(); // Return the captured HTML
}
add_shortcode('addcal_button', 'addcal_acf_button_shortcode');
?>
  4. Save the functions.php file (or your custom plugin file).

How to Use the Shortcode

Now you can use the shortcode in any post, page, or text widget:

  1. Edit a post or page where you have populated the AddCal-related ACF fields (from Step 3).
  2. In the content editor (either Classic or Block editor), simply add the shortcode:
  3. [addcal_button smart_link_key="YOUR_SMART_LINK_KEY"]
  4. Remember to replace YOUR_SMART_LINK_KEY with the actual Smart Link Key from your AddCal account (from Step 1).
  5. Update or Publish your post/page.

When the page is viewed on the front end, WordPress will process this shortcode, retrieve the ACF fields associated with that post/page, and generate the AddCal button with the dynamic event data.

Tips and Best Practices

  • Date/Time Format is CRITICAL: AddCal is quite flexible, but for consistency and reliability, always use the ISO 8601 format (YYYY-MM-DDTHH:mm:ss) for your date_start and date_end parameters. Configure your ACF Date Time Picker fields to return this format.
  • IANA Timezones: For the timezone parameter, use standard IANA timezone names (e.g., America/New_York, Europe/London). A full list can be found in the AddCal parameter information.
  • Handle Optional Fields: As shown in the code, use if (!empty($field_variable)) checks before outputting the <span> tags for optional parameters. This prevents empty data attributes from being sent.
  • duration vs. date_end: Remember that AddCal prioritizes duration if both duration and date_end are provided. Structure your ACF fields and logic accordingly.
  • Styling: You can style the .addcal-button-container and other elements around the AddCal button using your theme's CSS to match your website's design.
  • Debugging: If the button doesn't work as expected:
    • Check your browser's developer console for any JavaScript errors.
    • Inspect the HTML of the .addcal-btn div on your page to ensure the data- attributes are correctly populated with values from your ACF fields.
    • Double-check your smart_link_key attribute in the shortcode.

By following these steps, you'll have a robust system for generating AddCal Smart Links directly from your WordPress content using Advanced Custom Fields, significantly enhancing your event management capabilities.

Last updated on June 21, 2025

Continue reading

Browse all articles