Skip to content

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!

Important: Since Total 5.5 you can now create custom Cards via Theme Panel > Custom Cards using your favorite page builder (WPBakery, Gutenberg or Elementor). The guide below will show you how you can create custom cards using code.

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 always done by hooking into the “wpex_card_styles” filter which returns an array of card styles, but there are two ways of defining where the output of your card will be. You can either create a folder structure for your custom cards or define a template path for each custom card.

/**
 * Register custom card styles.
 *
 * @link https://total.wpexplorer.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;
} );

IMPORTANT: It is recommended to give your custom cards very unique names to prevent any conflicts in the theme. For example if you were to make a custom card named blog-11.php and then we add the same card in the future to the theme your's will override the theme's. If you are using a folder structure try and give them unique names as well to prevent any possible conflict. Prefixing the folder is a good way to avoid conflicts, for example mysite-blog would be a good name for some custom blog card styles.

Step 2: Create Your Custom Card Files

Now you have registered your custom cards and defined where the output will come from you need to create the design for the cards. This will be done by making use of the card API or general WordPress functions.

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.

You will probably want to check out the WPEX_Card class located at Total/framework/cards/class-wpex-card.php to see what parameters are allowed for each method. For example most modules have a link by default such as the thumbnail and title. You can set the link parameter to false to disable the link on the module. Other modules have unique parameters such as get_date which accepts a type parameter (published, modified or time_ago) as well as a format parameter for the output format.
Back To Top