API Documentation for Publizjr 2 - ΩJr. Publizjr Creates Web Pages

Publizjr 2 is O.O., requiring PHP5 or newer

Whereas Publizjr 1 was built without much object orientation, Publizjr 2 embraces the benefits of an o.o.-centric design. Unfortunately this means we have to document what it does and how PHP programmers can use it. You have come to the right place.

Migrate by Hand

Publizjr 2 is so young that we have yet to create and automated migration from Publizjr 1 to 2. We see several challenges which make automation difficult. Thus unfortunately, you will have to migrate your sites by hand. For your first template this may take several hours. Once you understand the migration, you should be able to migrate each section within 30 minutes.

Publizjr 2 Object Model

1. Public interface: interface PublizjrPageInterface, in the file “PublizjrPage.interface.php”.
2. Abstraction Class: abstract class PublizjrPageAbstract, in the file “PublizjrPage.abstract.php”.
3. Basic Publizjr 2 Generator Template: class PublizjrPage extends PublizjrPageAbstract, in the file “PublizjrPage.class.php”.
4. Multilingual Publizjr 2 Generator Template: final class PublizjrMultilanguagePage extends PublizjrPage, in the file “PublizjrMultilanguagePage.class.php”.

Required File Inclusions

The abstract class PublizjrPageAbstract requires inclusion of file “PublizjrPage.interface.php” and file “bb2html.php”.

The class PublizjrPage requires inclusion of file “PublizjrPage.abstract.php”.

The final class PublizjrMultilanguagePage requires inclusion of file “PublizjrPage.php” and file “detectlang.php”.

The file “bb2html.php” provides functionality for a simple recoding of BBCode into HTML. The file “detectlang.php” provides functionality which recognises the visitors’ desired language by reading the language preference setting in their web browser. (We might in the future make these part of the Publizjr package.)

The class, abstract class, and interface files as well as the required includes MUST live in the same folder. This MAY be a different folder than the web site root, and usually is a different folder than where the Publizjr template files live.

Publizjr 2 Constructor

called as:

$page = new PublizjrPage( $publizjrParams );

where $publizjrParams is an associative array holding the parameters like this:

$publizjrParams = array(

  'defaultPageID' => 'index',

  'uriCanonicalSection' => 'https://www.omegajunior.net/code/publizjr/', 

  'filePathToTranslations' => './translations',

  'filenameCallToAction' => 'callToAction-publizjr',

  'filenameCallToActionCaption' => 'callToActionCaption-publizjr', 

  'filenameDefaultVCardTranslation' => 'vCard-aev-zjr',

  'strDefaultPageDescription' => 'ΩJr. Publizjr - Creates Web Pages'

);

For the multilingual page generator the constructor is the same except for the class name.

Parameter Explanation

String defaultPageID:

Tells Publizjr which page folder to show in case no page ID was provided. Usually “index”. Change value only if your home page folder is not named “index”.

String uriCanonicalSection:

Tells Publizjr which web address to use as the canonical base address for a generated page. Always change this to the base address of where you intend the generated pages to live. Canonical web addresses are used by Google and other search engines to have one single web address for a web page, in case it can be reached via multiple addresses.

String filePathToTranslations:

Tells Publizjr where to find its translations folder. This is a file path (not a web address). Change this according to the name of your translations folder (which is “translations” by default) and its location relative to the current location of the Publizjr generator template.

String filenameCallToAction

Tells Publizjr which translation file to read when displaying the text of a call to action. See the method addCallToAction(), below.

String filenameCallToActionCaption

Tells Publizjr which translation file to read when displaying the title of a call to action. See the method addCallToAction(), below.

String filenameDefaultVCardTranslation

Tells Publizjr which translation file to read when displaying this section’s author information (vCard). Is overruled by a page’s own vcard file, if available. See the function addVCard(), below.

String strDefaultPageDescription

Tells Publizjr which description to use for the generated web page, in case the page author failed to provide one. In the default templates, the same information is reused as the og:site_name meta, and as the suffix for the title and h1 elements.

Publizjr 2 Class Properties

All are Read-Only! Listed alphabetically, first the pseudo-constants, then the rest:

protected $CANONICAL_SECTION_URI = '';

String: The web address to use as the canonical base address for a generated page. Set by the class constructor (see above).

protected $CALL_TO_ACTION_CAPTION_TRANSLATION_FILE = "callToActionCaption";

String: Which translation file to read when displaying the title of a call to action. Set by the class constructor (see above).

protected $CALL_TO_ACTION_TRANSLATION_FILE = "callToAction";

String: Which translation file to read when displaying the text of a call to action. Set by the class constructor (see above).

protected $DEFAULT_PAGE_DESCRIPTION = '';

String: Which description to use for the generated web page, in case the page author failed to provide one. In the default templates, the same information is reused as the og:site_name meta, and as the suffix for the title and h1 elements. Set by the class constructor (see above).

protected $DEFAULT_PAGE_ID = 'index';

String: Which page folder to show in case no page ID was provided. Usually “index”. Set by the class constructor (see above).

protected $DEFAULT_VCARD_TRANSLATION_FILE = 'vcard';

String: Which translation file to read when displaying this section’s author information (vCard). Is overruled by a page’s own vcard file, if available. Set by the class constructor (see above).

protected $FILE_PATH_TO_TRANSLATIONS = "./s/translations";

String: Where Publizjr finds its translations folder. This is a file path (not a web address). Set by the class constructor (see above).

protected $dateLastModified = '';

String: Date and time according to the web server, at which the current page's parent folder was modified last. Assigned automatically during construct.

protected $description = '';

String: Contents of the (localized) page file named “description”. Used in meta tags to surmise the page content to search engines and social media. Assigned automatically during construct.

protected $exists = false;

Boolean: Whether or not the requested web address resolves to an existing, qualifying page folder. (Folder must exist, must be a folder, and must contain a file named “body”.) Assigned automatically during construct.

protected $id = 'index';

String: identifier of the requested web page. Read from the querystring in the web address. In the multi-language-aware Publizjr class, this $id is prefixed with the requested language, if supported. Assigned automatically during construct.

protected $langReq = 'en';

String: identifier of the requested language, to localise the web page and its parts. By default, this is 'en' for English. The multilingual Publizjr template automatically detects the language preferred by the user’s web browser (HTTP_ACCEPT_LANGUAGE). If requested languages do not match supplied languages, a default language (usually 'en' for English) is returned. Assigned automatically during construct.

protected $ogImagePath = '';

String: The absolute web address to an image that is suitable for display when sharing the current page on Facebook and other Open Graph media. Read from a file named “ogImage” in the (localised) page folder, or, if missing, from its parent folder. Defaults to a branded image of the ΩJr.Net. Assigned automatically during construct.

protected $originalPageID = "index";

String: original identifier of the requested web page. Read from the querystring in the web address. When the multi-language-aware Publizjr class prefixes the $id with the requested language, if supported, this $originalPageID continues to reflect the identifier requested by the visitor. (This allowed us to write a smaller localisation-aware class.) Assigned automatically during construct.

protected $pinImagePath = '';

String: The absolute web address to an image that is suitable for display when sharing the current page on Pinterest. Read from a file named “pinImage” in the (localised) page folder, or, if missing, from its parent folder. Defaults to a branded image of the ΩJr.Net. Assigned automatically during construct.

protected $title = '';

String: Contents of the (localized) page file named “title”. Used in meta tags to identify the page content in search engines and social media. Shown in the web page as the largest header text. Assigned automatically during construct.

protected $twImagePath = '';

String: The absolute web address to an image that is suitable for display when sharing the current page on Twitter. Read from a file named “twImage” in the (localised) page folder, or, if missing, from its parent folder. Defaults to a branded image of the ΩJr.Net. Assigned automatically during construct.

protected $uriCanonical = '';

String: web address used to tell browsers, search engines, and social media, where to find the authoritive resource for the current web page. Helps recognise whether the page was requested at the authoritive domain.

Publizjr 2 Public Interface Methods

Listed alphabetically:

void addCallToAction ()

Adds to the page a div.callToAction which contains both an h2.callToActionCaption containing a caption, and a p.callToActionText containing text. Usually placed underneath the extending html (underneath the body text).
Expects 2 textual translations, the filenames of which should be supplied as the constructor parameters named filenameCallToActionCaption and filenameCallToAction.
Edit the translation file contents to suit your needs. Publizjr expects each section to sport its own call to action.

void addExtendedCss ( $deeperFolder = '' )

Adds to the page head section a style element containing the contents of the file “xtend.css”, if that file exists inside the page folder. If $deeperFolder is provided, it will be used as a an additional path to a folder inside the page’s folder, in which Publizjr is expected to find the file “xtend.css”. This lets webmasters and server admins granulate access control.

function addExtendedHtml ( $deeperFolder = '' )

Adds to the page, right after adding the body text, a div element containing the contents of the file “xtend.htmls”, if that file exists inside the page folder. If $deeperFolder is provided, it will be used as a an additional path to a folder inside the page’s folder, in which Publizjr is expected to find the file “xtend.css”. This lets webmasters and server admins granulate access control.

void addExtendedJs ( $deeperFolder = '' )

Adds to the page head section, underneath the extending css, a script element containing the contents of the file “xtend.js”, if that file exists inside the page folder. If $deeperFolder is provided, it will be used as a an additional path to a folder inside the page’s folder, in which Publizjr is expected to find the file “xtend.css”. This lets webmasters and server admins granulate access control.

void addNavMenu ()

Adds to the page a menu. It starts looking for a menu file “navMenu” inside the current page’s child folder. If that menu file exists, it is parsed and printed to the web page. If not, it goes up to its parent folder and looks for the file “navMenuForChildren”. If that seems amiss, it goes up to the index folder (not the root folder) and looks for the file “navMenuForChildren”. This function is language-aware.

void addPageBody ()

Adds to the page body section a div.body element containing the contents of the file “body”, if that file exists inside the page folder. If that file does NOT exist, the Publizjr template will generate a 404 page instead.

void addPageComments ()

Adds to the page footer element the contents of the translation file “pagecomments”, if that file exists, and if the page folder does NOT contain an empty file named “noPageComments”.
The “pagecomments” translation contains html, css, and js. It generates a form which the visitor can use to activate page comments. The page comments are provided by Disqus. You SHOULD edit this translation to reflect the Disqus identifiers for your web site.

void addPageLinks ( $extraLIs = '' )

Adds to the page body section an h2.related element and a ul.related element if the page folder contains a file named “links” or if the parameter “$extraLIs” is not empty.
The h2.related element is filled with the contents of the translation file “morelinks”. See the function readMoreLinksCaption(), below.
The ul.related element is filled with the parsed contents of the file “links”, if it exists in the page folder, followed by the unparsed contents of the parameter “$extraLIs”.
The “links” file in the page folder should contain hyperlinks in e-mail address format; one link per line. Example:
"Publizjr - Creates Web Pages" <https://omegajunior.globat.com/code/publizjr/>
Relative web addresses can be supplied.
These links are marked up with Rich Snippet mark-up, following the ItemList schema specification: http://schema.org/ItemList

void addSearchForm ()

Adds to the page, wherever called (usually between the h1 and the div.body, the contents of the translation file “searchform”. This file contains html and css. It generates a small search form (just an input and a button), which redirects the visitor to a central search page. Edit the contents of this translation to suit your needs.

void addSocialSharingButtons ()

Adds to the page footer element the contents of the translation file “socialsharing.131015t2211”, if the page folder does NOT contain an empty file named “noSocialSharing”. This translation contains php, html and css. It generates static social sharing buttons to twitter, google plus, facebook, and linkedin, and also a donate button linking to ΩJr.’s flattr. Edit the contents of this translation to suit your needs.

void addTranslation( $which = '' )

Adds to the page the contents of the translation file named in the parameter $which, if it exists and is not empty. Allows you to use translations that you uploaded to the translations folder. (Uses the function readTranslation() internally.)

void addVCard ()

Adds to the page footer element the contents of the translation file named in the constructor parameter filenameDefaultVCardTranslation, if the page folder does NOT contain a file named “vcard”.

void addWarningDeprecatedBrowser ()

Adds to the page, wherever called, the contents of the translation file “warningDeprecatedBrowser”, which contains html that warns users of unsupported browsers. By default, it warns users of MS web browsers older than MSIE7 to update their browser or use a competitive one (with hyperlinks to 4 competitors). Adjust this translation to suit your needs.

Boolean doesPageExist ()

Concludes whether the requested page exists based upon the following requirements:
- the child folder must exist and be a folder;
- inside the child folder the “body” file must exist and not be empty.
By default, the Publizjr template generates an http-404 status response (page not found) if the requested page does not exist.

String generateBodyClass ()

Uses the ID of the page to generate in order to create a qualified CSS class name attribute to add to the body element of the page. The template itself adds the resulting text to the web page’s body element declaration. This can be used to specify page-specific styling inside the main CSS file (so you don’t have to add an extending css file to the page folder).
The output looks something like this:
class="publizjr-2-api-doc", where the actual class name depends on the page id of the generated page. Notice the prefixed space.

String generateCanonicalURI ()

Generates a web address by combining the contents of the constructor parameter uriCanonicalSection, the “id” query parameter, and the page ID of the currently generated page.
The output of this function looks like the following for this page:
https://www.omegajunior.net/code/publizjr/?id=publizjr-2-api-doc

String readContentType ()

Returns the plain-text contents of the optional page file “ogType”, if it exists and contains anything. Otherwise, returns the default contenttype “article”. Use this to characterise the page content for social sharing media like Facebook and Twitter. Possible values are:
article, activity, author, blog, book, cause, city, company, product, public_figure

String readIntro ()

Returns the plain-text contents of the optional page file “intro”, if it exists and contains anything. Use this to introduce the page goal to the readers. Usually shown between the page title and the page body.

String readLastModifiedCaption ()

Returns the contents of the translation “lastModified”, if it exists and contains any text. Otherwise, returns the default text “Last Modified:”. Used as a caption for the date which informs the visitor when the author last edited the current page.

String readTwitterCardType ()

Returns the plain-text contents of the optional page file “twCardType”, if it exists and contains anything. Otherwise returns the default text “summary”. Use this to tell Twitter what to show from the current page if it is linked on Twitter’s social media platform. Valid options include:
app, gallery, player, photo, summary, video

String readTranslation ( $which = '', $default = '' )

Returns the contents of the translation file named in the parameter $which, if it exists and is not empty. Allows you to read translations that you uploaded to the translations folder. If the requested translation returns nothing, the function will return the contents of the parameter $default, if it was supplied a string value.