Xtatic is a Laravel bundle to facilitate rapid deployment and easy maintenance of small, static websites.
Copy the Xtatic directory to Laravel’s bundles directory.
Open application/bundles.php and add the following into the returning array.
'xtatic' => array(
'autoloads' => array(
'map' => array('Xtatic' => '(:bundle)/libraries/xtatic.php'),
),
),
Open application/routes.php and add the following route to divert requests to Xtatic.
Route::get(array('/', '(:any)'), function( $slug = NULL )
{
return Xtatic::make( $slug );
});
This route will just respond to GET requests. Passing an array containing / and (:any) ensures that requests to the root URL or any single segment URL will be handled by this route.
The second parameter is a callback function which accepts the first URI segment as the $slug parameter and passes it to the Xtatic class, returning the result.
Configuration parameters for the website are defined in bundles/xtatic/config/xtatic.php. Each item is explained in its preceding comment. Open the file and edit each configuration parameter as required.
The two configuration items which require the most explanation are navigation and pages which are dealt with below.
The navigation configuration parameter is a multidimensional array which defines the structure of the site. Its elements correspond to the navigation menus which appear in the site. Typically these top level elements will have keys like primary-navigation, main-menu, secondary-menu or footer-menu.
Each of these menu elements is also an array and its member elements can be one of three types. Most will be simple string values which correspond to the keys defined on the pages array (explained below).
Sometimes a member element can be a key/value pair. If the value is a string then it is this that will determine the URI of the resulting hyperlink. The element’s key will determine the link text.
Where the value is an array it will be rendered as a submenu.
An example configuration is shown here.
'navigation' => array(
'primary-navigation' => array(
'home',
'about-us',
'products' => array(
'widgets',
'doohickeys',
'thingummy-jigs',
),
'My Blog' => 'http://www.my-blog.com',
'get-in-touch',
),
'footer-navigation' => array(
'home', 'about-us', 'products', 'get-in-touch',
),
),
In the example there are two menus defined on the navigation configuration parameter. The home, about-us and products menu elements will be rendered as internal hyperlinks with link text derived from the value of label on the corresponding element on the pages configuration parameter. On the primary-navigation menu, the products menu element will also contain a submenu comprising menu elements for widgets, doohickeys and thingummy-jigs which are also defined on pages. The My Blog element will be rendered as an external hyperlink with My Blog as the link text.
To render a menu in the view, just pass the menu’s key to the method Xtatic::menu().
<?php echo Xtatic::menu('footer-navigation'); ?>
By default the method will return all the the nested levels of a menu. Passing a second depth parameter to the method will limit the level of returned menus to the depth supplied.
<?php echo Xtatic::menu('primary-navigation', 1); ?>
In this case the menu would only return the first level of elements, excluding the products sub-menu defined on the example configuration. More details on using this and other Xtatic methods is covered below under Public Methods.
The pages configuration parameter is a two dimensional array which defines all the pages in the site. Each has a key which corresponds to its URI slug, and its value is an array of page meta-data.
The default meta-data are as follows.
title defines the value of the HTML title tag. This is important for SEO and should be fewer than 70 characters if possible.
meta_description defines the HTML meta description tag. This may be shown in search results in preference to a sample of text from the body of the page. This should be fewer than 160 characters. A well written meta description can improve click-through rates from searches.
meta_keywords defines the HTML meta keywords tag.
meta-robots defines the HTML meta robots tag. This can provide instructions to web crawlers about how to index your site.
label defines the link text within menu hyperlinks generated by Xtatic.
is_live defines whether the page will appear in Xtatic menus. If set to FALSE then links to the page will not be included in menus generated by Xtatic.
The value of any of these meta-data for the current page can be rendered in the view by calling the method Xtatic::get() and passing the item name as a string.
<?php echo Xtatic::get('label'); ?>
Additional user-defined data items can be defined on the page meta-data and retrieved in the same way.
Xtatic::make( string $slug=NULL )
This method is called in the route. It primes Xtatic with page content and relevant meta-data. Assembles and returns the page view or other appropriate response. Omitting the $slug parameter or passing a null value will revert to the default page defined in the Xtatic configuration. Passing a value not defined on the configuration’s pages element will return a 404 response.
Xtatic::head()
This method is called within the main template view. It assembles and returns HTML head components - namely meta tags, CSS and JavaScript files based on information defined in the configuration file.
Xtatic::tail()
This method is called within the main template view. It returns any inline JavaScript to be rendered before the closing HTML body tag.
Xtatic::content()
This method is called within the main template view. It retrieves and returns the content view which corresponds to the page URI slug. If the view cannot be found then a placeholder view is substituted. Placeholder content is defined in the content_placeholder configuration parameter.
Xtatic::get( string $attribute_name )
Retrieve and return an item defined on the current element of the pages configuration parameter by passing its key to the method. Additionally the method can be used to retrieve the following.
Passing 'slug' returns the current URI slug (or key to the current page).
Passing 'title' returns the value of the page’s meta title wrapper in an HTML <title> element.
Passing 'site_owner' returns the value of the site_owner configuration parameter.
Xtatic::menu( string $root_key=NULL, int $to_depth=NULL, bool $include_root=FALSE, string $list_type='ul' )
Assembles and returns an HTML formatted list element derived from the navigation array specified by the root key passed in to the method. All the method parameters are optional.
$root_key defines the element of the navigations configuration parameter that will be used to generate the menu. If a null value is passed the first element of navigations will be used.
$to_depth defines the depth to which sub-menus will be rendered. If a null value is passed then all sub-menus will be rendered to their full depth.
$include_root determines whether the top level navigation element is included in the menu. If a falsey value is passe then it won’t be.
$list_type determines the HTML list type in which the menu is rendered. If dl or ol are passed then these will used, otherwise an unordered list (or ul) element will be used.
To render the main navigation menu in a view is as simple as calling…
<?php echo Xtatic::menu( 'primary-navigation' ); ?>
If you have a secondary navigation element which features the same elements as the primary navigation but excludes any sub menus then you could call the following.
<?php echo Xtatic::menu( 'primary-navigation', 1 ); ?>
Xtatic::ancestors( string $slug=NULL, bool $include_root=FALSE )
Iterates across the first defined element on the navigations configuration array looking for a key matching the value of $slug. If a match is found then an array of page keys is returned based on their positions in navigations. Array elements are in order of descending seniority.
If a null value is passed in $slug then the slug value of the current page is used.
Xtatic::siblings( string $slug=NULL )
Looks for an element in the navigations configuration array with a key value matching $slug. If a match is found then an array of keys which include sibling elements is returned.
If a null value is passed in $slug then the slug value of the current page is used.
Xtatic::children( string $slug=NULL )
Looks for an element in the `navigations` configuration array with a key value matching `$slug`. If a match is found then an array of keys which include child elements is returned.
If a null value is passed in `$slug` then the slug value of the current page is used.
Xtatic::page_data( string $slug=NULL )
Documentation required.
Xtatic::add_javascript( string $js, bool $in_head=FALSE )
Documentation required.
Xtatic::add_jquery( string $js, bool $in_head=FALSE )
Documentation required.