Overview

A simple markup language for composing content into a WordPress environment.

Simple Example'

Creates a page, sets it as home and creates a menu with a link to the it.

<page id='frontpage' >

    <title>Just another WordPress website</title>

    Write page content here.

</page>

<options>

    <page_on_front parser='export' link='frontpage' />
    <!-- 
    Note: A shorthand for the above would also be <page_on_front =frontpage />
    The Node reference for documentation
    -->

</options>

<menu location="primary" >

    <menuitem link='frontpage' />

</menu>

Getting started with Phat-Kitty

Initialising a project.

First you need to decide where to store your 'src' path (Your WML files and their dependencies), and your 'dist' path (The location where Phat-Kitty will save the resulting JavaScript compiled from your source files).

It is up to you how you would like to organise your project files. One approach is if you typically keep an 'assets' folder in the project root directory where store images and other assets relating to a website's design, then you could also set that as your src path so that the included WML files can directly source the included media in the same directory. Then you can just set your dist path to a folder within your WordPress theme which can be watched by BrowserSync. That way the browser can refresh automatically every time you edit your content, and the generated JavaScript will output a log to the browser's console detailing the last WML build process.

To start a Phat-Kitty project, run command: phat-kitty init <project>

If you want to use a specific workspace within a project then run this command instead: phat-kitty init <project> -p <workspace>

Follow the prompts to set your src and dist paths. For most other prompts, you can safely hit enter to apply the default settings with the possible exceptions of the following:

• It is unlikely you will run Phat-Kitty in production mode for a WML-only project. But just in case, it might be best to answer no when prompted if you want to clean the 'dist' directory before building for production. Otherwise Phat-Kitty may accidentally remove files from your theme that didn't originate from the src path.

• Type false to prevent Phat-Kitty from producing an manifest file if you have no need of a JSON representation of the output generated by Phat-Kitty.

Once a project has been initialised, open your src folder in an IDE like VS Code and create the entry js file; which would be index.js if you left the project entry configuration value as the default. Next, create your WML files with the file extension .wml. In most cases, you would only need one primary wml file which can then import subsequent content into its context; similar to how in scss you would typically have one style.scss file which would then import all your scss that have been categorised into multiple sub .scss files.

In order for Phat-Kitty to parse your WML, you will need to import your primary .wml files into your entry js. For most use cases you would only need to include the following in your script.js:

import './content.wml'; // Or whatever name you gave your file.

Compiling WML with Phat-Kitty

Once the project src files have been set up, it's time to start compiling your markup!

To run Phat-Kitty on your project, type in the terminal command: phat-kitty build <project> (or phat-kitty b <project>) and wait for it to finish. If no errors appeared, you should see your newly entered WordPress content appear within WP Admin, and the generated js file saved to your theme (if that is where you set the 'dist' path).

If you want to have Phat-Kitty watch for changes in your src directory and automatically rebuild on save then use the command phat-kitty build <project> --watch (or phat-kitty b <project> -w)

You can always use phat-kitty --help to see more options.

How WML Works

WML is designed to work as a programmatic interface for creating and managing WordPress content. Like most import plugins available for WordPress, WML is essentially XML representing the content to import into the target WordPress environment. In fact, internally, the WML interpreter just uses PHP's SimpleXML API for parsing the input markup; with special syntax first being compiled into valid XML before being parsed.

How WML works is that the interpreter will build up an internal state representing the input markup. It will then 'decorate' the target WordPress environment with the exported state. After this, the final state gets cached so that it can be referenced on subsequent builds.

This means on each rebuild, unmodified nodes can have their previously exported value restore from the cache and will therefore be ignored during the exporting process in order to avoid duplicating content. The remaining nodes in the cache that failed to be restored will be 'pruned' from the cached state; deleting its exported content from the target WordPress environment in the process.

With all this in mind. The process of compiling WML can be summarised as:

1. Building the internal state representing the content to be exported, with nodes that can be matched in the cache being restored with their previously exported value.
2. Expired nodes remaining in the cache that could not be restored will be deleted from the target WordPress environment.
3. The newly create state will then be inserted, while skipping cached nodes.
4. Finally cache the new state and print the build log.

IMPORTANT NOTE: The WML's data binding with the target WordPress environment is one-way. Which means as much as possible the interpreter remains unaware of the existing content set within WordPress and is only concerned about inserting and deleting the content from its own state.

Caveats!

Guides

• Adding Posts and Pages
• Uploading attachment media to WordPress
• Working with existing content in WordPress
• Context
• Evaluating Expressions

Working with ACF

Reference

• <Node>
• <A>
• <Alias>
• <Blog>
• <Category>
• <Construct>
• <Date>
• <Datetime>
• <Exec>
• <Export>
• <Field>
• <File>
• <Flush>
• <Frontpage>
• <Gallery>
• <Group>
• <Header>
• <Ignore>
• <Img>
• <Import>
• <Internal>
• <Layout>
• <Layouts>
• <Logo>
• <Loop>
• <Map>
• <Menu>
• <Menuitem>
• <Meta>
• <Mixin>
• <Optgroup>
• <Options>
• <Page>
• <Post>
• <Prop>
• <Repeater>
• <Role>
• <Row>
• <Select>
• <Set>
• <Splice>
• <Tag>
• <Template>
• <Term>
• <Theme>
• <Time>
• <Timestamp>
• <User>

Parsers

• alias
• exec
• export
• file
• flush
• group
• header_image
• import
• link
• loop
• lorem
• map
• markdown
• menu
• menuitem
• mixin
• noop
• options
• post
• prop
• raw
• reserved
• role
• set
• term
• theme_mod
• time
• to_array
• to_string
• user
• yaml