How to Create Custom Theme Cards

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.

function my_register_custom_card_styles( $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'] = array(
		'name'     => esc_html__( 'My Card 1', 'Total' ),
		'template' => get_stylesheet_directory() . '/my-cards/my-card.php',
	);

	return $card_styles;
}
add_filter( 'wpex_card_styles', 'my_register_custom_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: Portfolio 1
 *
 * @package Total WordPress Theme
 * @subpackage Cards
 * @version 5.0
 */

defined( 'ABSPATH' ) || exit;

$output = '';

// Media
$output .= $this->get_media( array(
	'class' => 'wpex-mb-15',
) );

// Details
$output .= '<div class="wpex-card-details wpex-flex wpex-flex-wrap wpex-justify-between">';

	// Title
	$output .= $this->get_title( array(
		'class' => 'wpex-heading wpex-uppercase wpex-font-bold',
	) );

	// Date
	$output .= $this->get_date( array(
		'type' => 'time_ago',
		'class' => 'wpex-text-gray-500 wpex-text-right',
	) );

$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
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
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.