How to Create Custom Theme Cards Using The API

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 ) {

	/*
	 * Register new "my-card" card style.
	 *
	 * Simply add a file to your child theme anywhere you want with any name
	 * then you define the location of your card via the template parameter.
	 */
	$card_styles['my-card'] = [
		'name'     => esc_html__( 'My Card 1', 'Total' ),
		'template' => get_stylesheet_directory() . '/my-cards/my-card.php',
	];

	return $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. This is a very simple card output example:

<?php
/**
 * Card: Blog 7.
 */

defined( 'ABSPATH' ) || exit;

$output = '';

// Add wrapper around the card with flex styles
// This is to allow the last element of the card to "stick" to the bottom via wpex-mt-auto (margin top auto).
$output .= '<div class="wpex-card-inner wpex-flex wpex-flex-col wpex-flex-grow wpex-bg-white wpex-border wpex-border-solid wpex-border-main">';

	// Display the post media.
	$output .= $this->get_media();

	// Open wrapper so we can group certain elements and give them some padding.
	$output .= '<div class="wpex-card-details wpex-m-25 wpex-last-mb-0">';

		// Display the post primary term/category.
		$output .= $this->get_primary_term( array(
			'class' => 'wpex-font-semibold wpex-leading-normal wpex-mb-15',
			'term_class' => 'wpex-inline-block wpex-bg-accent wpex-text-white wpex-hover-bg-accent_alt wpex-no-underline wpex-px-10 wpex-py-5 wpex-text-xs',
		) );

		// Display the post title.
		$output .= $this->get_title( array(
			'class' => 'wpex-heading wpex-text-xl wpex-font-bold wpex-my-15',
			'link_class' => 'wpex-inherit-color-important',
		) );

		// Display the post excerpt.
		$output .= $this->get_excerpt( array(
			'class' => 'wpex-text-gray-600 wpex-my-15',
		) );

	$output .= '</div>';

	// Card footer wrapper, not really necessary, but we add it to make it easier for child theme edits.
	$output .= '<div class="wpex-card-footer wpex-mt-auto wpex-mx-25 wpex-mb-25">';

		// Display the post published date.
		$output .= $this->get_date( array(
			'icon' => 'ticon ticon-clock-o wpex-mr-5',
		) );

	$output .= '</div>';

$output .= '</div>';

return $output;

As you can see the functions use in the card reference "$this" which is is the card object of WPEX_Card type. You can find the WPEX_Card class under Total/framework/cards/class-wpex-card.php so you can see all methods available (methods also listed below).

Displaying Content:

The Card API has various methods you can use to display content and they all function in pretty much the same way, however, you can use core WordPress functions instead if you prefer. As you can see above we have 3 elements displayed media, title, date all of these use the API methods and pass on a list of arguments.

You don't ever have to pass on any arguments but you will most likely want to pass on a class parameter with your custom classes to give it the design you want. In the example above we are using the theme's CSS utility classes for the design which are the classes prefixed with wpex-.

Available card class methods:

• get_element (this can be used to display anything just pass on a 'content' parameter with the output you want)
• get_media
• get_thumbnail
• get_video
• get_audio
• get_icon
• get_title
• get_date
• get_time
• get_author
• get_excerpt
• get_more_link
• get_terms_list
• get_primary_term
• get_number
• get_star_rating
• get_custom_field (key parameter required to let it know your custom field name)

Method Parameters:

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

Parameter	Type	Description
name	string	if given a name will be added to the containing div as wpex-card-{name}
class	string	custom classes for the element
content	string	the content to display in the element (used for the get_element method0)
link	bool/string	adds a link around the element, if you set a custom url it will use that instead
link_class	string	custom link class
link_rel	string	custom link rel
link_target	string	custom link target
sanitize_content	bool	whether to sanitize the output or not passes through wp_kses_post
html_tag	string	HTML tag for your element
before	string	insert extra content before your element
after	string	insert content after your element
icon	string	icon classname to add before, example: "ticon ticon-bolt"
prefix	string	extra content added added before the element content inside element div
suffix	string	extra content added added after the element content inside element div
css	string	inline CSS example: color:white;background:red;
data	string	custom data attributes to attach to the element div
overlay	string	theme overlay style name to add to the element for images

Card Arguments

Whenever a card is displayed it has various arguments assigned to them which can also be modified on the fly. Please refer to the docs here.