Consider Implementing a Custom Blocks Parser to Rewrite Internal Link URLs

[kellenmace]

Currently, the wpe_headless_content_replacement() function in wpe-headless/includes/replacement/callbacks.php handles rewriting internal link URLs so that they have the domain of the frontend app.

Because that relies on a the_content filter, it works for frontend apps that query the post's content. It does not, however, work for projects that use the WPGraphQL Gutenberg plugin and query for blocks.

We should consider including a custom blocks parser that performs the internal link URL string replacement, similar to this one: https://github.com/kellenmace/headless-block-parser/blob/main/headless-block-parser.php. Then internal links inside of Gutenberg blocks would be properly rewritten, as well.

[wjohnsto]

@apmatthews This is something we should be handling in the WP plugin.

[apmatthews]

@blakewilson @kellenmace What do you think about moving all URL rewrites to the front-end? 🤔

For Next.js in particular, we already need a parser that can transform internal links to Link components. It's up to the front-end developer to provide and use such a parser right now, but I could see this being a nice feature for Faust.js to provide.

If we did introduce a parser, it could also search any GraphQL query results for the NEXT_PUBLIC_WORDPRESS_URL and replace that value with the current site domain. A couple of advantages of this approach:

1. Enables support for multiple front-end domains that all want to use the same backend WP installation.
2. Lets us potentially explore rewriting more than just href attributes. This would help account for any Gutenberg content that is only saved in the block comment rather than in the block's saved HTML. It might also be useful for rewriting URLs stored in post meta, which is common for ACM or ACF users. Of course, there are plenty of implementation details to work out and it's not impossible to do this on the plugin side, but it seems like it could be easier to determine what should and what shouldn't be rewritten from the data consumer's perspective.

@kellenmace The server-side block parser you provided works great and I am still completely open to pulling that in. Just wanted to see if your approach would differ if we used the need to replace anchor tags with Link components as motivation to introduce some sort of parser in Faust.js.

[kellenmace]

@apmatthews Thanks for this. Some thoughts –

As you likely know, our WP Headless plugin currently assumes that the WordPress backend is being used for a single web client (rather than multiple) and requires the user to enter their Front-end site URL on its settings page. The WP backend has to know the frontend app URL for other reasons other than just URL rewrites, such as generating the password reset URL that gets emailed to the user when they request a password reset. So moving URL rewrites from PHP to JS wouldn't allow for multiple front-end domains in and of itself - we'd have to overhaul some other things to add support for that.

You mentioned rewriting URLs stored in metadata too. It seems like that could be done on the server using WP's get_{$meta_type}_metadata hook. That feels very clean & targeted to me. By contrast, in a frontend JS app, let's say we need to query for 5 different types of nodes in the GraphQL schema, and get 10 fields on each of them. Our JS app has no idea which of those fields' resolvers are pulling their data from post/user meta, so it seems like our app would have to run all String fields being requested through a string replace function just in case a field's value contains a URL that needs a rewrite. That's doable, but seems like an inelegant and heavy-handed solution, and like we're putting more work on the client than is necessary.

I like the idea that the JSON data that the WP backend serves up is already correct. I should be able to do this:

1. Install & activate WPGraphQL and WP Headless in my WP backend.
2. Set the Front-end site URL to the domain where my Faust.js frontend app lives.
3. Query the WPGraphQL schema from my web client, from my company's iOS and Android apps, from our desktop client, etc. and know that all URLs point to the correct pages of my Faust.js frontend app.

If we let the WordPress server continue to serve up the incorrect URLs and leave it to the client to rewrite them, then that work would need to be done separately and repeatedly in the web client, iOS client, Android client, desktop app client. etc.

My preferred approach is to have the WP backend serve up already correct, rewritten URLs, then use an HTML parser in the frontend Faust app to convert internal link anchor tags to Next.js Link components, as described in this blog post: https://developers.wpengine.com/blog/gutenberg-in-headless-wordpress-render-blocks-as-html

The approach I use in that blog post does the URL rewrites on the server, and also tacks on an extra data-internal-link="true" attribute. That makes it really easy to identify internal links using an HTML parser in the JS app & convert them to Link components. And that leaves the door open for us to "explore rewriting more than just href attributes", as you said.

What do you think? Am I overlooking any other details we should consider here?

Thanks! 👍

cc: @blakewilson