Integrate your theme with HivePress

In this tutorial, we’ll show how to integrate a third-party theme with HivePress.

By default, HivePress should work fine with any theme, but if you want HivePress layouts to match your theme design and ensure 100% compatibility, then a few changes are required.

Declare HivePress support

If you activate a third-party theme with HivePress, it will show a notice that warns the site administrator about the possible incompatibility issues. To hide this notice and declare HivePress support explicitly, add this code to the theme’s functions.php file:

add_action(
	'after_setup_theme',
	function() {
		add_theme_support( 'hivepress' );
	}
);

Add header menu

HivePress has a few links and buttons that should be displayed in the site header, e.g. the login link and the Add Listing button. To display them, add the following code somewhere in the header.php theme file:

if ( function_exists( 'hivepress' ) ) {
	echo hivepress()->template->render_menu();
}

We recommend adding it next to the main menu. Then, check if these links and buttons are properly aligned, and also make sure that they look good on mobile.

Add page wrapper

The most common issue that may occur with a third-party theme is related to HivePress page width and alignment. If the HivePress page content is not wrapped properly, you can add a custom HTML wrapper using this code in the theme’s functions.php file:

add_filter(
	'hivepress/v1/blocks/page',
	function( $args ) {
		return hivepress()->helper->merge_arrays(
			$args,
			[
				'blocks' => [
					'before' => [
						'type'    => 'content',
						'content' => '<div class="my-custom-wrapper">',
						'_order'  => 1,
					],

					'after'  => [
						'type'    => 'content',
						'content' => '</div>',
						'_order'  => 1000,
					],
				],
			]
		);
	}
);

Alternatively, you can add a custom CSS class to the existing wrapper with this code:

add_filter(
	'hivepress/v1/blocks/page',
	function( $args ) {
		return hivepress()->helper->merge_arrays(
			$args,
			[
				'attributes' => [
					'class' => [ 'my-custom-wrapper' ],
				],
			]
		);
	}
);

Also, you can use CSS to adjust the HivePress page width and padding. For example, add this code to the theme’s style.css file and change the sample values:

.hp-page {
	max-width: 1234px;
	padding: 32px;
}

Customize styles

By default, HivePress styles are pretty basic, so it may be a good idea to style its layouts and elements to match your theme design better.

All CSS classes in HivePress have the hp- prefix to avoid conflicts with other theme and plugin styles. We use BEM notation for naming CSS classes, so they are very intuitive, e.g. the listing CSS class is .hp-listing, its title class is .hp-listing__title, its Price attribute class is .hp-listing__attribute--price and so on.

You can easily inspect HTML elements via the browser development tools to check their CSS classes and then add custom styles to the theme’s style.css file accordingly. We also recommend enabling all the available HivePress extensions (e.g. Favorites, Messages, Geolocation, Reviews) and style their layouts if required.

Customize templates

Customizing HivePress styles may be enough, but if the advanced layout changes are required for your theme, then you probably need to customize the HivePress templates.

Using template hooks

In HivePress, templates are defined as arrays of blocks. With blocks, it’s easy to re-use and customize specific layout parts without affecting the whole template.

You can customize HivePress templates by adding, changing or deleting blocks via the hivepress/v1/templates/{template_name} filter hook. Template names always follow the {entity}_{context}_{layout} pattern, so it’s really easy to find the related templates.

For example, the code snippet below changes the number of columns on the Listings page by overriding the columns parameter of the listings block in the listings_view_page template:

add_filter(
	'hivepress/v1/templates/listings_view_page',
	function( $template ) {
		return hivepress()->helper->merge_trees(
			$template,
			[
				'blocks' => [
					'listings' => [
						'columns' => 3,
					],
				],
			]
		);
	}
);

And this code snippet changes the description position on the listing page by overriding the _order parameter of the listing_description block in the listing_view_page template:

add_filter(
	'hivepress/v1/templates/listing_view_page',
	function( $template ) {
		return hivepress()->helper->merge_trees(
			$template,
			[
				'blocks' => [
					'listing_description' => [
						'_order' => 123,
					],
				],
			]
		);
	},
	1000
);

You can check more examples of customizing templates in our code snippet collection.

Using template overrides

While templates consist of blocks, there’s a block type that loads specific HTML files from the templates subdirectory of the HivePress plugin, referred to as "template parts". You can override any template parts by copying them to the theme directory.

It's good practice to avoid overriding template parts where possible, because they may be updated in HivePress, while the theme will still load the outdated copy.

First, create a hivepress subdirectory in your theme directory. Then, find the template part that you want to customize in the templates subdirectory of the HivePress plugin or any of its extensions, and copy this file to the theme’s hivepress subdirectory you’ve just created, preserving the relative file path.

File paths always follow the {entity}/{context}/{layout} pattern, so it’s easy to find the related template parts in the templates subdirectory of HivePress or its extensions.

Once you copy the template part, HivePress will load it instead of the default one, so you can customize its HTML content without changing the plugin files directly.

For example, if you want to customize the listing description, copy the listing-description.php file from the templates/listing/view/page HivePress subdirectory to the theme’s hivepress/listing/view/page subdirectory. Then, change its HTML content and check if the changes are reflected on the listing page.

Keep developing

Congratulations! You’ve just integrated your theme with HivePress. Even though there's a lot more to the HivePress development than what you’ve seen so far, you’re now familiar with integrating or even creating custom themes for HivePress.

If you have any questions about HivePress development, please check the available docs and feel free to join the HivePress developer community.