/Laravel-Xtatic

View-based mini-subframework for lazy web developers, all wrapped up in a Laravel bundle

Primary LanguagePHP

Xtatic For Laravel

Easy to use view-based mini-framework for lazy web developers.

Overview

Xtatic is a Laravel bundle to facilitate rapid deployment and easy maintenance of small, static websites.

Installation

Step 1 - Add the files

Copy the Xtatic directory to Laravel’s bundles directory.

Step 2 - Register the Xtatic bundle

Open application/bundles.php and add the following into the returning array.

'xtatic' => array(
	'autoloads' => array(
		'map' => array('Xtatic' => '(:bundle)/libraries/xtatic.php'),
	),
),

Step 3 - Set up a catch-all route

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

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.

Navigation

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.

Pages

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.

How It Works

Public Methods

Make

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.

Head

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.

Tail

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.

Content

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.

Get

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.

Menu

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 ); ?>

Ancestors

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.

Siblings

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.

Children

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.

Page Data

Xtatic::page_data( string $slug=NULL )

Documentation required.

Add JavaScript

Xtatic::add_javascript( string  $js, bool $in_head=FALSE  )

Documentation required.

Add jQuery

Xtatic::add_jquery( string  $js, bool $in_head=FALSE  )

Documentation required.