Concepts¶

To know the RDF model of your data, create.js parses the page DOM for RDFa attributes. Whenever it encounters an about attribute, it knows that this section is an editable content. The typeof attribute tells what type the content has. The property attributes indicate that the parts inside that tag are editable. An article might look like this:

1
2
3
4
5
6
7

<div about="/cms/content/home" typeof="schema:WebPage" xmlns:schema="http://schema.org/">
    <h1 property="schema:headline">The Title</h1>
    <div property="schema:text">
        <h2>Welcome to the Symfony CMF Demo</h2>
        <p>If you see this page, it means that the...</p>
    </div>
</div>

Each property has a type. You can configure what editor to use for which type. CreateBundle comes with two editors: plaintext (with no formatting) and WYSIWYG. You can also define your own editors.

Create.js uses backbone.js to save edited data to the server in the JSON-LD format. You may have several objects editable on a single page. There will be one request per editable content that was actually modified.

The CreatePHP library provides the RDF information for create.js by creating RDFa attributes on your data in the templates. It also maps the JSON-LD sent by backbone.js back to your domain objects.

The CreatePHP library contains a metadata tool to define the mapping between your domain objects and the RDF information. It provides a Twig extension to enrich your HTML pages with the RDFa attributes, similar to how you output forms. CreatePHP also provides the means to store the JSON-LD data sent by backbone.js back into your domain objects and save them. If you know Doctrine, this is a similar job to how Doctrine reads data from database columns and loads them into your domain objects.

The CreateBundle finally registers the Twig extension in Symfony and provides a REST controller for the backbone.js ajax calls. It also provides helpers to bootstrap create.js in your templates.

Dependencies¶

The CreateBundle depends on the create.js github repository, which contains all create.js dependencies like jquery, vie, hallo, backbone and so on. Do not forget to add the composer script handler to your composer.json as described below to have CreateBundle clone that repository for you.

PHP dependencies are managed through composer. Besides the before mentioned CreatePHP, the CreateBundle also requires the AsseticBundle and the FOSRestBundle which in turn needs the JmsSerializerBundle. Make sure you load all those bundles in your kernel and properly configure Assetic as described below.

To upload and display images the MediaBundle is used. CKEditor uses the elfinder adapter.

Installation¶

You can install this bundle with composer using the symfony-cmf/create-bundle package.

Additionally, you will need to provide the JavaScript libraries. The standard way to do this is to add a scripts section in your composer.json to have the CreateBundle download the necessary libraries:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "scripts": {
        "post-install-cmd": [
            "Symfony\\Cmf\\Bundle\\CreateBundle\\Composer\\ScriptHandler::downloadCreateAndCkeditor",
            ...
        ],
        "post-update-cmd": [
            "Symfony\\Cmf\\Bundle\\CreateBundle\\Composer\\ScriptHandler::downloadCreateAndCkeditor",
            ...
        ]
    }
}

It is possible to specify another target directory, repository URL or commit id in the extra parameters of composer.json file if you need to use a development version of CKEditor or create.js. The default values (note that you should not hardcode those in your composer.json unless you need to overwrite them) are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
    "extra": {
        "create-directory": "vendor/symfony-cmf/create-bundle/Resources/public/vendor/create",
        "create-repository": "https://github.com/bergie/create.git",
        "create-commit": "a148ce9633535930d7b4b70cc1088102f5c5eb90"

        "ckeditor-directory": "vendor/symfony-cmf/create-bundle/Resources/public/vendor/ckeditor",
        "ckeditor-repository": "https://github.com/ckeditor/ckeditor-releases.git",
        "ckeditor-commit": "bba29309f93a1ace1e2e3a3bd086025975abbad0"
    }
}

Add this bundle (and its dependencies, if they are not already added) to your application's kernel:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Symfony\Bundle\AsseticBundle\AsseticBundle(),
            new JMS\SerializerBundle\JMSSerializerBundle($this),
            new FOS\RestBundle\FOSRestBundle(),
            new Symfony\Cmf\Bundle\CreateBundle\CmfCreateBundle(),
        );

        // ...
    }

    // ...
}

You also need to configure the FOSRestBundle to handle json:

If you want to use Assetic to combine the CSS and JavaScript used for create.js, you need to enable the CreateBundle in the Assetic configuration. Find the configuration for assetic.bundles. If it is not present, Assetic automatically scans all bundles for assets and you don't need to do anything. If you limit the bundles, you need to add CmfCreateBundle to the list of bundles.

If you were not using Assetic previously, you need to call the assetic:dump command in your deployment process, or the Javascript and CSS files will not be found:

1

$ php app/console --env=prod assetic:dump

Rendering Content¶

Create.js needs to identify what is editable in your content. To do this, it needs the RDF attributes in the HTML. Now that everything is prepared, you need to adjust your templates to output that information.

To render your data named cmfMainContent with a handle you call rdf, use the createphp Twig tag as follows:

1
2
3
4
5
6

{% createphp cmfMainContent as="rdf" noautotag %}
<div {{ createphp_attributes(rdf) }}>
    <h1 class="my-title" {{ createphp_attributes( rdf.title ) }}>{{ createphp_content( rdf.title ) }}</h1>
    <div {{ createphp_attributes( rdf.body ) }}>{{ createphp_content( rdf.body ) }}</div>
</div>
{% endcreatephp %}

The noautotag tells CreatePHP to not automatically output a <div> with namespace declarations and the about property containing the id of your object. When using noautotag, it is your responsibility to call createphp_attributes() inside a container tag that contains the fields of the object.

You can also output a whole field complete with tag, attributes and content by just calling {{ rdf.body|raw }}. (Without the raw filter, the HTML output by CreatePHP would be escaped.) You can even output the whole document automatically:

1
2
3

{% createphp cmfMainContent as="rdf" %}
{{ rdf|raw }}
{% endcreatephp %}

This will simply output all fields in the order they appear in the mapping file. With the optional tag-name attribute in the mapping file you can replace the default <div> tag with your own choice. And using an <attribute> child to specify CSS classes, you can let CreatePHP generate your HTML structure if you want.

Metadata¶

CreatePHP needs metadata information for each class of your domain objects. By default, the create bundle uses the XML metadata driver and looks for metadata in every bundles at <Bundle>/Resources/rdf-mappings. If you use a third party bundle that does not come with RDFa mapping, you can simply include a mapping file for it in any of your bundles, or specify a directory containing mapping files with the rdf_config_dirs option.

The mapping file name needs to be the fully qualified class name, having the backslash (\\) replaced by a dot (.), i.e. Symfony.Cmf.Bundle.ContentBundle.Doctrine.Phpcr.StaticContent.xml.

A basic mapping look as follows:

The most relevant parts are the property telling the RDF type, and the identifier telling the field of the class you map. If you use namespaces like schema.org, your annotations will actually make semantically sense. But you can also ignore this and use your own annotations, as long as you declare the namespaces you use.

You can additionally specify the HTML tag to be used when automatically rendering this field (see below). The default tag is div. And you can specify additional HTML attributes like the class attribute. A full example reads like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- Resources/rdf-mappings/Symfony.Cmf.Bundle.ContentBundle.Doctrine.Phpcr.StaticContent.xml -->
<type
    xmlns:schema="http://schema.org/"
    typeof="schema:WebPage"
>
    <children>
        <property property="schema:headline" identifier="title" tag-name="h1"/>
        <property property="schema:text" identifier="body">
            <attribute key="class" value="my-css-class"/>
        </property>
    </children>
</type>

Mapping Requests to Domain Objects¶

One last piece is the mapping between CreatePHP data and the application domain objects. Data needs to be stored back into the database.

Currently, the CreateBundle only provides a service to map to Doctrine PHPCR-ODM. If you do not enable the phpcr persistence layer, you need to configure the cmf_create.object_mapper_service_id.

CreatePHP would support specific mappers per RDFa type. If you need that, dig into the CreatePHP and CreateBundle and do a pull request to enable this feature.

Workflows¶

CreateJS uses a REST api for creating, loading and changing content. To delete content the HTTP method DELETE is used. Since deleting might be a more complex operation than just removing the content form the storage (e.g. getting approval by another editor) there is no simple delete button in the user frontend. Instead, CreateJS and CreatePHP use "workflows" to implement that. This bundle comes with a simple implementation of a workflow to delete content. To enable the workflow set the config option 'delete' to true.

This results in the delete workflow being registered with CreatePHP and CreateJS so that you can now delete content from the frontend.

In a more complex setup you need to create your own workflow instance, register it with CreatePHP and implement your logic in the workflows run method.

Currently the bundle only supports delete workflows but that will change in the future.

Read On¶

• Developing the Hallo Wysiwyg Editor
• Other Editors
• Configuration Reference