How To Develop an Entire WordPress Theme in Angular

If you’re like me you probably love Angular.

You use it every day in your professional activity and you think it’s (one of) the best frontend application frameworks out there right now.

If this is true, read on as I have something interesting to tell you today.

WordPress: The Good Things and the Bad Things

I love the backend of WordPress and the power of the Gutenberg editor and its blocks.

On the other side I don’t love PHP as mush as I do for other server-side programming languages (e.g. C#). I’m not so experienced in PHP but I’ve always thought that the WordPress theme structure is a little nightmare to understand and to master.
I really think that the way WordPress wants you to structure a theme is over-complicated and can very easily bring you to bad design practices.

NgWP Theme Kit: The Birth of a New Angular Library

Wouldn’t it be great if we could implement a WordPress theme just by developing an Angular application?

Maybe we could use a library/tool/whatever that when we build the application applies the required transformations and produces an output package that satisfies the WordPress theme structure, but at the same time uses your Angular application as the theme frontend?

Following these thoughts I decided to develop my own solution to satisfy this requirement. And this is the story behind the birth of the NgWP Theme Kit Angular library that I’ve developed and is currently available as GitHub repository (if you want to view the code) and as NPM package (if you want to use it).

Before we continue, I’d like to throw a big disclaimer on the table: be warned that this library is just born and is still under development. It’s not 100% documented, it’s not 100% robust and probably won’t satisfy every use case. Please think carefully before using it for production scenarios — generally I’d advise not to do it.

Using the Library

Installation & Module Import

The first thing you need to do is to install the library in your Angular application:

npm i ngwp-theme-kit

Now you must import the NgwpThemeKitModule in your main module (usually app.module.ts):

...

import { NgwpThemeKitModule } from 'ngwp-theme-kit';

...

@NgModule({
  ...
  imports: [
    ...

    NgwpThemeKitModule

    ...
  ],
  ...
})

Adding a themeconfig.json Configuration File

This is the configuration file that the custom build tool will use to generate the WordPress theme.

Here you specify some key information about your theme (such as its name, author and a description) along with supported theme features (e.g. menus) and the customizer options.

For example, here is the content of the themeconfig.json of the sample application that you can find in the GitHub repository of the library (called Demo Theme).

{
  "name": "Demo Theme",
  "description": "A WordPress template developed with Angular frontend",
  "author": "Piero De Tomi",
  "themeFeatures": [
    "menus"
  ],
  "menus": [{
    "location": "header-menu",
    "description": "Header",
    "initialName": "Header Menu",
    "initialEntries": [ "Home", "Blog", "About Us", "Privacy" ],
    "onlyRegisterLocation": false
  },{
    "location": "footer-menu",
    "description": "Footer",
    "initialName": "Footer Menu",
    "initialEntries": [ "Footer Item 1", "Footer Item 2", "Footer Item 3", "Footer Item 4" ],
    "onlyRegisterLocation": false
  },{
    "location": "sidebar-menu",
    "description": "Sidebar Menu",
    "onlyRegisterLocation": true
  }],
  "sections": [{
    "id": "main",
    "name": "Main Config",
    "description": "Main configuration parameters",
    "settings": [{
      "id": "title",
      "label": "Title",
      "description": "The title of this blog",
      "defaultValue": null,
      "controlType": "text"
    },{
      "id": "author",
      "label": "Author",
      "description": "The author of this blog",
      "defaultValue": null,
      "controlType": "text"
    },{
      "id": "logo",
      "label": "Logo",
      "description": "The website logo",
      "defaultValue": null,
      "controlType": "image"
    }]
  }]
}

Updating the build Script in package.json

In order to “make the magic happen”, you need to modify the build script in your package.json file:

{
  ...

  "scripts": {
    ...

    "build": "ng build && \"./node_modules/ngwp-theme-kit/bin/NgWP.ThemeBuilder.exe\" {{dist-path}} {{path-to-themeconfig.json}}",
    
    ...
  }

  ...
}

In the above script you’ll have to replace:

• The {{dist-path}} token with your actual application’s dist path (usually dist/<application name>)
• The {{path-to-themeconfig.json}} token with the actual file path of your themeconfig.json configuration file

This script will build the application and run the custom tool (a .NET console application) that will transform the source files and will package the WordPress theme ready to be installed into your WordPress site.

Sample Usage #1: Getting the Last 10 Blog Posts

The NgWP Theme Kit library exports a series of services that allow you to access the CMS information, such as blog posts, categories, media and so on.

One of these services is the PostService service class: using this service you’ll be able to read blog posts.

For example, to read the last 10 blog posts you can write the following code:

export class SampleComponent implements OnInit {
  public posts: IPost[] = [];

  constructor(private _postService: PostService) { }

  ngOnInit(): void {
    this._postService
      .get(1, 10)
      .subscribe((posts) => {
        this.posts = posts;
      });
  }
}

Easy, right? Let’s see one more use case.

Sample Usage #2: Reading a Custom Theme Setting

Remember that in the themeconfig.json file you can specify custom theme sections and settings?

This will actually show the specified sections inside the WordPress Theme Customizer and you’ll be able to edit these values there.

You’ll also be able to read these values using the ThemeSettingsService service class, with a code like this:

...
constructor(private _themeSettingsService: ThemeSettingsService) { }
...
this._themeSettingsService
   .get<string>('title')
   .subscribe((title) => {
      this.title = title;
   });
this._themeSettingsService
   .getImage('logo')
   .subscribe((logo) => {
      this.logo = logo;
   });

Other Code Samples

You can find some more example usages on the Demo Theme application inside the GitHub repository of the library.

Building & Packaging Your Theme

To build and package your theme, simply execute the modified build script that you previously added to the package.json file:

npm run build

At the end of the script execution, you’ll find your theme files under the dist path of your application (depends on your configuration, but usually it’s dist/<application-name>).

Copy the folder you find inside the dist path into your WordPress theme’s folder, go to the “Theme” section in the admin panel of your WordPress website, activate your theme and you’re ready to go.

BONUS: Changing the Theme’s Thumbnail

The package you’ll build will ship with a default theme thumbnail (the screenshot.png file).

If you want to change the thumbnail of your theme, you’ll have to replace this image with your own.

Conclusion

That’s it for today’s article. I hope you find this library interesting and I’m sure we’ll do great things with it!