Using iFrames with kitCommands

If you want to use the kitCommands not only for small code snippets but for interactive extensions it is a good idea to use inline frames to show the contents and dialogues returned from the kitCommand.

The key advantages of using iframes for the kitCommands are:

• optimized loading - the CMS must not wait for the response of the kitCommand
• if a form is submitted or another page loaded within the iframe the CMS parent page must not reload
• the content of an iframe is independent from the conditions of the CMS, i.e. you can use the jQuery version and add-ons you need

The kitCommands provide you with an iframe service

• that has a auto re-sizing function (can switched off)
• can use different templates
• can use different CSS
• enable auto-tracking functions (Google Analytics, Piwik)

furthermore URL's which belong to a kitCommand iframe and are opened outside of the Content Management System can redirect themselves to be displayed within the CMS.

Please try

~~ HelloIFrame ~~

and test it.

This is the controller for HelloIFrame:

use phpManufaktur\Basic\Control\kitCommand\Basic as kitCommandBasic;

$app->post('/command/helloiframe', function() use ($app) {
    $kitCommand = new kitCommandBasic($app);
    return $kitCommand->createIFrame('/helloworld/iframe/start');
}); 

The controller initialize the Class Basic and create the iframe.

The parameter of $kitCommand->createIFrame() is a route which return the content that should be shown first - it's your entry point.

The kitCommand Basic Class is handling all for you and it is normally not necessary to configure or to change anything.

$app->match('/helloworld/iframe/start',
    'thirdParty\HelloWorld\Control\HelloIFrame::start');

This route looks differently to such you have already seen. The second parameter tell the kitFramework to load the class thirdParty\HelloWorld\Control\HelloIFrame and execute the function start() within the class.

This short-hand directive is identical with this code:

use thirdParty\HelloWorld\Control\HelloIFrame;

$app->post('/helloworld/iframe/start', function() use ($app) {
    $class = new HelloIFrame();
    return $class->start($app);
});

If you have tested ~~ HelloIFrame ~~ you have seen, that there are the start screen and three different dialogues, here are the controllers for the dialogues:

$app->match('/helloworld/iframe/step02',      
    'thirdParty\HelloWorld\Control\HelloIFrame::step02');
$app->match('/helloworld/iframe/step03',      
    'thirdParty\HelloWorld\Control\HelloIFrame::step03');
$app->match('/helloworld/iframe/step04/{id}', 
    'thirdParty\HelloWorld\Control\HelloIFrame::step04');

'/helloworld/iframe/step04/{id}' contain the route variable {id} which will be replaced by a record ID and passed as $id to the function step04().

Please have a look at the class HelloIFrame.

The function start() will return the content for the start page:

public function start(Application $app)
{
    $this->initParameters($app);
    $this->setRedirectRoute('/helloworld/iframe/start');

    return $this->app['twig']->render($this->app['utils']->templateFile('@thirdParty/HelloWorld/Template',
        'hello.iframe.start.twig', $this->getPreferredTemplateStyle()),
        array(
            'basic' => $this->getBasicSettings()
    ));
}

The Application $app will be injected by the controller. With $this->initParameters($app); the Basic Class will be fully initialized and provide you with a full service.

$this->setRedirectRoute('/helloworld/iframe/start');

is optional and tell the kitFramework to which route must be redirected, if the actual content will be opened outside of the iframe (nesting back).

return $this->app['twig']->render(..)

You already know this from the chapter Using Class Basic.

    array(
            'basic' => $this->getBasicSettings()
    )

this is important. To get the things also in the templates working you must always pass the Basic Settings as basic to your templates.

Now have a look at the template hello.iframe.start.twig:

{% extends template_file('@phpManufaktur/Basic/Template', 'kitcommand/iframe.body.twig') %}
{% block title %}{{ 'iFrame Sample: Start'|trans }}{% endblock %}
{% block description %}{{ 'kitCommand Sample for the usage of iframes'|trans }}{% endblock %}
{% block keywords %}kitFramework,Sample,Hello World{% endblock %}
{% block stylesheet %}
  {{ parent() }}
  <link rel="stylesheet" type="text/css" href="{{ THIRDPARTY_URL }}/HelloWorld/Template/default/css/hello.iframe.css" media="screen, projection" />
{% endblock stylesheet %}
{% block content %}
  {{ parent() }}
  <h2>{{ 'Hello World Sample for iFrames - Start'|trans }}</h2>
  <p>{{ 'Please click <a href="%link%">here</a> to load the next step.'|trans({'%link%':FRAMEWORK_URL ~ '/helloworld/iframe/step02?pid=' ~ basic.pid}) }}</p>
{% endblock content %}

Please remember that for Twig is a very good documentation available - we will not dive in Twig here.

If you are using the iframe feature you must always extend the kitframework template:

{% extends template_file('@phpManufaktur/Basic/Template', 'kitcommand/iframe.body.twig') %}

The function template_file() we have already seen in Using Class Basic.

kitcommand/iframe.body.twig

provide you with all the things you need but it always need the basic variable which contain the basic settings.

{% block title %}{{ 'iFrame Sample: Start'|trans }}{% endblock %}
{% block description %}{{ 'kitCommand Sample for the usage of iframes'|trans }}{% endblock %}
{% block keywords %}kitFramework,Sample,Hello World{% endblock %}
{% block stylesheet %}
  {{ parent() }}
  <link rel="stylesheet" type="text/css" href="{{ THIRDPARTY_URL }}/HelloWorld/Template/default/css/hello.iframe.css" media="screen, projection" />
{% endblock stylesheet %}

These blocks are optional, you can set an title, a description, keywords and you can load additional CSS files.

To grant the functionality of the extended iframe.body.twig you should always use {{ parent() }} as first entry within blocks to get the parented content into your template.

<h2>{{ 'Hello World Sample for iFrames - Start'|trans }}</h2>

Make use of the |trans filter to get translations of your contents.

<p>{{ 'Please click <a href="%link%">here</a> to load the next step.'|trans({'%link%':FRAMEWORK_URL ~ '/helloworld/iframe/step02?pid=' ~ basic.pid}) }}</p>

Write the routes you want to use directly in your template. With {{ FRAMEWORK_URL }} you have access to the complete URL of the kitFramework, which is the base for the routes.

Important: the kitFramework Basic Class create a parameter_id or pid to save information about the kitCommand and used parameters. To grant the full functionality you should always attach this pid to routes (URL's) you are using:

<a href="{{ FRAMEWORK_URL}}/helloworld/iframe/step02?pid={{basic.pid})">sample</a>

In the next step we will start using forms.