Magento WordPress Integration Layout XMLWordPress Integration

« Back to Magento WordPress Integration

On This Page:

Create a Custom Layout XML File

You can create custom layout files in the following location:

// Change YourVendor and YourTheme for the actual vendor and theme used on your site
app/design/frontend/YourVendor/YourTheme/FishPig_WordPress/layout

Layout Files Names

Here are a list of layout file names used by the module. Some of these layout file names are dynamic (ie. they change based on the content).

wordpress_default.xml

This is used by every page/request of your WordPress blog. It is therefore useful to make global changes to the blog, such as adding CSS files or adding global blocks.

wordpress_homepage_view.xml

This is used by the WordPress homepage. This is the page that lists all of your posts.

wordpress_post_view_default.xml

This is the base layout file for viewing a post for all post types. Changes added here are applied to ALL posts and not just post_type=post posts.

wordpress_{post_type}_view.xml

You can target specific post types using the wordpress_{post_type}_view.xml layout file. For example, to target the single view for the post type page, you would use the layout handle wordpress_page_view.xml.

For custom post types (ie. not post or page), you will need the Post Types & Taxonomies add-on module.

wordpress_{post_type}_view_{post_id}.xml

This allows you to target a specific post by ID. For example, wordpress_post_view_123.xml would be applied to a post with a post type of post and an ID of 123.

wordpress_{post_type}_view__parent_{parent_id}.xml

Targets a post with a specific parent. This allows you to apply layout updates to all child posts based on a specific parent.

wordpress_post_list.xml

Target all post list/archive pages. This includes the homepage (default post list), category pages, tag pages, archive pages and any other archive/post list page. You target specific post list/archive pages using the layout files below.

wordpress_{taxonomy}_view.xml

Targets term pages for a specific taxonomy. To target all category pages, use wordpress_category_view.xml. You can target all post_tag pages using wordpress_post_tag_view.xml

You can use this layout file to target custom taxonomies but you must have the Post Types & Taxonomies add-on module installed.

wordpress_{taxonomy}_view_{term_id}.xml

Target a specific term by it's ID. For example, you can target a category with the ID of 123 using wordpress_category_view_123.xml.

wordpress_{post_type}_list.xml

Target an archive page of a custom post type.

Change the Page Layout

In Magento 2, the page layout is the root template. The module comes configured to use 2columns-left layout, but this can easily be changed for 1column, 2columns-right, 3columns, empty or any custom page layout that you have setup.

To change the page layout, you need to create a custom layout XML file. Use the layout file names listed above to decide what you want to target the new page layout for and then use the XML listed below.

<?xml version="1.0"?>
<page layout="2columns-left" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
  <!--
  /*
   * Change the layout="2columns-left" above to your new page layout
   */
  -->
</page>

Change Block Templates (.phtml Files)

You can change the template of any block in Magento by finding the layout name used but the key templates you might want to change for WordPress Integration are the post list templates and single post view.

Select the correct layout handle from above and use the layout XML below to change the templates.

FishPig_WordPress::post/list.phtml

This template is used on all archive pages to list the posts. In this template, each post is displayed via a renderer (more on this below) but you could remove the renderer and just add all post list code in this template.

<?xml version="1.0"?>
<!--
/*
 * You should create custom-list.phtml at:
 * app/design/frontend/YourVendor/YourTheme/FishPig_WordPress/templates/post/custom-list.phtml
 * Copy the default post/list.phtml to get you started
 */
-->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"><body>
    <referenceBlock name="wp.postlist.wrapper" 
                    template="FishPig_WordPress::post/custom-list.phtml" />
  </body></page>

FishPig_WordPress::post/list/renderer/default.phtml

This template is used to display each post in an archive/post list. post/list.phtml is the wrapper template while post/list/renderer/default.phtml is the individual post template.

The module will automatically change the renderer template based on the post type using the format: FishPig_WordPress::post/list/renderer/{post_type}.phtml. If this custom template cannot be found then the default.phtml will be used.

To change this template manually via XML, use the following XML:

<?xml version="1.0"?>
<!--
/*
 * You should create custom-list.phtml at:
 * app/design/frontend/YourVendor/YourTheme/FishPig_WordPress/templates/post/list/renderer/custom.phtml
 * Copy the default post/list/renderer/default.phtml to get you started
 */
-->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"><body>
    <referenceBlock name="wp.post.list">
      <action method="setRendererTemplate">
        <argument name="template" xsi:type="string">FishPig_WordPress::post/list/renderer/custom.phtml</argument>
      </action>
    </referenceBlock>
  </body></page>

As an example, you could use the above XML to change the post renderer for a specific category by using it in wordpress_category_view_123.xml (where 123 is the category ID).

FishPig_WordPress::post/view.phtml

This is the template used to view the post. This is automatically changed on the post type of the current post so you can create a new template in your theme using the post type and it will be selected automatically.

The module checks for the FishPig_WordPress::{post_type}/view.phtml template. You can create this template at FishPig_WordPress/templates/{post_type}/view.phtml in your custom theme.

You can also change this template manually via XML:

<?xml version="1.0"?>
<!--
/*
 * You should create view-custom.phtml at:
 * app/design/frontend/YourVendor/YourTheme/FishPig_WordPress/templates/post/view-custom.phtml
 * Copy the default post/view.phtml to get you started
 */
-->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"><body>
    <referenceBlock name="wp.post.view" template="FishPig_WordPress::post/view-custom.phtml" />
  </body></page>