Developers

Available Filters & Snippets

You can use the following snippets in your theme’s functions.php file or even better, create a custom plugin or using the Code Snippets plugin. (The latter two are the better options, as they won’t be overwritten by theme updates!)

You can find all picu filters and how they work below. Also have a look at the filter examples page for more advanced filtering.

picu Core

In the following section you find the filters/hooks that can be used with the free picu plugin you can download from WordPress.org. Below you will soon find more filters/hooks that can be used in conjunction with our Pro modules.

Define a custom base slug for collections

This will change the default slug from domain.tld/collections/ak4h38 to domain.tld/my-defined-slug/ak4h38.

Beware, that this changes the URL for all collections – including those you might have sent to clients before.

function my_picu_collection_slug() {
    return 'my-defined-slug';
}

add_filter( 'picu_collection_slug', 'my_picu_collection_slug' );

Please note: Make sure to go to “Settings > Permalinks” in your WordPress Admin after you implemented the snippet.

Disable random slug generation for picu collections

picu will then use the collection title to generate the slug, which is the WordPress default.

add_filter( 'picu_collection_do_random_slug', '__return_false' );

Set default share method to “Copy link & send manually”

picu will then select the Copy link & share manually tab by default, when you create a new collection.

add_filter( 'picu_default_share_method_is_email', '__return_false' );

Define a custom filename separator

This separator is used when you copy the image filenames after your client has approved a collection. This separator is also used in the proof text file that you can download once a collection has been approved. The default is a single space.

The example below will add a comma after each filename.

function my_custom_filename_separator( $divider ) {
    return ', ';
}

add_filter( 'picu_filename_separator', 'my_custom_filename_separator' );

There is an alternate method of defining a custom filename separator available. Just put the following line in your wp-config.php file:

define( 'PICU_FILENAME_SEPARATOR', "\n" );

This will add a new line after each filename, btw.

Define custom filenames when copying approved image names

By default picu will not use a suffix (like .jpg), when you copy the image filenames (or in the proof text file) after your client has approved a collection. With the following filter you can change what is being copied.

In the example below, we change the output to use the whole filenames, including the suffix (like .jpg).

function my_picu_approved_filename( $filename, $attachment_id ) {
    $attachment = wp_get_attachment_image_src( $attachment_id, 'full' );
    return wp_basename( $attachment[0] );
}

add_filter( 'picu_approved_filename', 'my_picu_approved_filename', 10, 2 );

By using the $attachement_id you can use pretty much any meta data attached to the respective image.

Define custom max width and height values for picu images

Set the maximum height and width with which picu images should be displayed.

function my_picu_large_image_size( $sizes ) {
    return array(
        'width' => 3000,
        'height' => 2000
    );
}

add_filter( 'picu_large_image_size', 'my_picu_large_image_size' );

Do not generate picu’s custom image sizes

Disable the generation of custom smaller and intermediate image sizes

function my_picu_disable_custom_image_sizes( $sizes ) {
    return array();
}

add_filter( 'picu_intermediate_image_sizes', 'my_picu_disable_custom_image_sizes' );

Set the default expiration time

Available in picu 2.0.

Set the default expiration time in days. The default is 30 days. This example will set the duration to five days:

add_filter( 'picu_expiration_length', 5 );

Send collection password with the email

By default picu will include the collection password in the email to the client. You can set this in the options, or disable it using this filter:

add_filter( 'picu_send_password_in_email', '__return_false' );

Define a custom FROM name for picu emails

Defaults to your Site Title.

function my_picu_email_from_name( $from_name, $mail_context, $collection_id ) {
     return 'Max Mustermann';
}

add_filter( 'picu_email_from_name', 'my_picu_email_from_name', 10, 3 );

Please note, that using this filter will overwrite your settings under “picu > Settings > General Settings”.

Define a custom FROM address for picu emails

Defaults to no-reply@domain.tld.

function my_picu_email_from_address( $from_address, $mail_context, $collection_id ) {
    return 'my.custum@email.address';
}

add_filter( 'picu_email_from_address', 'my_picu_email_from_address', 10, 3 );

Please note, that using this filter will overwrite your settings under “picu > Settings > General Settings”.

Define custom CC address(es) for picu emails

You can also define multiple addresses, just seperate them with a comma.

function my_picu_email_cc( $cc_address, $mail_context, $collection_id ) {
	return 'my.cc@email.address';
}

add_filter( 'picu_email_cc', 'my_picu_email_cc', 10, 3 );

Define custom BCC address(es) for picu emails

You can also define multiple addresses, just seperate them with a comma.

function my_picu_email_bcc( $bcc_address, $mail_context, $collection_id ) {
	return 'my.bcc@email.address';
}

add_filter( 'picu_email_bcc', 'my_picu_email_bcc', 10, 3 );

Change the email subject for picu emails

By default, the subject contains the collection title. In the example below we add “Please approve” in front of the collection title, when sending the collection to the client.

function my_picu_mail_subject( $subject, $mail_context, $collection_id ) {

    if ( $mail_context == 'client_collection_new' ) {
        return 'Please approve: ' . $subject;
    }

    return $subject;
}

add_filter( 'picu_mail_subject', 'my_picu_mail_subject', 10, 3 );

Change the content type for picu emails

Please use with caution, and only adjust if you kow, what you are doing.

function my_picu_email_content_type( $content_type, $mail_context, $collection_id ) {
    return 'text/plain';
}

add_filter( 'picu_email_content_type', 'my_picu_email_content_type', 10, 3 );

Change headers for picu emails

In this example we add a Reply-To address:

function my_picu_email_headers( $headers, $mail_context, $collection_id ) {
    $headers .= "Reply-To: my.reply@email.address\r\n";
    return $headers;
}

add_filter( 'picu_email_headers', 'my_picu_email_headers', 10, 3 );

Define a custom message for picu emails

Change the default message in emails that picu sends out.

function my_picu_email_message( $message ) {
    $message = 'Custom Message';
    return $message;
}

add_filter( 'picu_client_mail_message', 'my_picu_email_message' );

Please note, that with our Brand & Customize Pro module, it is possible to create multiple email templates.

Set customer email reminder time

Define a custom reminder time in seconds, eg. send the reminder after 48 hours (instead of the default 24):

add_filter( 'picu_selection_reminder_time_diff', function( $default ) {
    return 172800;
});

Define a custom TO address for approval email notifications

By default approval notifications are sent to the email address of the user, who created the collection. With this filter you can overwrite that.

function my_picu_approval_mail_recipient( $collection_id, $recipient_email ) {
	return 'what.ever@you.choose.com';
}

add_filter( 'picu_approval_mail_recipient', 'my_picu_approval_mail_recipient', 10, 2 );

Please note, that with the example above, all approval notifications will got to the same address.

Disable saving email history

This filter allows you to prevent picu from remembering the email addresses when sending out collections.

add_filter( 'picu_save_email_history', '__return_false' );

Disable using email history

By returning false via this filter, picu will not display the email address suggestions when creating a new collection.

add_filter( 'picu_use_email_history', '__return_false' );

Customize the email history list

The following example will add an email address to the top of the list and also display the number of uses per email address.

function my_picu_email_history_list( $datalist, $history ) {
	$datalist = '<datalist id="email-history">';

	// Eg. add an address to the top of the list
	array_unshift( $history, [ 'email' => 'most.important@client.com', 'uses' => '' ] );

	foreach( $history as $entry ) {
		// Eg. display the number of times an address was used
		$datalist .= '<option value="' . $entry['email'] . '">' . $entry['email'];
		if ( ! empty( $entry['uses'] ) ) {
			$datalist .= ' (' . $entry['uses'] . ')';
		}
		$datalist .= '</option>';
	}
	$datalist .= '</datalist>';

	return $datalist;
}

add_filter( 'picu_email_history_list', 'my_picu_email_history_list', 10, 2 )

Change the approval heading

Adjust the approval modal headline:

add_filter( 'picu_approval_heading', function( $headline ) {
    return 'My custom headline';
});

Change the approval warning message

Change the content of the message that is displayed above the “Approve Selection” button. Defaults to:

You are about to approve this collection.
Please note, that you won’t be able to make changes to your selection after that.

function my_picu_approval_warning( $message ) {
    return '<p><strong>Thank you for your time.</strong><br />We will get right to work on your images!</p>';
}

add_filter( 'picu_approval_warning', 'my_picu_approval_warning' );

Change the approval button text

With this filter you can adjust the text for the button below the approval form, which will send the selection – and close the collection for that recipient.

add_filter( 'picu_approval_button_text', function( $button_text ) {
	return 'My custom button text';
});

Change the send selection button text

With this filter you can adjust the text for the button below the gallery view, which leads to the approval form.

add_filter( 'picu_send_selection_button_text', function( $button_text ) {
	return 'My custom button text';
});

Add custom content above the collection images

Add/display custom elements/content above the images in a collection.

function my_picu_before_collection_images() {
    echo '<div style="margin: 0 1rem;">My custom content above the collection images</div>';
}

add_action( 'picu_before_collection_images', 'my_picu_before_collection_images' );

See an extended example on how to add content above the collection images.

Add Custom JavaScript

Add custom scripts, eg. for tracking or analytics, to your picu collections.

function my_picu_custom_scripts( $custom_scripts ) {
    $custom_scripts .= '<!-- YOUR ANALYTICS JS CODE -->';

    return $custom_scripts;
}

add_filter( 'picu_custom_scripts', 'my_picu_custom_scripts' );

Warning: Make sure, to add your custom code to the $custom_scripts string. Do not just overwrite the variable.

Define who can use picu

Define a capability, which a user/role must have, to access picu. The default is manage_options.

function my_picu_custom_capability() {
    return 'edit_posts';
}

add_filter( 'picu_capability', 'my_picu_custom_capability' );

Have a look at the full list of capabilities – and especially which roles usually have which capabilities.

Adjust the collection post type settings

Allows you to adjust the custom post type arguments. The example below adds author support to picu collections:

function my_picu_cpt_collection_args( $args ) {
    array_push( $args['supports'], 'author' );
    return $args;
}

add_filter( 'picu_cpt_collection_args', 'my_picu_cpt_collection_args' );

Please be extra careful when using this filter and check out all of the available post type parameters in the WordPress Code Reference, before making any changes.

Execute code after a collection has been approved

This hook is fired after a collection has been approved. For multi-collections if fires each time a recipient approves the collection.

function my_picu_after_approval( $collection_id, $ident ) {
    // Do something
}

add_action( 'picu_after_approval', 'my_picu_after_approval', 10, 2 );

Execute code after a picu email has been sent

This hook fires after a picu email has been sent.

function my_picu_after_email_sent( $mail_context, $collection_id ) {
    // Do something
}

add_action( 'picu_after_email_sent', 'my_picu_after_email_sent', 10, 2 );

Brand & Customize Module

Use custom styles

Change the appearance of your collections by adding custom css.

function my_custom_picu_styles( $custom_styles ) {
    $custom_styles .= 'body { background-color: pink; }';
    return $custom_styles;
}

add_filter( 'picu_brand_customize_styles', 'my_custom_picu_styles' );

Warning: Make sure, to add your custom code to the $custom_styles string. Do not overwrite the variable!

Customize the Approval Form

Define custom fields for the approval form. The filter accepts an array of fields. Check out the field parameters below.

add_filter( 'picu_approval_fields', 'my_picu_approval_fields' );

The following field parameters are supported:

$type
(string, required) Possible values are paragraph, select, text, textarea.
$label
(string, required) The Label that is displayed before the input field – or the text for a paragraph field.
$placeholder
(string, optional) Placeholder text that is displayed when a field is empty.
$width
(integer, optional) Define field width; fields will wrap automatically.
Allowed values are 20, 25, 30, 50, 60, 75, 100; default: 100
$break
(bool, optional) Whether the the field should start a new line.
$required
(bool, optional) Whether the field is required.
$value
(string, optional) Predefine a default value.
$validation
(string, optional) Use a regex pattern which the input will be validated against.
$options
(array, optional, only available for a select field) Define the options as an array of choices; separate values from display text by using the | character.

Take a look at this snippet for a more detailed example on how to customize the approval form.

Download Module

Define filename prefix in .zip file

By default picu adds numbers (with leading zeros) in front of the file name, when creating the .zip file. We do this to preserve the order in which the photos are displayed in the collection. You can change the prefix using this filter. To disable the prefix, just return an emptry string like so:

function my_picu_download_file_name_prefix( $prefix, $img_num, $images ) {
	return '';
}

add_filter( 'picu_download_file_name_prefix', 'my_picu_download_file_name_prefix', 10, 3 );

Delivery Module

Change the delivery box title

You can change the delivery box title by using the picu_delivery_box_title filter.

add_filter( 'picu_delivery_box_title', function( $title ) {
    return 'My custom delivery box title';
});

Expand the image list by default

Available from picu Pro 1.1.0

To expand the image list by default you can use to following filter/snippet:

add_filter( 'picu_delivery_show_images_by_default', '__return_true' );

Change the delivery box message

You can use the delivery box message by using the picu_delivery_box_message filter.

add_filter( 'picu_delivery_box_message', function( $message ) {
    return 'My custom delivery box message';
});

Still having issues?

In your WordPress Admin go to picu > Settings > Debug Info and send the contents of this page and your questions to support@picu.io.