Saving Settings for a Custom WordPress Block in the Block Editor

We’ve accomplished a bunch of stuff in this series! We created a custom WordPress block that fetches data from an external API and renders it on the front end. Then we took that work and extended it so the data also renders directly in the WordPress block editor. After that, we created a settings UI for the block using components from the WordPress InspectorControls package.

There’s one last bit for us to cover and that’s saving the settings options. If we recall from the last article, we’re technically able to “save” our selections in the block settings UI, but those aren’t actually stored anywhere. If we make a few selections, save them, then return to the post, the settings are completely reset.

Let’s close the loop and save those settings so they persist the next time we edit a post that contains our custom block!

Saving settings attributes

We’re working with an API that provides us with soccer football team ranking and we’re using it to fetch for displaying rankings based on country, league, and season. We can create new attributes for each of those like this:

// index.js

attributes: {
  data: {
    type: "object",
  },
  settings: {
    type: "object",
    default: {
      country: {
        type: "string",
      },
      league: {
        type: "string",
      },
      season: {
        type: "string",
      },
    },
  },
},

Next, we need to set the attributes from LeagueSettings.js. Whenever a ComboboxControl is updated in our settings UI, we need to set the attributes using the setAttributes() method. This was more straightfoward when we were only working with one data endpoint. But now that we have multiple inputs, it’s a little more involved.

This is how I am going to organize it. I am going to create a new object in LeagueSettings.js that follows the structure of the settings attributes and their values.

// LeagueSettings.js

let localSettings = {
  country: attributes.settings.country,
  league: attributes.settings.league,
  season: attributes.settings.season,
};

I am also going to change the initial state variables from null to the respective settings variables.

// LeagueSettings.js

const [country, setCountry] = useState(attributes.settings.country);
const [league, setLeague] = useState(attributes.settings.league);
const [season, setSeason] = useState(attributes.settings.season);

In each of the handle______Change(), I am going to create a setLocalAttributes() that has an argument that clones and overwrites the previous localSettings object with the new country, league, and season values. This is done using the help of the spread operator.

// LeagueSettings.js

function handleCountryChange(value) {
  // Initial code
  setLocalAttributes({ ...localSettings, country: value });
  // Rest of the code
}

function handleLeagueChange(value) {
  // Initial code
  setLocalAttributes({ ...localSettings, league: value });
  // Rest of the code
}

function handleSeasonChange(value) {
  // Initial code
  setLocalAttributes({ ...localSettings, season: value });
  // Rest of the code
}

We can define the setLocalAttributes() like this:

// LeagueSettings.js

function setLocalAttributes(value) {
  let newSettings = Object.assign(localSettings, value);
  localSettings = { ...newSettings };
  setAttributes({ settings: localSettings });
}

So, we’re using Object.assign() to merge the two objects. Then we can clone the newSettings object back to localSettings because we also need to account for each settings attribute when there a new selection is made and a change occurs.

Finally, we can use the setAttributes() as we do normally to set the final object. You can confirm if the above attributes are changing by updating the selections in the UI.

Another way to confirm is to do a console.log() in DevTools to find the attributes.

Look closer at that screenshot. The values are stored in attributes.settings. We are able to see it happen live because React re-renders every time we make a change in the settings, thanks to the useState() hook.

Displaying the values in the blocks settings UI

It isn’t very useful to store the setting values in the control options themselves since each one is dependent on the other setting value (e.g. rankings by league depends on which season is selected). But it is very useful in situations where the settings values are static and where settings are independent of each other.

Without making the current settings complicated, we can create another section inside the settings panel that shows the current attributes. You can choose your way to display the settings values but I am going to import a Tip component from the @wordpress/components package:

// LeagueSettings.js
import { Tip } from "@wordpress/components";

While I’m here, I am going to do a conditional check for the values before displaying them inside the Tip component:

<Tip>
  {country && league && season && (
    <>
      <h2>Current Settings: </h2>
      <div className="current-settings">
        <div className="country">
          Country: {attributes.settings.country}
        </div>
        <div className="league">
          League: {attributes.settings.league}
        </div>
        <div className="season">
          Season: {attributes.settings.season}
        </div>
      </div>
    </>
  )}
</Tip>

Here’s how that winds up working in the block editor:

API data is more powerful when live data can be shown without having to manually update them each and every time. We will look into that in the next installment of this series.

Saving Settings for a Custom WordPress Block in the Block Editor originally published on CSS-Tricks, which is part of the DigitalOcean family. You should get the newsletter.