Custom Cards API: Create Custom Cards via Child Theme

Total Cards are used to display post entries within grids and archives and while there are a many pre-build cards to choose from sometimes you may want to create a custom card design and luckily the WPEX_Card API makes it super easy!

Creating custom Card styles in your child theme is quite simple, below you will find how to register your card styles and how to actually code your own custom styles.

Step 1: Register Your Custom Cards

First thing you need to do is register your custom cards so that the theme knows they exist. Registering your cards is done by hooking into the “wpex_card_styles” like the example below:

/**
 * Register custom card styles.
 *
 * @link https://totalwptheme.com/docs/how-to-create-custom-theme-cards/
 */
add_filter( 'wpex_card_styles', function( $card_styles ) {
	$my_cards = [
		'my-card-2' => [
			'name'     => esc_html__( 'My Card 1', 'Total' ),
			'template' => get_stylesheet_directory() . '/my-cards/my-card-2.php',
			'group'    => esc_html__( 'My Cards', 'Total' ),
		],
		'my-card-2' => [
			'name'     => esc_html__( 'My Card 2', 'Total' ),
			'template' => get_stylesheet_directory() . '/my-cards/my-card-2.php',
			'group'    => esc_html__( 'My Cards', 'Total' ),
		],
	];
	return array_merge( $my_cards, $card_styles );
} );

Step 2: Create Your Custom Card Files

Now that you have registered your custom cards you will need to create your card templates. When creating your card output you can use the theme’s WPEX_Card API (accessible via the $this variable) or using any code you want.

Your Card template file supports standard PHP and HTML so you can literally add anything you want in your template.

Sample Card (based on Blog 22)

<?php
defined( 'ABSPATH' ) || exit;

$has_link = $this->has_link_wrap();

$html = '';

if ( $has_link ) {
	$html .= $this->get_link_open( [
		'class' => 'wpex-card-inner wpex-flex wpex-flex-col wpex-flex-grow wpex-overflow-hidden wpex-rounded-md wpex-border wpex-border-solid wpex-border-main wpex-surface-1 wpex-no-underline wpex-inherit-color',
		'attributes' => array(
			'aria-label' => get_the_title( $this->post_id ),
		),
	] );
} else {
	$html .= '<div class="wpex-card-inner wpex-flex wpex-flex-col wpex-flex-grow wpex-overflow-hidden wpex-rounded-md wpex-border wpex-border-solid wpex-border-main wpex-surface-1">';
}

	$html .= $this->get_media( [
		'link' => ! $has_link,
	] );

	$html .= '<div class="wpex-card-details wpex-flex wpex-flex-col wpex-flex-grow wpex-p-30 wpex-last-mb-0">';

		$html .= $this->get_title( [
			'class' => 'wpex-heading wpex-child-inherit-color wpex-text-xl',
			'link' => ! $has_link,
		] );

		$html .= $this->get_excerpt( [
			'class' => 'wpex-mt-15',
		] );

	$html .= '</div>';

if ( $has_link ) {
	$html .= $this->get_link_close();
} else {
	$html .= '</div>';
}

return $html;

As you can see, all cad methods reference $this which is is the card object of WPEX_Card type. You can find the class at Total/inc/lib/wpex-card.php.

Displaying Content

The Card API offers several methods for displaying content, all of which work in a similar way. However, you can also use core WordPress functions if you prefer. Since a custom card is simply a PHP file, you can include any PHP or HTML code you like within it. Just make sure to return your code from the card, rather than echoing it.

While passing arguments isn’t required, you’ll typically want to include a class parameter to apply your own custom styles. In the example above, we’ve used the theme’s CSS utility classes (those prefixed with wpex-) to handle the card’s design. This way you don’t need to target it with custom CSS.

WPEX_Class Methods

Below is a table with available class methods:

WPEX_Class Method Parameters

Below is a list of common parameters that can be used in any of the methods mentioned above:

Card Arguments

Whenever a card is displayed, it comes with a set of arguments that can be modified dynamically as needed. You can find the full details and options in the documentation here.