Page Generator

PHP

plugins/cap-page-generator/cap-page-generator.php

Plugin Name: Capitularia Page Generator Plugin URI: Description: Generate Wordpress pages for our TEI files.

Version: 0.1.1 Author: Marcello Perathoner Author URI: License: GPLv2 or later Text Domain: cap-page-generator Domain Path: /languages

Capitularia Page Generator plugin.

The Page Generator plugin helps managing the publication of manuscript pages. Whenever a new manuscript is transcribed and its file is put into the file repository, a new Wordpress page needs to be made for the manuscript to actually appear in Wordpress.

This plugin lets you choose among a configurable set of source directories. Then it displays a list of the TEI files in that directory and lets you create and manage the page for each file. Bulk actions allow you to manage the pages in batches.

The plugin can be configured to automatically put some text on newly created pages. Usually this text consists in one or more shortcodes for the Capitularia File Includer plugin. It is the File Includer plugin that actually puts the content onto the page.

Note that this plugin does nothing on the public pages (except displaying a button on the admin toolbar).

How do the TEI files get to the user?

A cron process on the API server converts all the TEI files into HTML files and stores them in the filesystem. See also: Makefile Overview.

The Capitularia File Includer plugin then includes those files from the filesystem when outputting a Wordpress page to the user.

constant NAME

‘Capitularia Page Generator’

The name of the plugin.

constant DOMAIN

‘cap-page-generator’

The Text Domain ofthe plugin.

constant OPTIONS

‘cap_page_gen_options’

The Wordpress ID of the settings (option) page.

constant DASHBOARD

‘cap_page_gen_dashboard’

The Wordpress ID of the dashboard page.

plugins/cap-page-generator/class-config.php

Capitularia Page Generator Configuration Class

class Config

Contains configuration parameters.

property sections

The configured sections and fields

Array of arrays of arrays: sections / fields / properties

foreach ($this->sections as $section) {
     $section_id      = $section[0];
     $fields          = $section[1];
     foreach ($fields as $field) {
         $field_id            = $field[0];
         $field_caption       = $field[1];
         $field_description   = $field[2];
         $validation_callback = $field[3];
     }
}
property options

(string[]|null) Array of options retrieved from database and cached.

__construct()

Constructor

init()

Set up the options

If we setup the options in the constructor it will be too early for translation to kick in.

Return type:

void

get_opt(section_id, field_id, default)

Get an option

Parameters:

  • section_id (string) – The section @see $this->sections

  • field_id (string) – The field (or option) name

  • default (string) – The default value

Returns:

The option

Return type:

string

get_opt_path(section_id, path_id)

Get a path

Parameters:

  • section_id (string) – The section @see $this->sections

  • path_id (string) – The path option name

Returns:

The path ending in ‘/’

Return type:

string

section_can(section_id, status)

Check if a certain page status is allowed in this section.

Parameters:

  • section_id (string) – The section id

  • status (string) – The status to check

Returns:

True if section can $status

Return type:

bool

plugins/cap-page-generator/class-dashboard-page.php

Capitularia Page Generator Dashboard Page

class Dashboard_Page

Implements the dashboard page.

The dashboard page controls the plugin.

You open the dashboard page by clicking on Dashboard | Capitularia Page Generator in the Wordpress admin page.

property pagination_args

(array) The standard pagination args.

__construct()

Constructor

display()

Output dashboard page.

Outputs bare jQuery-UI tabs. They get filled by AJAX. Also outputs messages we get thru AJAX.

Return type:

void

display_section(section, paged)

Output one section

Parameters:

  • section (array) – Section descriptor

  • paged (int) – The page to go to

Return type:

void

format_error_message(error_struct)

Format error message as HTML snippet.

These notices get inserted at the top of the dashboard page. The user can click on the cross icon to dismiss the notice.

Parameters:

  • error_struct (array) – The error struct

Returns:

The HTML-formatted message

Return type:

string

process_bulk_actions(action, section_id, filenames)

Handle bulk actions

Handles user actions performed on one or more files using the file checkboxes and the bulk actions dropdown menu.

See: \cceh\capitularia\page_generator\on_cap_action_file

Parameters:

  • action (string) – The action to perform

  • section_id (string) – The section id

  • filenames (array) – The filenames of the files to perform the action on

Returns:

Error messages formatted as HTML

Return type:

string

on_cap_action_file()

Ajax endpoint

Handles user actions performed on one file using the links inside a table row.

See: \cceh\capitularia\page_generator\process_bulk_actions()

Return type:

void

on_cap_load_section()

Ajax endpoint

Load a section (represented by a jquery tab) in response to the user clicking on a tab or using the table pager.

Return type:

void

send_json(section_id, error_struct)

Send the result of an Ajax action back to the user.

The reason we use JSON instead of just sending HTML is that we want to send both, HTML and success / error messages. A table update is sent as a JSON string of HTML table rows that simply replace the old table rows. We assume for now that the user dashboard changes only on successful operations.

Parameters:

  • section_id (string) – The section id

  • error_struct (array) – The error messages

Return type:

void

plugins/cap-page-generator/class-file-list-table.php

Capitularia Page Generator File List Table class.

class File_List_Table

The file list table on the dashboard page.

Lists all the files in a directory plus status information.

See: https://core.trac.wordpress.org/browser/tags/4.4/src/wp-admin/includes/class-wp-list-table.php WP_list_Table source code in Trac.

property status_to_notice_class

HTML classes for table rows.

Classes set according to current page status. To colorize our table rows in the canonical way we use the same classes as Wordpress admin notices.

property bulk_actions

Enum bulk actions

An associative array of bulk actions and relative captions for the action links and the drop-down menus above and below the table.

property statuses

Enum statuses of manuscripts

An associative array of statuses and relative captions. A manuscript can have a public page, a private page, or not have any page at all.

property section_id

The section id

property directory

The directory to scan

property paths

The scanned files

property xml_path

The URI path to the xml file.

__construct(section_id, directory, args)

Constructor.

See: \WP_List_Table::__construct() for more information on default arguments.

Parameters:

  • section_id (string) – The section id

  • directory (string) – The directory to scan

  • args (array) – An associative array of arguments.

get_table_classes()

Get a list of CSS classes for the list table table tag.

Overrides method in base class.

Returns:

List of CSS classes for the table tag.

Return type:

array

scandir_recursive(root, paths)

Recursively scan a directory.

Parameters:

  • root (string) – The root directory

  • paths (array) – Array of strings: the paths still to scan

Return type:

void

prepare_items()

Prepare the items to show in the table.

Overrides abstract method in base class.

Return type:

void

no_items()

Message to be displayed when there are no items

Overrides method in base class.

Returns:

The message

Return type:

string

get_bulk_actions()

Get the list of bulk actions.

Overrides method in base class.

Returns:

(option_name => option_title)

Return type:

array

get_columns()

Get a list of table columns.

Overrides abstract method in base class.

Returns:

(internal_name => HTML content)

Return type:

array

single_row(manuscript)

Generates content for a single row of the table

Parameters:

  • manuscript (object) – The current file

Return type:

void

column_cb(manuscript)

Generates contents of the _cb_ column.

Called by the base class.

Parameters:

  • manuscript (object) – The current file

Return type:

void

column_status(manuscript)

Generates contents of the _status_ column.

Called by the base class.

Parameters:

  • manuscript (object) – The current file

Return type:

void

column_slug(manuscript)

Generates contents of the _slug_ column.

Called by the base class.

Parameters:

  • manuscript (object) – The current file

Return type:

void

column_title(manuscript)

Generates contents of the _title_ column.

Called by the base class.

Parameters:

  • manuscript (object) – The current file

Return type:

void

handle_row_actions(manuscript, column_name, primary)

Generates and displays row action links.

These are the links that appear when hovering over the table row. Clicking on the link initiates an Ajax request that performs the action and automagically redraws the table.

Parameters:

  • manuscript (object) – File being acted upon.

  • column_name (string) – Current column name.

  • primary (string) – Primary column name.

Returns:

Row action output for links.

Return type:

string

plugins/cap-page-generator/class-manuscript.php

Capitularia Page Generator Manuscript class.

class Manuscript

Represents a manuscript file.

This class represents TEI manuscripts stored in a directory on disk. It also manages manuscripts in Wordpress.

N.B. The class name is somewhat a misnomer because it can also represent a Capitulary file.

property path

(string) The filesystem path to the manuscript file.

property section_id

(string) The section of the manuscript, eg. ‘mss’, ‘capit/ldf’, .

property xml_id

(string|null) The xml:id of the manuscript. Cached.

property title

(string|null) The title of the manuscript. Cached.

__construct(section_id, path)

Constructor

Parameters:

  • section_id (string) – The section id

  • path (string) – The full path to the manuscript file

Return type:

void

get_path()

Getter for $path

Returns:

The path

Return type:

string

get_section_id()

Getter for $section_id

Returns:

The section id

Return type:

string

get_filename()

Return the filename

Returns:

The filename and extension (without directories)

Return type:

string

get_slug()

Generate a slug (without path).

Returns:

The slug

Return type:

string

get_slug_with_path()

Generate a slug with path.

Returns:

The slug with path, eg. capit/ldf/slug

Return type:

string

Generate a HTML link that points to the page.

A link the user can click to get to the relative page.

Returns:

The link pointing to slug

Return type:

string

get_xml_id()

Get the xml:id of this manuscript.

Returns:

The xml:id.

Return type:

string

get_title()

Get the title of this manuscript.

Returns:

The title.

Return type:

string

get_page_id()

Get ID of page

Returns:

The page ID or false

Return type:

mixed

get_status()

Get the current status of a manuscript page.

Returns:

The current status

Return type:

string

parse_tei()

Extract the manuscript id and title.

Extracts the manuscript id and title from the TEI file. We need the id for the post metadata. We need the title for the file list table.

Also puts qTranslate-X tags into the title iff the title has an xml:lang attribute.

Return type:

void

delete_pages()

Delete all pages with our slug

Slugs must be unique for all children of one page, but the same slug may be used by more than one page provided each has a different parent page. Eg. /mss and /internal/mss both have the slug ‘mss’ but a different parent page, so we must account for that.

We also delete all pages that have the same slug with a hyphen and number appended. Eg. deleting the page /mss/my-slug would also delete the pages /mss/my-slug-1 and /mss/my-slug-42, but not the page /internal/mss/my-slug.

Returns:

Success or error messages

Return type:

array

create_page(status)

Create a page containing one or more shortcodes.

Build the content for the new page. Some pages are made of more than one transformation, eg. the transcription pages have a header, transcription and footer.

Parameters:

  • status (string) – Status to set on the newly created page.

Returns:

Success or error messages

Return type:

array

do_action(action)

Perform an action on the manuscript.

Actions: publish: create the page with publish status private: create the page with private status refresh: re-create the page with the same status as before delete: delete the page

Parameters:

  • action (string) – The action to perform with the manuscript.

Returns:

{ 0 => int error code: 0 = success, 1 = warning, 2 = error, 1 => string success or error message, 2 => array optionally more error messages }

Return type:

array

plugins/cap-page-generator/class-settings-page.php

Capitularia Page Generator Settings Page

class Settings_Page

Implements the settings (options) page.

Found in Wordpress admin under Settings | Capitularia Page Generator.

__construct()

Constructor

Add option fields so we can use the Wordpress function do_settings_fields() to output them. All field descriptions are stored in the Config class.

Also register _one_ POST parameter to be handled and validated by Wordpress.

display()

Output the Settings page.

Return type:

void

on_options_field(args)

Output an option field.

Output (echo) an option field with its description.

We want all user entries to be returned into PHP as one string[] called OPTIONS_PAGE_ID. This array will be passed by Wordpress to the validation function and stored in the database all in one row.

See: http://planetozh.com/blog/2009/05/handling-plugins-options-in-wordpress-28-with-register_setting/ Blog post: how to store all plugin options into one database row.

Parameters:

  • args (array) – The arguments registered with add_settings_field ()

Return type:

void

on_validate(options)

Validate options entered by user

We get all user entries back in one string[] so we can store them in one database row. This makes validation somewhat more difficult.

See: \cceh\capitularia\page_generator\on_options_field()

Parameters:

  • options (array) – Array of key, value: the options as entered on the form.

Returns:

Array containing the validated options

Return type:

array

plugins/cap-page-generator/functions.php

Capitularia Page Generator global functions.

ns(function_name)

Add current namespace

Parameters:

  • function_name (string) – The class or function name without namespace

Returns:

Name with namespace

Return type:

string

cap_get_parent_id(section_id)

Get ID of the parent page of a section

Returns the ID of the parent page of a section.

Parameters:

  • section_id (string) – The section id

Returns:

The parent page ID or false

Return type:

mixed

cap_get_status(page_id)

Get the current status of a page.

Parameters:

  • page_id (int) – The Wordpress page id

Returns:

The current status

Return type:

string

cap_get_section_page_status(section_id)

Get the current status of a section’s parent page.

We need to check this so as not to make public children of private pages.

Parameters:

  • section_id (string) – The section id

Returns:

The current status

Return type:

string

cap_make_path_relative_to(path, base)

Returns a path relative to base

Parameters:

  • path (string) – The path

  • base (string) – The base

Returns:

The path relative to base

Return type:

string

cap_sanitize_nothing(s)

Do nothing

Parameters:

  • s (string) – The string to do nothing with

Returns:

The same string

Return type:

string

cap_sanitize_caption(caption)

Sanitize a caption

Parameters:

  • caption (string) – The caption to sanitize

Returns:

The sanitized caption

Return type:

string

cap_sanitize_path(path)

Sanitize a path

Parameters:

  • path (string) – The path to sanitize

Returns:

The sanitized path

Return type:

string

cap_sanitize_path_list(path_list)

Sanitize a space-separated list of paths

Parameters:

  • path_list (string) – The space-separated list of paths to sanitize

Returns:

The space-separated list of sanitized paths

Return type:

string

cap_sanitize_key(key)

Sanitize a key

Parameters:

  • key (string) – The key to sanitize

Returns:

The sanitized key

Return type:

string

cap_sanitize_key_list(key_list)

Sanitize a space-separated list of keys

Parameters:

  • key_list (string) – The space-separated list of keys to sanitize

Returns:

The space-separated list of sanitized keys

Return type:

string

on_init()

Initialize the plugin.

Return type:

void

on_cap_action_file()

AJAX hook

Return type:

void

on_cap_load_section()

AJAX hook

Return type:

void

on_enqueue_scripts()

Enqueue the public pages scripts and styles

Return type:

void

on_query_vars(vars)

Register cap_page_gen as valid HTTP GET parameter

We use the cap_page_gen parameter to call the dashboard from the Page Generator button on the user’s tool bar on the public pages.

Parameters:

  • vars (string[]) – Already registered parameter names

Returns:

Augmented registered parameter names.

Return type:

string[]

on_admin_enqueue_scripts()

Enqueue the admin page scripts and styles

Return type:

void

on_admin_menu()

Add menu entries to the Wordpress admin menu.

Adds menu entries for the settings (options) and the dashboard pages to the Wordpress settings and dashboard admin page menus respectively.

Return type:

void

on_admin_bar_menu(wp_admin_bar)

Add a dashboard button to the Wordpress toolbar.

Parameters:

  • wp_admin_bar (WP_Admin_Bar) – The WP_Admin_Bar object

Return type:

void

Add a link to our settings page to the plugins admin dashboard.

Adds hack value.

Parameters:

  • links (array) – The old links

Returns:

The augmented links

Return type:

array

Javascript

plugins/cap-page-generator/src/js/admin.js

Some utility function for the Page Generator admin interface.

plugins/cap-page-generator/admin.deparam(s)

The inverse of the jQuery.param () function.

Arguments:

  • s (string()) – A string in the form “p=1&q=2”

Returns:

{ p : 1, q : 2 }

Return type:

Object

plugins/cap-page-generator/admin.add_ajax_action(data, action)

Add action parameters to AJAX request data.

Arguments:

  • data (Object()) – The AJAX request data.

  • action (Object()) – The AJAX action.

Returns:

The AJAX request data augmented.

Return type:

Object

plugins/cap-page-generator/admin.on_cap_action_file(event)

Perform an action on a TEI file. The user clicked somewhere inside the table row listing that file.

Arguments:

  • event (Event()) – The click event

plugins/cap-page-generator/admin.on_cap_load_section(event)

Perform an action on a tab. The user clicked on a tab. The tab contents must now be loaded.

Arguments:

  • event (Event()) – The click event

plugins/cap-page-generator/admin.make_cb_select_all(ev, ui)

Activate the ‘select all’ checkboxes on the tables. Check or uncheck all checkboxes when the user clicks on the “select all” checkbox. Stolen from wp-admin/js/common.js

Arguments:

  • ev (Event()) – (unused) The tab loaded event emited by jQuery-ui

  • ui (Element()) – The tab element

plugins/cap-page-generator/admin.get_url_parameter(name)

Get a parameter from the URL in the browser location bar.

Arguments:

  • name (string()) – The name of the parameter

Returns:

The value of the parameter or null

Return type:

string

plugins/cap-page-generator/admin.init_tabs()

Initialize the jQuery tab interface.