It's incredibly simple

Getting Started

Follow the instructions below to see how easy it is to get started with Dytomate. It's as easy as downloading 2 files and providing a couple of configuration options.

Download For Free

Client Side Integration

Integrating Dytomate into client side code is super simple. Just download dytomate.min.js JavaScript file and include it in your page like so:

<script src="/path/to/dytomate.min.js"></script>

We recommend putting this before all your other JavaScript includes in <head> section of your HTML but it should work anywhere.

To keep things safe you should only include this JavaScript when user has access to modify your site data.

Understanding Tags

You can make any element editable by adding a data-dytomate attribute for the element you want to edit. Value for this attribute should be a unique key so that it can be identified and stored properly.


<div data-dytomate="example-key">Lorem Ipsum...</div>
        

Element contents should be filled with stored value from server. This should be handled by server side library - like the PHP one we provide for you.

You can also make elements read-only and they will still update when mutable element with the same key is changed. To do that add data-dytomate-ro attribute with value of true.


<div data-dytomate="example-key" data-dytomate-ro="true">Lorem Ipsum...</div>
        
Comminicating With Server

Whenever content is modified - JavaScript will send AJAX requests to two URLs.

POST /api/dytomate/save

This request will be made when any textual component is changed. Request will be made with 3 POST parameters. `key` which represents components key. `value` which represents components value. `attributes` which is an array that represents all components attributes where array key is attribute name and array value is attribute value.

POST /api/dytomate/upload

This request will be made when image component is changed. It will have both `key` and `attributes` POST parameters as in previous request but `value` will now be an array with two keys. `name` which contains image name and `blob` which contains base64 encoded image data.

These both requests should return a JSON response containing saved data like so:


{
    "success": true,
    "value": "<savedValue>",
    "attributes": {
        "<attributeName>": "<attributeValue>"
    }
}
        

If this seems complicated - don't worry. We provide a PHP library to handle all this for you. Read on to see how that works.

PHP Server Library

We provide a simple PHP library that will handle all data saving and retrieving logic so that you don't have to worry about anything.

Composer Installation

Our recommended installation method is by using Composer. It's as simple as executing this command:

composer require sds/dytomate-php:dev-master

After that just include the provided autoloader if you haven't already and you're all set.

require "vendor/autoload.php";
Manual Installation

If for some reason you don't want to go the Composer installation route you can also manually download the dytomate.php file and include it where you want to use this library.

require "dytomate.php";
Library Configuration

All configuration happens through \SDS\Dytomate\DytomateFactory::setDefaultConfiguration(array $configuration) method. This will set the default configuration options but you can also set custom options through \SDS\Dytomate\DytomateFactory constructor and they will be merged with default options.


\SDS\Dytomate\DytomateFactory::setDefaultConfiguration([
    "defaultData" => [
        "example-key" => "Lorem Ipsum..."
    ],

    "pdo" => [
        "password" => "secret"
    ]
]);
        
Retrieving Dytomate Instance

Dytomate intance can be retrieved by using \SDS\Dytomate\DytomateFactory::makeDefault() method. You can also use \SDS\Dytomate\DytomateFactory::make() method if you have factory instance.


$dytomate = \SDS\Dytomate\DytomateFactory::makeDefault();

// or

$factory = new \SDS\Dytomate\DytomateFactory($configuration = []);
$dytomate = $factory->make();
        
Configuring Database

We use PDO and MySQL for data storage and access. All you need to do is tell us how to connect to the database and we will handle the rest.


\SDS\Dytomate\DytomateFactory::setDefaultConfiguration([
    "pdo" => [
        "dsn" => "mysql:host=localhost;port=3306;dbname=dytomate", // database connection string
        "user" => "root", // database username
        "password" => "secret" // database password
    ]
]);
        
Configuring Image Uploads

To be able to store images we need to know where to store them and how to display them. This is easily configurable.


\SDS\Dytomate\DytomateFactory::setDefaultConfiguration([
    "uploadPath" => "/var/www/dytomate/public/uploads", // full path to directory where images will be stored
    "uploadUrl" => "http://example.com/uploads" // how will these images be accessible by users
]);
        
Configuring Security

You don't want anyone to be able to modify your site without proper authentication. By default we will lock it down so that nobody can modify it but you can set any custom logic to suit your needs.


\SDS\Dytomate\DytomateFactory::setDefaultConfiguration([
    // you can set any logic you like in this callback and just return true if access is granted for this request
    "isAccessAllowedCallback" => function() {
        return !is_null(getCurrentUser());
    }
]);
        
Basic Authentication

If you don't want to create your own authentication we provide Basic Authentication support out-of-box.


\SDS\Dytomate\DytomateFactory::setDefaultConfiguration([
    "basicAuth" => [
        "enabled" => true, // set to true if you wish to enable basic authentication
        "username" => "admin", // username that needs to be entered to enable modification
        "password" => "secret", // password that needs to be entered to enable modification
        "path" => "/dytomate/login" // URL path where users need to go to attempt login
    ]
]);
        
Registering Routing

If you wish to use our provided request handling then you need to configure your URLs and call our router.


\SDS\Dytomate\DytomateFactory::setDefaultConfiguration([
    "http" => [
        "scheme" => "http", // by default we will accept any scheme
        "host" => "example.com", // by default we will accept all hosts
        "basePath" => "/blog", // if your website lives under a directory you can set it here - by default we assume it exists in the root
    ]
]);

// this will handle all necessary Dytomate requests that deal with data storage
if (!$dytomate->getRouter()->route()) {
    // handle your application routing here if necessary
}
        

If you don't wish to use our provided request handling you can disable routing to save some resources.


\SDS\Dytomate\DytomateFactory::setDefaultConfiguration([
    "enableRouting" => false
]);
        
Retrieving And Rendering Data

This library provides several methods to make it super easy to retrieve any stored data and output Dytomate compatible HTML tags.


// ->get("<key>") will return value for given key
<div data-dytomate="example-key" class="example"><?= $dytomate->get("example-key") ?></div>

// ->getTag("<key>", "<tag>", [ "<attributeName>" => "<attributeValue>" ]) is shorthand for the above
<?= $dytomate->getTag("example-key", "div", [ "class" => "example" ]) ?>

// second argument for ->get() is dummy data options which when provided and value isn't set for the key will generate dummy data for you
<div data-dytomate="example-key"><?= $dytomate->get("example-key", 3) ?></div>

// ->getTag() shorthands forth argument can be used for the same result
<?= $dytomate->getTag("example-key", "div", [], 3) ?>

// ->getReadOnlyTag() shorthand will do the same as ->getTag() but will make element read-only
<?= $dytomate->getReadOnlyTag("example-key", "div", [], 3) ?>

// ->getAttribute() will return attribute value for given key and can also generate dummy data for you
<?= $dytomate->getAttribute("example-key", "href", 3) ?>
        
Default Data

Initially you won't have any data stored but you might have an idea for default data so that your site doesn't look empty in the very beginning. We provide a simple way to configure default data so that your site always has things to show.


\SDS\Dytomate\DytomateFactory::setDefaultConfiguration([
    "defaultData" => [
        "example-key-1" => "Example value 1", // setting default value for a key
        "example-key-2" => [ "value" => "Example value 2", "href" => "http://example.com" ], // setting default value and href attribute for a key
    ]
]);
        
Dummy Data

If you have a lot of different components that you wish to edit you might not want to manually set default values for all of them. This is where dummy data comes in. By using loripsum.net and lorempixel.com we can generate data for you with no extra effort on your side.


// displays all available options for text generation - you can supply one or more options
$dytomate->getTag("example", "div", [], [
    "paragraphs" => 3, // how many paragraphs to generate
    "length" => "medium", // how long should the paragraphs be
    "decorate" => false, // should it contain any text decorations like bold and italic
    "link" => false, // whether to include links
    "ul" => false, // whether to include unordered lists
    "ol" => false, // whether to include ordered lists
    "dl" => false, // whether to include definition lists
    "bq" => false, // whether to include blockquotes
    "code" => false, // whether to include code sections
    "headers" => false, // whether to include headers
    "allcaps" => false, // should text be in all caps
    "prude" => false, // whether to generate prude version
    "plaintext" => false // whether to include any tags ( including paragraph tags ) at all
]);

// shorthand for generating 3 paragraphs
$dytomate->getTag("example", "div", [], 3);

// displays all available options for image generation - you can supply one or more options
$dytomate->getTag("example-image", "img", [], [
    "size" => 500, // image size in pixels ( will set both width and height making image a square )
    "width" => 100, // image width in pixels
    "height" => 200, // image height in pixels
    "grayscale" => false, // whether image should be grayscale
    "category" => false, // what category images should it show ( e.g. sports )
    "number" => false, // which image to show if you don't want it to be random ( 1 - 10 )
    "text" => false // what text to include inside image
]);

// shorthand for generating 400x400 image
$dytomate->getTag("example-image", "img", [], 400);
        
Do you like magic? We sure do! Subscribe for monthly tips on techology fairy dust you can show your clients when delivering a web application.
i