Shopware 6 – Handling admin errors on frontend

Shopware is an extensive platform. It is complex and offers multiple ways to implement different features. Let’s take a look at handling errors in Shopware 6, specifically errors in frontend of the admin panel. It is complicated how they work. You can use APIs to handle them. Some work out of the box. Others require knowledge of the complex Shopware ecosystem.

Fortunately, in this article, I will show a simple example of handling admin errors in Shopware 6. I will also explain some places where errors are handled out of the box to ease your development process.

Let’s start with a “custom product”

Shopware implemented some measures to make your life easier in developing plugins and themes. 

Let’s focus on the custom element that you are developing in your journey for the best shop on Shopware. Let us call it a “custom product”. 

In this element, we want to have a custom component and config. We will base this article on Shopware custom CMS element example and its basic configuration.

Shopware 6 handling admin errors: Out-the-box solutions

Let’s set a scenario. We want a border in our custom product. However, to make it appealing for users of the plugin, so we need it to have a configurable border radius and border width. Luckily for us, Shopware already has some tools that we can use. We can set the whole process in our “custom product element name”/index.js.

Next, in the file, we have an object with a few keys. The key relevant to this article is “defaultConfig”. Inside it, we can initialize our config values. These values will persist between files in this folder. You can take their values using “this.element.config.[your value name]”.

The most important thing in this object is the required property. While its value is set to true, Shopware will automatically check and validate it when the admin user wants to save without setting those values.

In most cases, it is enough and a simple solution to have more validation for important config values in your custom CMS element.

defaultConfig: {
    borderWidth: {
      source: 'static',
      value: '1px',
      required: true
    },
    borderRadius: {
      source: 'static',
      value: '10px',
      required: true
    },
  }

Error handling when admin user clicks save

Now, as we know how to handle simple cases, what about more complicated ones?

I will gladly demonstrate it with two components.

One is named “sw-product-detail-base” (which you can find in the Shopware vendor) and the other is “sw-product-detail”.

First, we developed a custom CMS product element with custom border properties. Now, let’s imagine we are adding functionality to the “sw-product-detail-base” component. We will override it, extend its functions, and save additional data.

Then, when we did everything correctly and with some backend help, we have the data saved in the database. We want to have an active button and a text input with our custom description. (“this.product.extensions” persists between the parent and the child so we will need it later to do a correct validation on saving).

Here’s a snippet of our extra data. It includes an example of how we can bind it with our extension variable:

customProducttActive: {
      get() {
        return this.product.extensions?.customProduct?.active ?? false;
      },


      set(value) {
        if (!this.product.extensions?.customProduct) {
          this.$set(
            this.product.extensions, 
            'customProduct',
            this.customProductRepository.create()
    );
        }


        this.$set(
          this.product.extensions?.customProduct, 
          'active', 
          value
        )
      },
    },


    customProductDescription: {
      get() {
        return this.product.extensions?.customProduct?.description ?? null;
      },


      set(value) {
        if (!this.product.extensions?.customProduct) {
          this.$set(
            this.product.extensions, 
            'customProduct', 
            this.customProductRepository.create()
          );
        }


        this.$set(this.product.extensions?.customProduct, 'description', value)
      },
    },

After checking the active checkbox and filling in description text, we can test it. The save button that is in the admin page is working. But we want to add validation. It should state that if we check the checkbox, we cannot save without also inputting data to a description.

An error message must appear and be short. Saving should be blocked until we validate the data. Unfortunately, there is not much we can do in this file. The save function is not present in “sw-product-detail-base”. As a child of “sw-product-detail”, its parent takes care of saving. This leaves us developers with the problem of how to handle validation. 

Override the parent

Fortunately, it’s possible to override the parent. To override it, we have to know the name of the function, in our case, it’s “onSave”. Then we can add our snippet to override it.

We have to remember that the override function from the Shopware “Component” object is essential. It allows us to access “this.$super(‘[function name]’).” This will help us with overriding save. It will also help us access its “old” save function. This will allow further updates of base function by the Shopware theme while still retaining our custom validation.

const { Component } = Shopware;


Component.override('sw-product-detail', {

In the Vue method object we will add “onSave” method. This method will be overridden. The “this.$super(‘onSave’);” will execute the Shopware version of “onSave” method.

“this.ourCustomValidation()” will return false if we have to abort saving. It will return true if everything is in order. The return statement is responsible for “finishing saving” by returning and new promise.

We mirrored its logic by observing Shopware inside the vendor directory in the “onSave” method. We only copied it here.

I would recommend checking by yourself how it is done in your Shopware version. It can change in newer versions.

onSave() {
  if (!this.ourCustomValidation()) {
    return new Promise((resolve) => {
      resolve();
    });
  }


  this.$super('onSave');
},

Validation

The validation method looks into our extensions to search for “customProduct extension”. If our active checkbox is set to false, validation will simply allow the whole process to go undisturbed. By extension, the save method of our overriding component will fire. 

If the active checkbox value is true, we want to remove the description from our saved object. We also want to check if the description exists. If it does not exist we will use this snippet:

this.createNotificationError({
  message: this.$tc('The description is empty'),
});

What it does is use the built-in Shopware functions to show the message under the save button. But that’s it. If we want to stop the saving process, we have to stop it by returning the promise as described above.

ourCustomValidation() {
  if (this.product?.extensions?.customProduct?.active) {
    const { description } = this.product?.extensions?.customProduct;


    // Check if description exists
    if (!description) {
      this.createNotificationError({
        message: this.$tc('The description is empty'),
      });


      return false;
    }
  }


  return true;
}

Summary

Here is all the knowledge on how to block saving in the “sw-product-detail” view in Shopware administration.

The important step of debugging is having your CMS element correctly set up. The second most important thing is to remember that the “Component” object from Shopware has multiple modes, not only override.

I recommend searching in Shopware vendor files for more examples. Knowing where the save function is and how it works is very important for a “Component” object.

Do not copy snippets from this article mindlessly. Try to understand as much as you can to check if our snippets are correct. 

Sometimes, the backend of your plugin might be at fault. Make sure to consult your backend developers if you encounter any problems with “this.product.extensions.” Sometimes a simple cache refresh will help. Other times, we need to run “bin/console cache:clear” or a plugin refresh command.

I hope this article was helpful, happy coding!