Developers/Html frontend/Template syntax and view helper

From Aimeos documentation

Developers
Other languages:
English 100%


2017.x+ version

The template views itself consist of HTML with alternative PHP syntax.

Data access

You have access to all data that has been assigned by the HTML client which renders the view as well as all data that has been assigned by the parent HTML clients, e.g.

Client/Html/Checkout/Standard/Standard
    Client/Html/Checkout/Standard/Address/Standard
        Client/Html/Checkout/Standard/Address/Billing/Standard

The HTML clients use these templates and e.g. assign

  • Client/Html/Checkout/Standard/Standard
    • template: checkout/standard/body-default.php
    • assigns: standardSteps, etc.
  • Client/Html/Checkout/Standard/Address/Standard
    • template: checkout/standard/address-body-default.php
    • assigns: addressCustomerItem, addressPaymentItem, etc.
  • Client/Html/Checkout/Standard/Address/Billing/Standard
    • template: checkout/standard/address-billing-body-default.php
    • assigns: billingMandatory, billingOptional, etc.

In the template of the Client/Html/Checkout/Standard/Address/Billing/Standard HTML client, you have now access to standardSteps, addressCustomerItem, addressPaymentItem, billingMandatory, billingOptional. You should have a look into the templates and the HTML clients to find out which data they assign.

To access the data in the view, you can use

  1. $this->get( 'billingOptional', array() ) // second parameter is the default value if not available
  2. $this->billingOptional // throws an exception if not available
  3. isset( $this->billingOptional ) // tests if the parameter is available

View helper

Additionally, there are some view helpers available.

To use the view helpers in the view, call e.g.

  1. echo $this->url( $target, $controller, $action, $params, $trailing, $config );

The example prints the generated URL for the given parameters. Use lower-case for all view helpers, i.e. "url()" for the view helper in the "Url" directory. The parameters for each view helper varies, so please have a look at each view helper you want to use.

access

Tests if the current user is member of one of the given groups.

  1. <?php if( $this->access( ['mygroup', 'othergroup'] ) ) : ?>
  2.   Yes, I'm a member!
  3. <?php endif ?>

The parameter for the view helper can either be a single group name or a list of group names.

block

Extend from parent templates like in Blade, Fluid or Twig. If you have a common template like this:

  1. <html>
  2.   <head><title>Test template</title></head>
  3.   <body>
  4. <?php echo $this->block()->get( 'content' ); ?>
  5.   </body>
  6. </html>

You can now use this common template in your subpart templates:

  1. <?php $this->block()->start( 'content' ); ?>
  2. <div class="test">
  3.   <h1>Test</h1>
  4. </div>
  5. <?php $this->block()->stop(); ?>
  6.  
  7. <?php echo $this->render( $this->config( 'my/parent/template', 'parent.php' ) ); ?>

The last line is important because it fetches the parent template, inserts the "content" block and outputs the resulting HTML code. The path of the template must be relative to the "templates" directory.

config

Access the configuration settings.

  1. <?php echo $this->config( 'client/html/catalog/detail/url/config', array() ); ?>

The first parameter is the configuration key (without slashes (/) at the beginning and the end, which the second parameter is the default value if no value in the configuration is found.

content

Generates an URL from a path like they are stored in the database.

  1. <?php echo $this->content( 'relative/path/to/media.jpg' ); ?>

Depending on the environment and configuration, this view helper creates a

csrf

Secures form posts with a CSRF token.

  1. <?php echo $this->csrf()->formfield(); ?>
  2. <?php echo $this->csrf()->name(); ?>
  3. <?php echo $this->csrf()->value(); ?>

The formfield() method creates a hidden input field that can be added inside an HTML form tag, while the name() and value() methods return the single values for building an input field of your own.

date

Translates a date into the localized format.

  1. <?php echo $this->date( '2000-01-01 00:00:00' ); ?>

The input must be an ISO date format.

encoder

Quotes the data before printing it to avoid security breaches like cross site scripting (XSS).

  1. <input value="<?php echo $this->encoder()->attr( 'evil"value' ); ?>" />
  2. <p><?php echo $this->encoder()->html( '<value>' ); ?></p>
  3. <tag><?php echo $this->encoder()->xml( '<value>' ); ?></tag>
  4. <?php echo $this->encoder()->url( 'me & you?' ); ?>

You have to use these methods all the time you print a non-static value and you must use the appropriate method for the context. Using html() for an attribute value will result in a XSS security hole.

formparam

Generates the value for the "name" attribute of input elements. Depending on the environment, the value of the name attribute must be formatted differently. This method cares about the right value.

  1. <?php echo $this->formparam( 'name' ); ?> // as name=value in POST request
  2. <?php echo $this->formparam( array( 'name', 'sub' ) ); ?> // as name[sub]=value
  3. <?php echo $this->formparam( array( 'name', '' ) ); ?> // as name[]=value

If you forget to use the formparam() view helper, you component or subpart won't work in some applications!

mail

Provides access to an e-mail message that can be filled with a message body.

  1. <?php $message = $this->mail(); ?>

The available methods in the message object are available in the Aimeos\MW\Mail\Message\Iface.

number

Returns the localized integer or decimal value for the given number.

  1. <?php echo $this->number( 123 ); ?> // 123.00
  2. <?php echo $this->number( '123.45, 1 ); ?> // 123.4

The second parameter is the number of decimal digits the result should contain. Depending on the locale settings, the decimal point and the thousand separator are different.

param

Returns the GET/POST/URL parameter or a list if its an array.

  1. <?php echo $this->param( 'myparam' ); ?>
  2. <?php echo $this->param( 'my/param' ); ?>
  3. <?php echo $this->param( 'myparam', 'default' ); ?>

The first argument is the name of the parameter or path to the value separated by slashes (/) in case it's a multi-dimensional array. In the second example, a structure like

array( 'my' => array( 'param' => 'value' ) )

is assumed and it would return 'value'. The second parameter of the method is the default value returned if no value was found (null if not used).

partial

Renders the given sub-template with the arguments passed.

  1. <?php echo $this->partial( 'mytemplate.php', array( 'key' => 'value' ) ); ?>

The path of the template must be relative to the "templates" directory.

request

Returns the request object implementing the PSR-7 ServerRequestInterface.

  1. <?php $request = $this->request(); ?>

For more information about PSR-7 requests, please have a look into the PHP-FIG documentation of the PSR-7 standard.

response

Returns the response object implementing the PSR-7 ResponseInterface.

  1. <?php $response = $this->response(); ?>

For more information about PSR-7 requests, please have a look into the PHP-FIG documentation of the PSR-7 standard.

session

Returns the value stored in the session of the user.

  1. <?php echo $this->session( 'a/session/key', 'mydefault' ); ?>

The first parameter is the session key which was used to store the value in the session of the user. The key can be any string but using characters, numbers and slashes is recommended. The second parameter is the value returned if the key isn't available in the session.

translate

Translates a string according to the current locale.

  1. <?php echo $this->translate( 'client/code', 'size' ); ?>
  2. <?php echo $this->translate( 'client', '%1$d article', '%1$d articles', 10 ); ?>

The first form is for singular translations, the second one for plural ones.

url

Generates URLs for the given target, controller, action, parameter and configuration.

  1. <?php
  2. $target = $this->config( 'client/html/catalog/detail/url/target' );
  3. $controller = $this->config( 'client/html/catalog/detail/url/controller', 'catalog' );
  4. $action = $this->config( 'client/html/catalog/detail/url/action', 'detail' );
  5. $config = $this->config( 'client/html/catalog/detail/url/config', array() );
  6. $trailing = array( 'anchor' ); // will be added as #anchor
  7. $params = array( 'd_prodid' => 1 );
  8. ?>
  9. <?php echo $this->url( $target, $controller, $action, $params, $trailing, $config ); ?>

Besides the parameter and the trailing array, all other arguments should be retrieved from the configuration.

value

Returns a value from a multi-dimensional arrays in a simple way.

  1. <?php echo $this->value( $array, 'path/to/key' ); ?>
  2. <?php echo $this->value( $array, 'path/to/key', 'default' ); ?>

The first argument is the path to the value separated by slashes (/). In the first example, a structure like

array( 'path' => array( 'to' => array( 'key' => 'value' ) ) )

is assumed and it would return 'value'. The second parameter of the method is the default value returned if no value was found (null if not used).