Skip to content
Browse files

Update LICENSE and add documentation

  • Loading branch information...
1 parent 96ccce8 commit 38011b8de755d68cd6602444cbf2142f39b71a90 Gabriel Evans committed Feb 7, 2012
View
2 LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2011 Gabriel Evans
+Copyright (c) 2011-2012 Gabriel Evans
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
View
23 config/userguide.php
@@ -0,0 +1,23 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+return array(
+ // Leave this alone
+ 'modules' => array(
+
+ // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename'
+ 'partials' => array(
+
+ // Whether this modules userguide pages should be shown
+ 'enabled' => TRUE,
+
+ // The name that should show up on the userguide index page
+ 'name' => 'Partials',
+
+ // A short description of this module, shown on the index page
+ 'description' => 'Documentation for Kohana partials.',
+
+ // Copyright message, shown in the footer for this module
+ 'copyright' => '&copy; 2011-2012 Gabriel Evans',
+ )
+ )
+);
View
4 guide/partials/examples.md
@@ -0,0 +1,4 @@
+# Examples
+
+- [Basic](examples/basic): Basic examples.
+- [Collections](examples/collections): Full example of rendering a list of users with zebra-stripes and spacers.
View
83 guide/partials/examples/basic.md
@@ -0,0 +1,83 @@
+# Basic Examples
+
+These are basic examples of how partials can be used to DRY up views for reuse in other views.
+
+## Layouts
+
+Your application's look and feel is important and being able to maintain it will save you a ton of development time. In this example, we'll outline a basic template that has been split into several smaller partials.
+
+### Main Template
+
+In this case, we're using the default `Controller_Template` class to render our layout with the default `template.php` view. All of the bulk of its content and markup is separated into smaller, easier to maintain files and at the same time, we're able to get an overview of the layout.
+
+ <!-- application/views/template.php -->
+ <html>
+ <head>
+ <?= Partial::factory('template/head') ?>
+ </head>
+ <body>
+
+ <div id="header">
+ <?= Partial::factory('template/header') ?>
+ </div>
+
+ <div id="main">
+ <?= $content ?>
+ </div>
+
+ <div id="footer">
+ <?= Partial::factory('template/footer') ?>
+ </div>
+
+ </body>
+ </html>
+
+### Head
+
+This partial contains the markup we want in the `<head>` of the template. This can range anywhere from stylesheets to javascripts and various meta tags. In the case where multiple templates are being used in an application, you can reuse this partial in other layouts.
+
+ <!-- application/views/template/_head.php -->
+ <meta http-equiv="Content-Type" content="text/html; charset=<?= Kohana::$charset ?>" />
+
+ <title><?= $title ?></title>
+
+ <meta name="keywords" content="" />
+ <meta name="description" content="" />
+
+ <!-- scripts and javascripts -->
+
+### Template Header
+
+Our header contains our site's title, tagline, and main navigation menu.
+
+ <!-- application/views/template/_header.php -->
+ <h1><?= $title ?></h1>
+ <h2><?= $tagline ?></h2>
+
+ <ul id="top-nav">
+ <?= Partial::factory('template/navigation')->collection($navigation, 'item') ?>
+ </ul>
+
+### Navigation
+
+One line for a partial may seem like overkill, but it allows us to keep things simple.
+
+ <!-- application/views/template/_navigation.php -->
+ <li><?= HTML::anchor($item['url'], $item['title']) ?></li>
+
+In this case, when the partial is rendered, it will loop through the specified navigation items and produce markup similar to this:
+
+ <li><a href="/">Home</a></li>
+ <li><a href="/about">About Us</a></li>
+ <li><a href="/contact">Contact Us<</li>
+
+### Template Footer
+
+We're able to reuse the same navigation in our footer:
+
+ <!-- application/views/template/_footer.php -->
+ &copy; 2012 Some Company
+
+ <div id="bottom-nav">
+ <?= Partial::factory('template/navigation')->collection($navigation, 'item')->spacer(' | ') ?>
+ </div>
View
3 guide/partials/examples/collections.md
@@ -0,0 +1,3 @@
+# Collection Examples
+
+*Work in progress...*
View
36 guide/partials/index.md
@@ -0,0 +1,36 @@
+# What are partials?
+
+> Partial templates – usually just called “partials” – are another device for breaking the rendering process into more manageable chunks. With a partial, you can move the code for rendering a particular piece of a response to its own file.
+
+## Basic Usage
+
+Partials let you DRY up your views and split them into smaller pieces. If you're reusing forms on several views, displaying data in similar formats, or facing problems where a simple view turns into a complicated mess, partials can help.
+
+Just as you would use the `View` class, you can use `Partial::factory('path/to/partial')` to render your partials. Partials are very similar to regular views and are stored in the `views/` directory of your application. One difference however, is that these files are prefixed with an underscore. So `Partial::factory('contact/form')` will render `views/contact/_form.php`.
+
+Having an underscore in the filename of your partials makes it easier to assume which views you are reusing and which views are independent. For examples, see the [basic examples](examples/basic) page.
+
+## Collections
+
+This module also includes several shortcuts for rendering lists and collections (for example, a listing of products). Rather than mixing complicated foreach statements into your views:
+
+ // application/views/posts/index.php
+ <?php foreach ($posts as $post): ?>
+ <div>
+ <h2><?= $post->title ?></h2>
+ <?= $post->content ?>
+ </div>
+ <?php endforeach; ?>
+
+Partials will loop over the provided data and eliminate the madness in complex views:
+
+ // application/views/posts/index.php
+ <?= Partial::factory('posts/post')->collection($posts) ?>
+
+ // application/views/posts/_post.php
+ <div>
+ <h2><?= $post->title ?></h2>
+ <?= $post->content ?>
+ </div>
+
+For more examples, see the [collection examples](examples/collections) page.
View
5 guide/partials/menu.md
@@ -0,0 +1,5 @@
+## [Partials]()
+
+- [Examples](examples)
+ - [Basic](examples/basic)
+ - [Collections](examples/collections)

0 comments on commit 38011b8

Please sign in to comment.
Something went wrong with that request. Please try again.