Formatting

With the ePages REST SDK its easy to format output without any usage of HTML. The definition of Formatting objects can be done via config.json or direct inline PHP.

Define Formatters via config.json

The first example

All defined Formatters are written down in the formatting element of the config.json.

{
    "formatting":
    {
        "image":
        {
            "formatters": ["IMAGE"]
        },
        "strong":
        {
            "formatters": ["BOLD"]
        }
    }
}

The little example defines two Formatters with the name image and bold. With using the SDK you can directly execute this Formatters in PHP.

<?php
require 'libraries/epages-rest-php.phar';

echo $imageFormatter->format("http://path.to.an/image.file");
echo $strongFormatter->format("makeMeBold");
?>

These lines of code will produce the following HTML structure:

<img src="http://path.to.an/image.file"/>
<strong>makeMeBold</strong>

The formatters array does define the Formatters which should be executed.

Using more than one Formatter

Solution 1

Imagine you want to make something looking strong and italic you can define two seperate Formatters.

{
    "formatting":
    {
        "italic":
        {
            "formatters": ["ITALIC"]
        },
        "strong":
        {
            "formatters": ["BOLD"]
        }
    }
}

The PHP script will work but does not look good.

<?php
require 'libraries/epages-rest-php.phar';

echo $strongFormatter->format(
        $italicFormatter->format("String To Format");
     );
?>

Solution 2

Its easier to define a single Formatter with more steps of execution:

{
    "formatting":
    {
        "italicAndBold":
        {
            "formatters": ["ITALIC", "BOLD"]
        }
    }
}

With this single Formatter you can do two formatting steps with one line of code.

<?php
require 'libraries/epages-rest-php.phar';

echo $italicAndStrongFormatter->format("String To Format");
?>

Both example will produce the following HTML stuff.

<strong><em>String To Format</em></strong>

Pay attention The order in the formatters array is important. Changing ITALIC and BOLD order like "formatters": ["BOLD", "ITALIC"] will produce other HTML output: <em><strong>String To Format</strong></em>.

Lots of extra features

With this Formatter object there are lots of other useful functions. You can define classes, IDs and other HTML attributes. The following JSON will handle a real example.

{
    "formatting":
    {
        "imageLogo":
        {
            "formatters": ["IMAGE", "NEWLINE"],
            "classes": ["borderless"],
            "id": "logo",
            "attributes":
            {
                "width": "150",
                "height": "230"
            }
        },
        "imageGallery":
        {
            "formatters": ["IMAGE", "NEWLINE"],
            "classes": ["gallery"]
        }
    }
}

To use both Formatter look to the following PHP script:

<?php
require 'libraries/epages-rest-php.phar';

# Doing some stuff to get the $logoImage and $galleryImages (e.g. array with 4 images)

echo $imageLogoFormatter->format($logoImage);

foreach ($galleryImages as $galleryImage) {
   echo $imageGalleryFormatter->format($galleryImage);
}
?>

This few lines will produce following HTML definition.

<img class="borderless" id="logo" with="150" height="230" src="...."/>
<img class="gallery" src="..."/><br/>
<img class="gallery" src="..."/><br/>
<img class="gallery" src="..."/><br/>
<img class="gallery" src="..."/><br/>

Possible Formatters

With 0.2.0 there are the following Formatters possible to use. Feel free to create an issue if you want more. The PLACEHOLDER is the string which will be formatted.

Formatter	Result
IMAGE	<img src="PLACEHOLDER" />
BOLD	<strong>PLACEHOLDER</strong>
ITALIC	<em>PLACEHOLDER</em>
HYPERLINK	<a href="PLACEHOLDER">
NEWLINE	PLACEHOLDER<br/>

Without config.json

If you want to create a Formatter object while lifetime without using config.json definition its also possible.

Figure out: This is NOT recommended. The Formatter object is an internal helper object and may can change their functions and attributes!

<?php
require 'libraries/epages-rest-php.phar';

$myOwnFormatter = new ep6\Formatter();

# Add BOLD and ITALIC actions
$myOwnFormatter->add("BOLD");
$myOwnFormatter->add("ITALIC");
# Set an HTML tag ID
$myOwnFormatter->setID("myTestID");
# Add some HTML tag classes
$myOwnFormatter->setClass("classOne");
$myOwnFormatter->setClass("classTwo");
# Add some other HTML attributes
$myOwnFormatter->setAttribute("width", "250");
$myOwnFormatter->setAttribute("height", "150");

$myOwnFormatter->format("StringToFormat");
?>