/ 
Mojolicious-Plugin-Wordpress-0.03
River stage zero No dependents
/ Mojolicious::Plugin::Wordpress

NAME

Mojolicious::Plugin::Wordpress - Use Wordpress as a headless CMS

SYNOPSIS

use Mojolicious::Lite;
plugin wordpress => {base_url => "https://wordpress.example.com/wp-json"};

get "/page/:slug" => sub {
  my $c = shift->render_later;
  $c->wp->get_page_p($c->stash("slug"))->then(sub {
    my $page = shift;
    $c->render(json => $page);
  });
};

DESCRIPTION

Mojolicious::Plugin::Wordpress is a plugin for getting data using the Wordpress JSON API.

This plugin is currently EXPERIMENTAL. Let me know if you have any feedback at https://github.com/jhthorsen/mojolicious-plugin-wordpress/issues.

HELPERS

get_post_p

my $promise = $c->wp->get_post_p;
my $promise = $c->wp->get_post_p($slug);
my $promise = $c->wp->get_post_p(\%query);

This helper will be available, dependent on what you set "post_types" to. It will return a Mojo::Promise that will get a $post hash-ref or undef in the fullfillment callback. The $post hash-ref will be exactly what was returned through the API from Wordpress, or whatever the "post_processor" has changed it to.

get_posts_p

my $promise = $c->wp->get_posts_p;
my $promise = $c->wp->get_posts_p(\%query);
my $promise = $c->wp->get_posts_p({all => 1, post_processor => sub { ... }});

This helper will be available, dependent on what you set "post_types" to. It will return a Mojo::Promise that will get an array-ref of $post hash refs in the fullfillment callback. A $post hash-ref will be exactly what was returned through the API from Wordpress, or whatever the "post_processor" has changed it to.

meta_from

my $meta = $c->wp->meta_from(\%post);

This helper will extract meta information from the Wordpress post and return a %hash that looks something like this:

{
  wp_canonical             => "",
  wp_title                 => "",
  wp_metadesc              => "",
  wp_description           => "",
  wp_opengraph_title       => "",
  wp_opengraph_description => "",
  wp_twitter_title         => "",
  wp_twitter_description   => "",
  ...
}

Note that some keys might be missing or some keys might be added, depending on how the Wordpress server has been set up.

Suggested Wordpress plugins: https://wordpress.org/plugins/wordpress-seo/ and https://github.com/jhthorsen/wp-api-yoast-meta.

rewrite_content

$dom = $c->wp->rewrite_content($post->{content}{rendered});

This helper will rewrite a piece of HTML from Wordpress with the following rules:

  • Asset URL

    Will replace "src" and "srcset" on images with an URL to the local application, if "base_assets_url" is set in config or a "wp.assets" route could be found.

  • Images

    All "height" and "width" attributes will be removed from "img" tags.

Note that more rules might be added in the future.

ATTRIBUTES

base_url

my $url = $wp->base_url;
my $wp  = $wp->base_url("https://wordpress.example.com/wp-json");

Holds the base URL to the Wordpress server API, including "/wp-json".

meta_replacer

my $cb = $wp->meta_replacer;
my $wp = $wp->meta_replacer(sub { my ($c, $str) = @_ });

A callback used to search and replace meta data when calling "meta_from". The default callback will search and replace all occurances of "%%some_key%%" with wp_$some_key from "stash" in Mojolicious::Controller.

post_processor

my $cb = $wp->post_processor;
my $wp = $wp->post_processor(sub { my ($c, $post) = @_ });

A code block that can be used to post process the JSON response from Wordpress.

ua

my $ua = $wp->ua;
my $wp = $wp->ua(Mojo::UserAgent->new);

Holds a Mojo::UserAgent object that is used to get data from Wordpress.

yoast_meta_key

my $str = $wp->yaost_meta_key;
my $wp  = $wp->yaost_meta_key("yoast");

The key in the post JSON response that holds Yoast meta information.

This information is not enabled by default. To enable it through the API, you can add this plugin: https://github.com/jhthorsen/wp-api-yoast-meta.

METHODS

register

$wp->register($app, \%config);
$app->plugin(wordpress => \%config);

Used to register this plugin. %config can have:

  • base_assets_url

    If base_assets_url is set, then a new route will be added to your $app, that will proxy GET requests to your Wordpress backend. This can be useful, if you want to mask/hide Wordpress URLs and rather let everything go through your Mojolicious application.

    Example value:

    {base_assets_url => 'https://wordpress.com/wp-content/uploads'}

    The path added will either be defined by the base_assets_route config variable or default to "/uploads/*proxy_path", and the route will be named "wp.assets".

  • base_url

    See "base_url".

  • post_processor

    See "post_processor".

  • post_types

    A list of post types available in the CMS. Defaults to:

    ["pages", "posts"]

    This list will generate helpers to fetch data from Wordpress. Example default helpers are:

    my $p = $c->wp->get_page_p(...);
my $p = $c->wp->get_pages_p(...);
my $p = $c->wp->get_post_p(...);
my $p = $c->wp->get_posts_p(...);

    See "get_post_p" and "get_posts_p" for more information.

    Suggested Wordpress plugin: https://wordpress.org/plugins/custom-post-type-maker/

  • prefix

    The prefix for the helpers. Defaults to "wp".

  • ua

    See "ua".

  • yoast_meta_key

    See "yoast_meta_key".

AUTHOR

Jan Henning Thorsen

COPYRIGHT AND LICENSE

Copyright (C), Jan Henning Thorsen.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.