Customization Examples¶

• Table of contents
• Customization Examples
  • How to use these snippets
    • Theme's functions.php
    • Custom Plugin
  • Examples
    • Exclude licensing information
    • Append a copyright notice under the text of any CC license
    • Customize the author URL
    • Customize the text templates of a single license or of a group of licenses
      • Change the long text template
      • Change the short text template
      • Change the media license text template
      • Change the extra permissions text template
      • Change the surrounding HTML template of the content license
      • Change the surrounding HTML template of the media license
    • Customize the font and other CSS attributes of the license block
    • Modify the widget's HTML output
    • Enclose the license block in <footer> HTML 5 tags
    • Add the WTFPL license
    • Customize the license URL
    • Add a Public Domain statement

How to use these snippets¶

The code snippets found in this page are PHP source code. You can use this code in the following ways.

Theme's functions.php¶

The snippets can be added in the currently activated theme's functions.php file.

This is the fastest and easiest way to use the snippets, but there are some shortcomings:

• Every time the theme is updated, the functions.php file is updated as well, which means all your customizations are lost. So, if you use functions.php for your customizations, make sure to always have a backup of them.
• Each theme uses its own functions.php file, so every time you activate a different theme, make sure to also move the customizations to the functions.php file of the currently activated theme.

If you frequently change your theme, you should definitely consider the alternative option below.

Custom Plugin¶

In order to avoid the shortcomings involved with storing the snippets in the functions.php file, you can create a custom plugin for your customizations and add the snippets in there.

Creating a plugin for WordPress is really easy. Add the following in a file at /wp-content/plugins/wordpress-customizations.php:

<?php
/*
Plugin Name:  WordPress Customizations
Description:  Custom functionality for WordPress plugins and themes.
Version:      1.0.0
Author:       John Smith
Author URI:   http://www.example.com
License:      GNU General Public License v2 or later
License URI:  http://www.gnu.org/licenses/gpl-2.0.html
*/

// Prevent direct access to this file.
if ( ! defined( 'ABSPATH' ) ) {
    header( 'HTTP/1.0 403 Forbidden' );
    echo 'This file should not be accessed directly!';
    exit; // Exit if accessed directly
}

// Add your code below

Then, add your customizations and activate the plugin through the WordPress administration interface.

Examples¶

This section contains customization examples. Read more information about the available filter hooks.

Exclude licensing information¶

It is possible to exclude licensing information from a web page or a part of a WordPress powered web site by using the bccl_exclude_license filter hook.

The following example demonstrates how to exclude licensing information from a WordPress Page with slug sample-page:

function bccl_force_exclude_licensing($default, $post) {
    if ( is_page('sample-page') ) {
        return true;
    }
    return $default;
}
add_filter('bccl_exclude_license', 'bccl_force_exclude_licensing', 10, 2);

Another example which excludes the licensing information based on post type:

function bccl_force_exclude_licensing($default, $post) {
    $post_type = get_post_type($post);
    if ( $post_type === false ) {
        return $default;
    }
    // Set supported post types
    $supported_types = array('page', 'attachment');
    // Exclude not supported post types
    if ( ! in_array($post_type, $supported_types) ) {
        return true;
    }
    return $default;
}
add_filter('bccl_exclude_license', 'bccl_force_exclude_licensing', 10, 2);

Append a copyright notice under the text of any CC license¶

This can easily be done by hooking a custom function to the bccl_full_license_block_cc filter:

function append_copyright_notice_to_cc_text( $license_text ) {
    $extra_text = '<br />Copyright &copy; ' . get_the_date('Y') . ' - Some Rights Reserved';
    return $license_text . $extra_text;
}
add_filter( 'bccl_full_license_block_cc', 'append_copyright_notice_to_cc_text' );

Customize the author URL¶

By default the author URL is the URL of the author archive. Customize it with:

function bccl_custom_author_url( $default, $post, $creator_format ) {
    return get_bloginfo('url');
    //return trailingslashit(get_bloginfo('url')) . 'about/author/';
    // Example for BuddyPress profile
    // return trailingslashit( bp_core_get_user_domain( $post->post_author ) . bp_get_profile_slug() );
}
add_filter( 'bccl_author_url', 'bccl_custom_author_url', 10, 3 );

Customize the text templates of a single license or of a group of licenses¶

CC-Configurator lets you customize the text template of any single license or of a group of licenses. A group is identified by a common slug prefix, for instance the slug of each Creative Commons license is prefixed with cc.

There are 3 text templates that could be changed and also there are some template variables that can be used in each template. The modification of a template can be done by attaching a filtering function to the proper filter hook. The filtering function should return the custom text template. Moreover, some template variables (enclosed in pound characters #) can be used. The available filter hook names and the available template variables are outlined below:

• bccl_license_text_long_template: Filter hook that can be used to customize the extended licensing text (the one that provided details about the author and the licensed work). Available template variables:
  • #work#: expanded to the hyperlink to the content page.
  • #creator#: expanded to the hyperlink to the local author profile.
  • #license#: expanded to the hyperlink to the license page.
  • #year#: expanded to the year of the publication of the content.
• bccl_license_text_short_template: Filter hook that can be used to customize the generic licensing text (the one that does not contain any specific details about the author or the work). Available template variables:
  • #license#: expanded to the hyperlink to the license page.
  • #year#: expanded to the year of the publication of the content.
• bccl_license_text_media_template: Filter hook that can be used to customize the licensing text that appears under the media files inside the posts. Available template variables:
  • #media_type#: expanded to the media type (image/video/audio).
  • #creator#: expanded to the hyperlink to the local author profile.
  • #license#: expanded to the hyperlink to the license page.
• bccl_extra_permissions_template: Filter hook that can be used to customize the text which indicates the web page where extra permissions could be found. Available template variables:
  • #page#: expanded to the hyperlink of the page containing the extra permissions.

In order to change the template of a group of licenses, the common slug prefix (eg cc for Creative Commons licenses) can be appended to the filter hook name, eg: bccl_license_text_long_template_cc

Change the long text template¶

The following example demonstrates how to alter the extended license templates of all Creative Commons licenses:

function bccl_custom_cc_extended_text_template() {
    // Supports: #work#, #creator#, #license#, #year#
    return 'Unless otherwise expressly stated, #work# by #creator# is licensed under a #license#.';
}
add_filter( 'bccl_license_text_long_template_cc', 'bccl_custom_cc_extended_text_template' );

Change the short text template¶

The following example demonstrates how to alter the short license templates of all Creative Commons licenses:

function bccl_custom_cc_short_text_template() {
    // Supports: #license#, #year#
    return 'Unless otherwise expressly stated, This work is licensed under a #license#.';
}
add_filter( 'bccl_license_text_short_template_cc', 'bccl_custom_cc_short_text_template' );

Change the media license text template¶

The following example demonstrates how to alter the media license templates of all Creative Commons licenses:

function bccl_custom_cc_media_license_template() {
    // Supports: #work#, #creator#, #license#, #year#
    //return 'Unless otherwise expressly stated, #work# by #creator# is licensed under a #license#.';
    // Supports: #media_type#, #creator#, #license#
    return 'Copyright &copy; <em>#creator#</em> under #license#';
}
add_filter( 'bccl_license_text_media_template_cc', 'bccl_custom_cc_media_license_template' );

Change the extra permissions text template¶

The following example demonstrates how to alter the extra permissions template of all Creative Commons licenses:

function bccl_custom_cc_extra_perms_text_template() {
    // Supports: #page#
    return 'Additional details about the licensing of this work can be found in our #page# section.';
}
add_filter( 'bccl_extra_permissions_template_cc', 'bccl_custom_cc_extra_perms_text_template' );

Change the surrounding HTML template of the content license¶

function bccl_custom_outer_html($default) {
    // Default: <p prefix="dct: http://purl.org/dc/terms/ cc: http://creativecommons.org/ns#" class="cc-block">#inner_html#</p>
    // Needs one '#inner_html#' placeholder which will be expanded to the license text.
    return '<p xmlns:dct="http://purl.org/dc/terms/" xmlns:cc="http://creativecommons.org/ns#" class="cc-block">#inner_html#</p>';
}
add_filter( 'bccl_outer_html_template_cc', 'bccl_custom_outer_html' );

Change the surrounding HTML template of the media license¶

function bccl_custom_outer_html_media($default) {
    // Default: <div style="#style#" class="#classes#" prefix="dct: http://purl.org/dc/terms/ cc: http://creativecommons.org/ns#" typeof="cc:Work" about="#attachment_url#">#inner_html#</div>
    // Supports placeholders: #style#, #classes#, #attachment_url#
    // Needs one '#inner_html#' placeholder which will be expanded to the license text.
    return '<div style="#style#" class="#classes#" xmlns:dct="http://purl.org/dc/terms/" xmlns:cc="http://creativecommons.org/ns#" typeof="cc:Work" about="#attachment_url#">#inner_html#</div>';
}
add_filter( 'bccl_outer_html_media_template_cc', 'bccl_custom_outer_html_media' );

Customize the font and other CSS attributes of the license block¶

This can easily be done by hooking a custom function to the bccl_extra_style filter and inject extra styles to the default inline CSS:

function bccl_customize_licence_block_font() {
    return <<<EOT
.cc-block {
  font-family: courier-new;
  font-size: 0.8em;
}
EOT;
}
add_filter( 'bccl_extra_style', 'bccl_customize_licence_block_font' );

Modify the widget's HTML output¶

This can easily be done by hooking a custom function to the bccl_widget_html filter hook (for content pages) or to the bccl_widget_html_archives filter hook (for the front page and the archives):

function bccl_extend_widget_html_output_for_content( $html ) {
    $extended_html = 'some HTML code' . $html . 'some more HTML code';
    return $extended_html;
}
add_filter( 'bccl_widget_html', 'bccl_extend_widget_html_output_for_content' );

Enclose the license block in <footer> HTML 5 tags¶

This can easily be done by hooking a custom function to the bccl_license_block_enclosure filter:

function bccl_add_footer_tags( $block ) {
    return '<footer>' . $block . '</footer>';
}
add_filter( 'bccl_license_block_html', 'bccl_add_footer_tags' );

Add the WTFPL license¶

This can easily be done by hooking a custom generator function to the bccl_licenses filter:

// Example WTFPL generator.
function bccl_wtfpl_generator( $license_slug, $license_data, $post, $options, $minimal=false ) {
    // Here we use exactly the same templates as the CC licenses,
    // which should be suitable for any kind of permissive copyright based license.
    $templates = bccl_default_license_templates();
    // In case we need to customize the default templates, here is how to do it:
    //$templates = array_merge( bccl_default_license_templates(), array(
    //    // Supported template tags: #work#, #creator#, #license#, #year#
    //    'license_text_long' => __('#work#, written by #creator# in #year#, has been published under the terms of the #license#.', 'cc-configurator'),
    //    // Supported template tags: #license#, #year#
    //    'license_text_short' => __('This article is published under a #license#.', 'cc-configurator'),
    //    // Supported template tags: #page#
    //    'extra_perms' => __('More information about how to reuse or republish this work may be available in our #page# section.', 'cc-configurator')
    //));
    // Finally we use the base generator to build and return the HTML content.
    // The base generator should be suitable for any type of license.
    return bccl_base_generator( $license_slug, $license_data, $post, $options, $minimal, $templates );
}
// Add the WTFPL license to the array of available licenses.
function bccl_add_wtfpl_license( $licenses ) {
    $licenses['wtfpl'] = array(         // slug (unique for each license)
        'url' => 'http://www.wtfpl.net/about/',    // URL to license page
        'name' => 'WTFPL International License',   // Name of the license
        'name_short' => 'WTFPL',
        'button_url' => 'http://www.wtfpl.net/wp-content/uploads/2012/12/wtfpl-badge-1.png', // URL to license button
        'button_compact_url' => 'http://www.wtfpl.net/wp-content/uploads/2012/12/wtfpl-badge-2.png', // URL to a small license button
        'generator_func' => 'bccl_wtfpl_generator'
    );
    return $licenses;
}
add_filter( 'bccl_licenses', 'bccl_add_wtfpl_license' );

Customize the license URL¶

Sometimes, modifying the license URL is required. for instance in order to link to the localized version of the license text. The following example demonstrates how to append the deed.COUNTRY_CODE part to the license URLs.

function bccl_localized_license_url( $license_url ) {
    if ( ! empty( $license_url ) ) {
        return $license_url . 'deed.el';
    }
    return $license_url;
}
add_filter( 'bccl_license_url', 'bccl_localized_license_url' );

Add a Public Domain statement¶

CC-Configurator does not contain a statement about the copyright being in the Public Domain in the default licenses, because of the legal complexity that surrounds such a statement (jurisdiction of application, legitimate reasoning, laws that enforce copyright, etc).

However, it is very easy to add such a statement in the available licenses by hooking a custom generator function to the bccl_licenses filter hook:

// Example Public Domain generator.
function bccl_copyright_expired_generator( $license_slug, $license_data, $post, $options, $minimal=false ) {
    $templates = bccl_default_license_templates();
    // In case we need to customize the default templates, here is how to do it:
    $templates = array_merge( bccl_default_license_templates(), array(
        // Long template
        // Supported template variables: #work#, #creator#, #license#, #year#
        'license_text_long' => __('The copyright for #work# by #creator# is in the public domain because it has expired.', 'cc-configurator'),
        // 'license_text_long' => __('The copyright for #work# by #creator# was injected into the public domain for other reasons, such as failure to adhere to required formalities or conditions.', 'cc-configurator'),
        // 'license_text_long' => __('#creator# owns the copyright for #work#, but is not interested in exercising control.', 'cc-configurator'),
        // Short template
        // Supported template variables: #license#, #year#
        'license_text_short' => __('The copyright for this work is in the public domain because it has expired.', 'cc-configurator'),
        // 'license_text_short' => __('The copyright for this work was injected into the public domain for other reasons, such as failure to adhere to required formalities or conditions.', 'cc-configurator'),
        // 'license_text_short' => __('The copyright owner is not interested in exercising control.', 'cc-configurator'),
        // More information template
        // Supported template variables: #page#
        'extra_perms' => __('More information about the status of the copyright is available in our #page# section.', 'cc-configurator')
    ));
    // Finally we use the base generator to build and return the HTML content.
    // The base generator should be suitable for any type of license.
    return bccl_base_generator( $license_slug, $license_data, $post, $options, $minimal, $templates );
}
// Add the Public Domain statement to the array of available licenses.
function bccl_add_copyright_expired_statement( $licenses ) {
    $licenses['crexp'] = array(  // slug (unique for each license; think well before setting it; not wise to change it later)
        'url' => '',
        'name' => 'Public Domain due to expired copyright',   // Name of the license
        // 'name' => 'Public Domain due to failure to comply with the laws',
        // 'name' => 'Public Domain due to lack of owner interest',
        'name_short' => 'PD',
        'button_url' => '',
        'button_compact_url' => '',
        'generator_func' => 'bccl_copyright_expired_generator'
    );
    return $licenses;
}
add_filter( 'bccl_licenses', 'bccl_add_copyright_expired_statement' );

IMPORTANT NOTICE: Be advised that adding the country/jurisdiction in which the above statements have effect and/or adding more details about the reasons of the lack of copyright might be necessary in order to comply with your country's laws and copyright regulations.