# Routing From Config

Construct allows you to set up routes in your config file and set various variables, or run your own PHP functions. If the route matches a Node and you have set specific items (such as the entry ID), it will override that item for that Node and will not be available in the Control Panel to edit.

The config item is $config['construct_routes] and takes an array. Each array key is the route you wish to match.

$config['construct_routes'] = array(
    ':before' => array(
        'logic' => function($routing) {
            $route->setGlobal('routing:my_var', 'my_var_value');
        }
    ),
    ':home' => array(
        'template' => 'site/_index'
        'entryId' => 2
    ),
    'blog/:pagination' => array(
        'template' => 'blog/_index',
        'listingEntryTemplate' => 'blog/_entry'
    )
    'news' => array(
        'logic' => function($routing) {
            // do stuff here
        }
    )
);

# Route Keys

Use the route keys in your construct_routes array to match URI segments. Construct makes several special commonly used route keys available that run regex on your route behind the scene.

Each route key value should be an array.

# my/uri

The basic principle is that you use the array keys to match the route.

# :before

This route key runs before any other route allowing you to set defaults or other things.

# :home

This route key matches the home page.

# :pagination

Matches a pagination segment. So you might do something like blog/:pagination.

# :any

Matches any segment.

# :all

Matches all segments.

# :num

Matches a numeric segment.

# :year

Matches a four digit year.

# :month

Matches a two digit month.

# :day

Matches a two digit day.

# Custom Regex

Construct Routes are really just running regex against your current URI and you can include your own regex.

So for instance, instead of using :day or :month, you could instead do this: blog/(\d{2})/(\d{2}). That would be equivalent to blog/:month/:day. Of course in this case, that regex is built in with the special route keys in a much more readable way, but the ability to perform your own regex is there.

# Setting Variables

There are a number of items you can set within a route key. These items will override the Node for this route if there is one. It will also hide those items to users in the Control Panel.

# template => 'site/_my-template'

Set the template being served.

# 'entryId'=> 231

Set the entry ID variable.

# 'pagination' => 6

Set the number of pagination items.

# 'listingChannels' => 'blog|news'

Set the listing channels.

# listingEntryTemplate' => true

This only takes a boolean to hide the Control Panel item when editing the Node for this route. You would still need to do your own route matching for the entry and set the template there.

# 'listingCategoryTemplate' => true

The same applies to this item.

# Routing Logic

There is one additional item you can set in your route key. The key is logic and the value of that key would be a function. This function will be run if your route is matched.

$config['construct_routes'] = array(
    'my/route/:pagination' => array(
        'logic' => function($routing, $path, $pagination) {
            // do stuff here
        }
    )
);

# Arguments

The logic function receives various arguments. The first argument will always be the Routing object that you can use to do various things.

# The Routing Object

The routing object offers you a number of helpful options like set the template, or the entry ID, or check what they are already set to.

# $routing->get('template')

The get() method let’s you check the value of any predefined Construct variables (such as the template as you see in the example above). You can get any of the settings variables in the section above.

# $routing->setTemplate('group/template')

As indicated, you can set the template with this method.

You must declare template => true in your route key to set this item.

$config['construct_routes'] = array(
    'my/route' => array(
        'logic' => function($routing) {
            $routing->setTemplate('group/template');
        },
        'template' => true
    )
);

# $routing->setEntryId(389)

Set the Construct entry id.

You must declare entryId => true in your route key to set this item.

$config['construct_routes'] = array(
    'my/route' => array(
        'logic' => function($routing) {
            $routing->setEntryId(389);
        },
        'entryId' => true
    )
);

# $routing->setPagination(18)

Set the pagination.

You must declare pagination => true in your route key to set this item.

$config['construct_routes'] = array(
    'my/route' => array(
        'logic' => function($routing) {
            $routing->setPagination(18);
        },
        'pagination' => true
    )
);

# $routing->setlistingChannels('blog|news')

Set the listing channels.

You must declare listingChannels => true in your route key to set this item.

$config['construct_routes'] = array(
    'my/route' => array(
        'logic' => function($routing) {
            $$routing->setlistingChannels('blog|news');
        },
        'listingChannels' => true
    )
);

# $routing->set404()

This tell ExpressionEngine to show the 404 error page.

# $routing->setStop()

This prevents any further routes in the construct_routes array from being evaluated.

# $routing->setGlobal('my_global', 'my_value')

The setGlobal() method allows you to set variables which will be available in your template.

{my_global}

# $routing->setPair()

The setPair() method takes two arguments, the first is the name of the pair you are setting, the second an array of variables for the tag pair to parse.

$routing->setPair('my_pair', array(
    0 => array(
        'my_var' => 'my_value'
    ),
    1 => array(
        'my_var' => 'another_value'
    )
));

Use the route_pair tag to retrieve that tag pair in your template:

{exp:construct:route_pair name="my_pair"}
    {my_var}
{/exp:construct:route_pair}

The route_pair tag is running ExpressionEngine’s native tag parsing methods and uses the array you set to parse the variables, so you can nest variables or do anything with the array you would do in any ExpressionEngine tag pair.

# Matches

Any arguments after the $routing object are determined by your route. Each of the regex matches are passed into your function as arguments. For instance, a route key of news/blog/:pagination would have three arguments, the $routing object, the first match of news/blog, and the second match of the pagination segment.

$config['construct_routes'] = array(
    'news/blog/:pagination' => array(
        'logic' => function($routing, $val, $page) {
            var_dump($val, $page);
        }
    )
);