Merge prototype pages with your existing application

As of today Soflomo\Prototype has been updated to support tight integration into your existing application. Before, Soflomo\Prototype could be used to either bootstrap the first phase of your application design process or to document your REST APIs. However, prototyping new features in your existing application is a very useful add-on to this list.

What is now possible?

Previously, Soflomo\Prototype made all the routes for the pages a literal route. This means the route should match exactly, otherwise the routing fails. This also means you cannot have parameters in your routes. But with v0.2.0, you can! If you need a parametrized route, specify the key “type” in the configuration (it defaults to literal):

'foo-baz' => array(
    'type'     => 'segment',
    'route'    => '/foo/:id/baz',
    'template' => 'mockup/foo-baz'
),

Why is this necessary?

Say for instance you have an application with the following routes & navigation:

'router' => array(
  'routes' => array(
    'foo' => array(
      'type'    => 'segment',
      'options' => array(
        'route'    => '/foo/:id',
        'defaults' => array(/* ... */),
      ),
      'may_terminate' => true,
      'child_routes'  => array(
        'bar' => array(
          'type'    => 'literal',
          'options' => array(
            'route'    => '/bar',
            'defaults' => array(/* ... */),
        ),
      ),
    ),
  ),
),
'navigation' => array(
  'default' => array(
    'foo' => array(
      'label' => 'Foo',
      'route' => 'foo',
      'use_route_match' => true,
      'pages' => array(
        'bar' => array(
          'label' => 'Bar',
          'route' => 'foo/bar',
          'use_route_match' => true,
        ),
      ),
    ),
  ),
),

Within this application, you want to enable a new page “Baz” which is a child of Foo. You could create (with Soflomo\Prototype v0.1.0) a page like this:

'soflomo_prototype' => array(
  'pages' => array(
    'foo-baz' => array(
      'route'    => '/foo/baz',
      'template' => 'mockups/foo-baz',
    ),
  ),
),
'navigation' => array(
  'default' => array(
    'foo' => array(
      'pages' => array(
        'baz' => array(
          'label' => 'Baz',
          'route' => 'foo-baz',
        ),
      ),
    ),
  ),
),

But this will break.

Now, if you visit /foo/1 first, you see the childs Bar and Baz in your navigation. Clicking on Bar will let you go to /foo/1/bar. The id parameter (1) is kept due to the use_route_match key. Now if you click on Baz, the url is /foo/baz. See, you have lost the id parameter? You will get an exception: the navigation component is unable to render the menu for Foo and Bar because it doesn’t have an id parameter anymore.

If you change the Baz page as follows:

'soflomo_prototype' => array(
  'pages' => array(
    'foo-baz' => array(
      // Set the type and add the :id paramater
      'type'     => 'segment',
      'route'    => '/foo/:id/baz',
      'template' => 'mockups/foo-baz',
    ),
  ),
),
'navigation' => array(
  'default' => array(
    'foo' => array(
      'pages' => array(
        'baz' => array(
          'label' => 'Baz',
          'route' => 'foo-baz',

          // Add this use_route_match
          'use_route_match' => true,
        ),
      ),
    ),
  ),
),

The route is set to the type segment with the id parameter in the page. The navigation is updated as well to reuse the routematch parameters to build the navigation.

Try again, from the Bar page to the Baz page you will go to /foo/1/baz. Your id parameter is kept, the navigation can render the page so if you need to get back into your application, the navigation takes you to /foo/1 and /foo/1/bar. Great!