Documentation

Developping for MidnightCMS

How to create a new page type ?

Creating a new page type in MidnightCMS is really simple. You just need to create a new folder "Type" in your working bundle (AppBundle for example) and add one file per wanted type (one type = one file).
In this file you'll write a class that extends AbstractType (From VFou\CmsBundle\Type). You'll need to implement every needed functions ('display', 'addForm' and 'handleRequest') and override those you want to change the behavior.

The page entity contains a Data field, that is used to store the data of the page type. For example, in 'Page' type, the data field is used to store the raw HTML content. However, the 'Sitemap' type will store an array of two parameters. You can store everything you want into this field.

You can take example of the existing types, like the basic page type, but for most advanced usage you can take example of the blog page type from the blog extension of midnightCMS.

You can also take a look into the examples section for more code examples.

Overview of every functions

Initialization functions
  • __construct(EntityManagerInterface $em, Environment $twig)
    If you need to call more services, you can add any service class in argument and the autowire will do the work.
    By default, the construct gives you an entity manager (accessible via $this->em) and the twig service ($this->twig).

  • initialize($name = "Unknown", $icon = null)
    You must override this function to properly register your type. You can see an example of overrided initialize function into the classic 'page' type.
    By default, this function will register your type as "Unknown" without icons.

Display functions
  • getPrevious(Page $page)
    This function must returns the previous page of $page. In some case you'll need to change it if your page type can display multiple pages. (A good example can be seen into the 'blog' type of the blog extension).
    By default, this function will return the parent page.
  • handleUrl($route, Page &$page)
    This function is called for you to verify if your page type can handle the next part of the route. The $route variable will contain the route part that is after your page route segment. If you return 'true', the $options array into the 'prepareDisplay' will contain a "route" variable that'll contain the $route.
    By default, this function always return false.

  • prepareDisplay(Request $request, Page $page, &$options)
    This function is called before 'display'. He is called before the twig rendering, and is useful for preloading and process specific values. You can fill the $options variable with values that will be available for the display method.
    If you have returned "true" into the 'handleUrl' function, you'll have a preset option called "route" that you can use for handling the route and prepare the page to be displayed. A good example can be seen into the 'blog' type of the blog extension)
    By default this function do nothing.

  • display(Page $page, $options = []) (required)
    This function is called into the twig rendering. You'll have to return raw HTML that will be displayed into the "content" block.

Backend-Related functions
  • addForm(FormBuilderInterface $fb, Page $page) (required)
    This function will be called when the user click on the page in the backend. You get a FormBuilder $fb that'll contain the actual form of the page. You have to add your own fields with this builder, and set their data in this function with the help of the page's data.

  • handleRequest(Request $request, Page &$page) (required)
    This function is called when the user submit the backend's page form. You'll get a request with the fields you have added into the 'addForm' function. Here you can store everything you want into the page's data field.

Frontend Editing functions
  • frontendEditing(FormBuilderInterface $fb, Page $page, Draft $draft, &$options)

    This function is called when the Frontend editor opens on your page. You have a FormBuilder that you need to fill and return exactly like the 'addForm' function. The $options can have two parameters 'beforeHTML' and 'afterHTML' that'll obviously be appended before and after the form. These fields must contains raw HTML. You can see a complex example of use of the frontend editing in the 'blog' type of the blog extension. You must get the data of the given $draft entity for filling your form.
    By default, this function returns the 'display' function's result, like the frontend editor is not enabled.

  • fEditingHandle(Request $request, Page &$page, Draft &$draft)
    This function is called like the 'handleRequest' function: when the form is saved, and you just have to process the request and you have to store it into the $draft entity's data property.
    By default, this function do nothing.
  • fEditingSubmit(Page &$page, Draft $draft)
    This function is called when the user want to submit his page. You have to process the draft's stored data and set the page's data. You must remove the draft as soon as you can. As usual, you can see an advanced use of frontend editing into the 'blog' type of the blog extension.
    By default, this function sets the draft's data into the page's data.

Cache functions
  • getCacheLevel()
    Here you must return the cache level you want to use for your page type. Every cache level are stored into the CacheService class. There is a description of every cache level into this file.
    By default, this function always return NO_CACHE level.
  • clearCache(CacheService $cache, Page $page)
    This function is called when you have set the cache level to any "Custom" value. Here you can clear the cache of your custom-handled URLs. A good example is available in the 'blog' type of the blog extension.

How to add elements to the backend toolbar, register templates or configurations ?

Add elements into the toolbar, as well as registering templates or configuration uses the same file and a similar pattern than creating a type of page. You'll need to create a folder named "Configuration" in your Bundle. Inside you create one file for all your configuration (you can separate it into multiple files if you want).

This file will be a PHP class that extends AbstractConfiguration from VFou\CmsBundle\Configuration.
You can override any functions of AbstractConfiguration that you want, and register everything you want as long as you respect the pattern explained in the next part.

Note that you can use the cms configuration file as an example for your configuration files.

Overview of every functions

  • __construct(TranslatorInterface $translator)
    If you need to call more services, you can add any service class in argument and the autowire will do the work.
    By default, the construct gives you the translator (accessible via $this->translator).
  • getConfiguration()
    In this function you'll need to return an array with the fields you want to add to the configuration, following this pattern:
return [
  "unique_field_name" => [
          "name" => "Label of the field",
          "hint" => "description of this configuration, displayed on the bottom of the input field",
          "default" => "default value"
      ],
  "another_configuration" => [/*...etc...*/]
];

note: you'll need to override 'getForm' if you want your form to be displayed.

  • getForm(FormBuilderInterface $fb, $configuration)
    This functions gives you a FormBuilder that you'll fill with the actual fields you want to add and then return it. You'll have to take the name and hint of 'getConfiguration'. The $configuration variable contains the current configuration array with all the values sets to defaults if they're inexistant. You can see an example of use of this function in the cms configuration file.
  • addToolbar(RouterInterface $router)
  • In this function you can register new toolbar links. You just have to return an associative array with the toolbar name as keys (they will be translated with "admin" domain automatically) and the route name you want to redirect the user as value.

  • registerTemplate()
    In this function you can register templates. As for the "addToolbar" function, you have to return an associative array with the name of the template as keys (that will also be translated with "admin" domain) and the resource route name as values (for example "@VFouCmsBundle/Resources/views/Type/sitemap.html.twig"). The @YourBundle is important because the CMS uses it for template overriding.