ivo/ponzi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

adding doc routes.

Browse Source
This commit is contained in:
Taylor Otwell
2012-04-02 11:02:09 -05:00
parent 2a49787e46
commit 6dd8063646
47 changed files with 6799 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
storage/documentation/views/assets.md Normal file
View File

@@ -0,0 +1,73 @@
# Managing Assets
## Contents
- [Registering Assets](#registering-assets)
- [Dumping Assets](#dumping-assets)
- [Asset Dependencies](#asset-dependencies)
- [Asset Containers](#asset-containers)
- [Bundle Assets](#bundle-assets)
<a name="registering-assets"></a>
## Registering Assets
The **Asset** class provides a simple way to manage the CSS and JavaScript used by your application. To register an asset just call the **add** method on the **Asset** class:
#### Registering an asset:
Asset::add('jquery', 'js/jquery.js');
The **add** method accepts three parameters. The first is the name of the asset, the second is the path to the asset relative to the **public** directory, and the third is a list of asset dependencies (more on that later). Notice that we did not tell the method if we were registering JavaScript or CSS. The **add** method will use the file extension to determine the type of file we are registering.
<a name="dumping-assets"></a>
## Dumping Assets
When you are ready to place the links to the registered assets on your view, you may use the **styles** or **scripts** methods:
#### Dumping assets into a view:
<head>
<?php echo Asset::styles(); ?>
<?php echo Asset::scripts(); ?>
</head>
<a name="asset-dependencies"></a>
## Asset Dependencies
Sometimes you may need to specify that an asset has dependencies. This means that the asset requires other assets to be declared in your view before it can be declared. Managing asset dependencies couldn't be easier in Laravel. Remember the "names" you gave to your assets? You can pass them as the third parameter to the **add** method to declare dependencies:
#### Registering a bundle that has dependencies:
Asset::add('jquery-ui', 'js/jquery-ui.js', 'jquery');
In this example, we are registering the **jquery-ui** asset, as well as specifying that it is dependent on the **jquery** asset. Now, when you place the asset links on your views, the jQuery asset will always be declared before the jQuery UI asset. Need to declare more than one dependency? No problem:
#### Registering an asset that has multiple dependencies:
Asset::add('jquery-ui', 'js/jquery-ui.js', array('first', 'second'));
<a name="asset-containers"></a>
## Asset Containers
To increase response time, it is common to place JavaScript at the bottom of HTML documents. But, what if you also need to place some assets in the head of your document? No problem. The asset class provides a simple way to manage asset **containers**. Simply call the **container** method on the Asset class and mention the container name. Once you have a container instance, you are free to add any assets you wish to the container using the same syntax you are used to:
#### Retrieving an instance of an asset container:
Asset::container('footer')->add('example', 'js/example.js');
#### Dumping that assets from a given container:
echo Asset::container('footer')->scripts();
<a name="bundle-assets"></a>
## Bundle Assets
Before learning how to conveniently add and dump bundle assets, you may wish to read the documentation on [creating and publishing bundle assets](/docs/bundles#bundle-assets).
When registering assets, the paths are typically relative to the **public** directory. However, this is inconvenient when dealing with bundle assets, since they live in the **public/bundles** directory. But, remember, Laravel is here to make your life easier. So, it is simple to specify the bundle which the Asset container is managing.
#### Specifying the bundle the asset container is managing:
Asset::container('foo')->bundle('admin');
Now, when you add an asset, you can use paths relative to the bundle's public directory. Laravel will automatically generate the correct full paths.

153
storage/documentation/views/forms.md Normal file
View File

@@ -0,0 +1,153 @@
# Building Forms
## Contents
- [Opening A Form](#opening-a-form)
- [CSRF Protection](#csrf-protection)
- [Labels](#labels)
- [Text, Text Area, Password & Hidden Fields](#text)
- [Checkboxes and Radio Buttons](#checkboxes-and-radio-buttons)
- [Drop-Down Lists](#drop-down-lists)
- [Buttons](#buttons)
- [Custom Macros](#custom-macros)
> **Note:** All input data displayed in form elements is filtered through the HTML::entities method.
<a name="opening-a-form"></a>
## Opening A Form
#### Opening a form to POST to the current URL:
echo Form::open();
#### Opening a form using a given URI and request method:
echo Form::open('user/profile', 'PUT');
#### Opening a Form that POSTS to a HTTPS URL:
echo Form::open_secure('user/profile');
#### Specifying extra HTML attributes on a form open tag:
echo Form::open('user/profile', 'POST', array('class' => 'awesome'));
#### Opening a form that accepts file uploads:
echo Form::open_for_files('users/profile');
#### Opening a form that accepts file uploads and uses HTTPS:
echo Form::open_secure_for_files('users/profile');
#### Closing a form:
echo Form::close();
<a name="csrf-protection"></a>
## CSRF Protection
Laravel provides an easy method of protecting your application from cross-site request forgeries. First, a random token is placed in your user's session. Don't sweat it, this is done automatically. Next, use the token method to generate a hidden form input field containing the random token on your form:
#### Generating a hidden field containing the session's CSRF token:
echo Form::token();
#### Attaching the CSRF filter to a route:
Route::post('profile', array('before' => 'csrf', function()
{
//
}));
#### Retrieving the CSRF token string:
$token = Session::token();
> **Note:** You must specify a session driver before using the Laravel CSRF protection facilities.
*Further Reading:*
- [Route Filters](/docs/routing#filters)
- [Cross-Site Request Forgery](http://en.wikipedia.org/wiki/Cross-site_request_forgery)
<a name="labels"></a>
## Labels
#### Generating a label element:
echo Form::label('email', 'E-Mail Address');
#### Specifying extra HTML attributes for a label:
echo Form::label('email', 'E-Mail Address', array('class' => 'awesome'));
> **Note:** After creating a label, any form element you create with a name matching the label name will automatically receive an ID matching the label name as well.
<a name="text"></a>
## Text, Text Area, Password & Hidden Fields
#### Generate a text input element:
echo Form::text('username');
#### Specifying a default value for a text input element:
echo Form::text('email', 'example@gmail.com');
> **Note:** The *hidden* and *textarea* methods have the same signature as the *text* method. You just learned three methods for the price of one!
#### Generating a password input element:
echo Form::password('password');
<a name="checkboxes-and-radio-buttons"></a>
## Checkboxes and Radio Buttons
#### Generating a checkbox input element:
echo Form::checkbox('name', 'value');
#### Generating a checkbox that is checked by default:
echo Form::checkbox('name', 'value', true);
> **Note:** The *radio* method has the same signature as the *checkbox* method. Two for one!
<a name="drop-down-lists"></a>
## Drop-Down Lists
#### Generating a drop-down list from an array of items:
echo Form::select('size', array('L' => 'Large', 'S' => 'Small'));
#### Generating a drop-down list with an item selected by default:
echo Form::select('size', array('L' => 'Large', 'S' => 'Small'), 'S');
<a name="buttons"></a>
## Buttons
#### Generating a submit button element:
echo Form::submit('Click Me!');
> **Note:** Need to create a button element? Try the *button* method. It has the same signature as *submit*.
<a name="custom-macros"></a>
## Custom Macros
It's easy to define your own custom Form class helpers called "macros". Here's how it works. First, simply register the macro with a given name and a Closure:
#### Registering a Form macro:
Form::macro('my_field', function()
{
return '<input type="awesome">';
});
Now you can call your macro using its name:
#### Calling a custom Form macro:
echo Form::my_field();

241
storage/documentation/views/home.md Normal file
View File

@@ -0,0 +1,241 @@
# Views & Responses
## Contents
- [The Basics](#the-basics)
- [Binding Data To Views](#binding-data-to-views)
- [Nesting Views](#nesting-views)
- [Named Views](#named-views)
- [View Composers](#view-composers)
- [Redirects](#redirects)
- [Redirecting With Flash Data](#redirecting-with-flash-data)
- [Downloads](#downloads)
- [Errors](#errors)
<a name="the-basics"></a>
## The Basics
Views contain the HTML that is sent to the person using your application. By separating your view from the business logic of your application, your code will be cleaner and easier to maintain.
All views are stored within the **application/views** directory and use the PHP file extension. The **View** class provides a simple way to retrieve your views and return them to the client. Let's look at an example!
#### Creating the view:
<html>
I'm stored in views/home/index.php!
</html>
#### Returning the view from a route:
Route::get('/', function()
{
return View::make('home.index');
});
#### Returning the view from a controller:
public function action_index()
{
return View::make('home.index');
});
Sometimes you will need a little more control over the response sent to the browser. For example, you may need to set a custom header on the response, or change the HTTP status code. Here's how:
#### Returning a custom response:
Route::get('/', function()
{
$headers = array('foo' => 'bar');
return Response::make('Hello World!', 200, $headers);
});
#### Returning a custom response containing a view:
return Response::view('home', 200, $headers);
<a name="binding-data-to-views"></a>
## Binding Data To Views
Typically, a route or controller will request data from a model that the view needs to display. So, we need a way to pass the data to the view. There are several ways to accomplish this, so just pick the way that you like best!
#### Binding data to a view:
Route::get('/', function()
{
return View::make('home')->with('name', 'James');
});
#### Accessing the bound data within a view:
<html>
Hello, <?php echo $name; ?>.
</html>
#### Chaining the binding of data to a view:
View::make('home')
->with('name', 'James')
->with('votes', 25);
#### Passing an array of data to bind data:
View::make('home', array('name' => 'James'));
#### Using magic methods to bind data:
$view->name = 'James';
$view->email = 'example@example.com';
#### Using the ArrayAccess interface methods to bind data:
$view['name'] = 'James';
$view['email'] = 'example@example.com';
<a name="nesting-views"></a>
## Nesting Views
Often you will want to nest views within views. Nested views are sometimes called "partials", and help you keep views small and modular.
#### Binding a nested view using the "nest" method:
View::make('home')->nest('footer', 'partials.footer');
#### Passing data to a nested view:
$view = View::make('home');
$view->nest('content', 'orders', array('orders' => $orders));
Sometimes you may wish to directly include a view from within another view. You can use the **render** helper function:
#### Using the "render" helper to display a view:
<div class="content">
<?php echo render('user.profile'); ?>
</div>
It is also very common to have a partial view that is responsible for display an instance of data in a list. For example, you may create a partial view responsible for displaying the details about a single order. Then, for example, you may loop through an array of orders, rendering the partial view for each order. This is made simpler using the **render_each** helper:
#### Rendering a partial view for each item in an array:
<div class="orders">
<?php echo render_each('partials.order', $orders, 'order');
</div>
The first argument is the name of the partial view, the second is the array of data, and the third is the variable name that should be used when each array item is passed to the partial view.
<a name="named-views"></a>
## Named Views
Named views can help to make your code more expressive and organized. Using them is simple:
#### Registering a named view:
View::name('layouts.default', 'layout');
#### Getting an instance of the named view:
return View::of('layout');
#### Binding data to a named view:
return View::of('layout', array('orders' => $orders));
<a name="view-composers"></a>
## View Composers
Each time a view is created, its "composer" event will be fired. You can listen for this event and use it to bind assets and common data to the view each time it is created. A common use-case for this functionality is a side-navigation partial that shows a list of random blog posts. You can nest your partial view by loading it in your layout view. Then, define a composer for that partial. The composer can then query the posts table and gather all of the necessary data to render your view. No more random logic strewn about! Composers are typically defined in **application/routes.php**. Here's an example:
#### Register a view composer for the "home" view:
View::composer('home', function($view)
{
$view->nest('footer', 'partials.footer');
});
Now each time the "home" view is created, an instance of the View will be passed to the registered Closure, allowing you to prepare the view however you wish.
> **Note:** A view can have more than one composer. Go wild!
<a name="redirects"></a>
## Redirects
It's important to note that both routes and controllers require responses to be returned with the 'return' directive. Instead of calling "Redirect::to()"" where you'd like to redirect the user. You'd instead use "return Redirect::to()". This distinction is important as it's different than most other PHP frameworks and it could be easy to accidentally overlook the importance of this practice.
#### Redirecting to another URI:
return Redirect::to('user/profile');
#### Redirecting with a specific status:
return Redirect::to('user/profile', 301);
#### Redirecting to a secure URI:
return Redirect::to_secure('user/profile');
#### Redirecting to the root of your application:
return Redirect::home();
#### Redirecting back to the previous action:
return Redirect::back();
#### Redirecting to a named route:
return Redirect::to_route('profile');
#### Redirecting to a controller action:
return Redirect::to_action('home@index');
Sometimes you may need to redirect to a named route, but also need to specify the values that should be used instead of the route's URI wildcards. It's easy to replace the wildcards with proper values:
#### Redirecting to a named route with wildcard values:
return Redirect::to_route('profile', array($username));
#### Redirecting to an action with wildcard values:
return Redirect::to_action('user@profile', array($username));
<a name="redirecting-with-flash-data"></a>
## Redirecting With Flash Data
After a user creates an account or signs into your application, it is common to display a welcome or status message. But, how can you set the status message so it is available for the next request? Use the with() method to send flash data along with the redirect response.
return Redirect::to('profile')->with('status', 'Welcome Back!');
You can access your message from the view with the Session get method:
$status = Session::get('status');
*Further Reading:*
- *[Sessions](/docs/session/config)*
<a name="downloads"></a>
## Downloads
#### Sending a file download response:
return Response::download('file/path.jpg');
#### Sending a file download and assigning a file name:
return Response::download('file/path.jpg', 'photo.jpg');
<a name="errors"></a>
## Errors
To generating proper error responses simply specify the response code that you wish to return. The corresponding view stored in **views/error** will automatically be returned.
#### Generating a 404 error response:
return Response::error('404');
#### Generating a 500 error response:
return Response::error('500');

139
storage/documentation/views/html.md Normal file
View File

@@ -0,0 +1,139 @@
# Building HTML
## Content
- [Entities](#entities)
- [Scripts And Style Sheets](#scripts-and-style-sheets)
- [Links](#links)
- [Links To Named Routes](#links-to-named-routes)
- [Links To Controller Actions](#links-to-controller-actions)
- [Mail-To Links](#mail-to-links)
- [Images](#images)
- [Lists](#lists)
- [Custom Macros](#custom-macros)
<a name="entities"></a>
## Entities
When displaying user input in your Views, it is important to convert all characters which have signifance in HTML to their "entity" representation.
For example, the < symbol should be converted to its entity representation. Converting HTML characters to their entity representation helps protect your application from cross-site scripting:
#### Converting a string to its entity representation:
echo HTML::entities('<script>alert('hi');</script>');
#### Using the "e" global helper:
echo e('<script>alert('hi');</script>');
<a name="scripts-and-style-sheets"></a>
## Scripts And Style Sheets
#### Generating a reference to a JavaScript file:
echo HTML::script('js/scrollTo.js');
#### Generating a reference to a CSS file:
echo HTML::style('css/common.css');
#### Generating a reference to a CSS file using a given media type:
echo HTML::style('css/common.css', 'print');
*Further Reading:*
- *[Managing Assets](/docs/views/assets)*
<a name="links"></a>
## Links
#### Generating a link from a URI:
echo HTML::link('user/profile', 'User Profile');
#### Generating a link that should use HTTPS:
echo HTML::secure_link('user/profile', 'User Profile');
#### Generating a link and specifying extra HTML attributes:
echo HTML::link('user/profile', 'User Profile', array('id' => 'profile_link'));
<a name="links-to-named-routes"></a>
## Links To Named Routes
#### Generating a link to a named route:
echo HTML::link_to_route('profile');
#### Generating a link to a named route with wildcard values:
$url = HTML::link_to_route('profile', array($username));
*Further Reading:*
- *[Named Routes](/docs/routing#named-routes)*
<a name="links-to-controller-actions"></a>
## Links To Controller Actions
#### Generating a link to a controller action:
echo HTML::link_to_action('home@index');
### Generating a link to a controller action with wildcard values:
echo HTML::link_to_action('user@profile', array($username));
<a name="mail-to-links"></a>
## Mail-To Links
The "mailto" method on the HTML class obfuscates the given e-mail address so it is not sniffed by bots.
#### Creating a mail-to link:
echo HTML::mailto('example@gmail.com', 'E-Mail Me!');
#### Creating a mail-to link using the e-mail address as the link text:
echo HTML::mailto('example@gmail.com');
<a name="images"></a>
## Images
#### Generating an HTML image tag:
echo HTML::image('img/smile.jpg', $alt_text);
#### Generating an HTML image tag with extra HTML attributes:
echo HTML::image('img/smile.jpg', $alt_text, array('id' => 'smile'));
<a name="lists"></a>
## Lists
#### Creating lists from an array of items:
echo HTML::ol(array('Get Peanut Butter', 'Get Chocolate', 'Feast'));
echo HTML::ul(array('Ubuntu', 'Snow Leopard', 'Windows'));
<a name="custom-macros"></a>
## Custom Macros
It's easy to define your own custom HTML class helpers called "macros". Here's how it works. First, simply register the macro with a given name and a Closure:
#### Registering a HTML macro:
HTML::macro('my_element', function()
{
return '<article type="awesome">';
});
Now you can call your macro using its name:
#### Calling a custom HTML macro:
echo HTML::my_element();

104
storage/documentation/views/pagination.md Normal file
View File

@@ -0,0 +1,104 @@
# Pagination
## Contents
- [The Basics](#the-basics)
- [Using The Query Builder](#using-the-query-builder)
- [Appending To Pagination Links](#appending-to-pagination-links)
- [Creating Paginators Manually](#creating-paginators-manually)
- [Pagination Styling](#pagination-styling)
<a name="the-basics"></a>
## The Basics
Laravel's paginator was designed to reduce the clutter of implementing pagination.
<a name="using-the-query-builder"></a>
## Using The Query Builder
Let's walk through a complete example of paginating using the [Fluent Query Builder](/docs/database/fluent):
#### Pull the paginated results from the query:
$orders = DB::table('orders')->paginate($per_page);
#### Display the results in a view:
<?php foreach ($orders->results as $order): ?>
<?php echo $order->id; ?>
<?php endforeach; ?>
#### Generate the pagination links:
<?php echo $orders->links(); ?>
The links method will create an intelligent, sliding list of page links that looks something like this:
Previous 1 2 ... 24 25 26 27 28 29 30 ... 78 79 Next
The Paginator will automatically determine which page you're on and update the results and links accordingly.
It's also possible to generate "next" and "previous" links:
#### Generating simple "previous" and "next" links:
<?php echo $orders->previous().' '.$orders->next(); ?>
*Further Reading:*
- *[Fluent Query Builder](/docs/database/fluent)*
<a name="appending-to-pagination-links"></a>
## Appending To Pagination Links
You may need to add more items to the pagination links' query strings, such as the column your are sorting by.
#### Appending to the query string of pagination links:
<?php echo $orders->appends(array('sort' => 'votes'))->links();
This will generate URLs that look something like this:
http://example.com/something?page=2&sort=votes
<a name="creating-paginators-manually"></a>
## Creating Paginators Manually
Sometimes you may need to create a Paginator instance manually, without using the query builder. Here's how:
#### Creating a Paginator instance manually:
$orders = Paginator::make($orders, $total, $per_page);
<a name="pagination-styling"></a>
## Pagination Styling
All pagination link elements can be style using CSS classes. Here is an example of the HTML elements generated by the links method:
<div class="pagination">
<a href="foo" class="previous_page">Previous</a>
<a href="foo">1</a>
<a href="foo">2</a>
<span class="dots">...</span>
<a href="foo">11</a>
<a href="foo">12</a>
<span class="current">13</span>
<a href="foo">14</a>
<a href="foo">15</a>
<span class="dots">...</span>
<a href="foo">25</a>
<a href="foo">26</a>
<a href="foo" class="next_page">Next</a>
</div>
When you are on the first page of results, the "Previous" link will be disabled. Likewise, the "Next" link will be disabled when you are on the last page of results. The generated HTML will look like this:
<span class="disabled prev_page">Previous</span>

153
storage/documentation/views/templating.md Normal file
View File

@@ -0,0 +1,153 @@
# Templating
## Contents
- [The Basics](#the-basics)
- [Sections](#sections)
- [Blade Template Engine](#blade-template-engine)
- [Blade Layouts](#blade-layouts)
<a name="the-basics"></a>
## The Basics
Your application probably uses a common layout across most of its pages. Manually creating this layout within every controller action can be a pain. Specifying a controller layout will make your develompent much more enjoyable. Here's how to get started:
#### Specify a "layout" property on your controller:
class Base_Controller extends Controller {
public $layout = 'layouts.common';
}
#### Access the layout from the controllers' action:
public function action_profile()
{
$this->layout->nest('content', 'user.profile');
}
> **Note:** When using layouts, actions do not need to return anything.
<a name="sections"></a>
## Sections
View sections provide a simple way to inject content into layouts from nested views. For example, perhaps you want to inject a nested view's needed JavaScript into the header of your layout. Let's dig in:
#### Creating a section within a view:
<?php Section::start('scripts'); ?>
<script src="jquery.js"></script>
<?php Section::stop(); ?>
#### Rendering the contents of a section:
<head>
<?php echo Section::yield('scripts'); ?>
</head>
#### Using Blade short-cuts to work with sections:
@section('scripts')
<script src="jquery.js"></script>
@endsection
<head>
@yield('scripts')
</head>
<a name="blade-template-engine"></a>
## Blade Template Engine
Blade makes writing your views pure bliss. To create a blade view, simply name your view file with a ".blade.php" extension. Blade allows you to use beautiful, unobtrusive syntax for writing PHP control structures and echoing data. Here's an example:
#### Echoing a variable using Blade:
Hello, {{$name}}.
#### Rendering a view:
<h1>Profile</hi>
@include('user.profile')
> **Note:** When using the **@include** Blade expression, the view will automatically inherit all of the current view data.
#### Creating loops using Blade:
<h1>Comments</h1>
@foreach ($comments as $comment)
The comment body is {{$comment->body}}.
@endforeach
#### Other Blade control structures:
@if (count($comments) > 0)
I have comments!
@else
I have no comments!
@endif
@for ($i =0; $i < count($comments) - 1; $i++)
The comment body is {{$comments[$i]}}
@endfor
@while ($something)
I am still looping!
@endwhile
#### The "for-else" control structure:
@forelse ($posts as $post)
{{ $post->body }}
@empty
There are not posts in the array!
@endforelse
<a name="blade-layouts"></a>
## Blade Layouts
Not only does Blade provide clean, elegant syntax for common PHP control structures, it also gives you a beautiful method of using layouts for your views. For example, perhaps your application uses a "master" view to provide a common look and feel for your application. It may look something like this:
<html>
<ul class="navigation">
@section('navigation')
<li>Nav Item 1</li>
<li>Nav Item 2</li>
@yield_section
</ul>
<div class="content">
@yield('content')
</div>
</html>
Notice the "content" section being yielded. We need to fill this section with some text, so let's make another view that uses this layout:
@layout('master')
@section('content')
Welcome to the profile page!
@endsection
Great! Now, we can simply return the "profile" view from our route:
return View::make('profile');
The profile view will automatically use the "master" template thanks to Blade's **@layout** expression.
Sometimes you may want to only append to a section of a layout rather than overwrite it. For example, consider the navigation list in our "master" layout. Let's assume we just want to append a new list item. Here's how to do it:
@layout('master')
@section('navigation')
@parent
<li>Nav Item 3</li>
@endsection
@section('content')
Welcome to the profile page!
@endsection
Notice the **@parent** Blade construct? It will be replaced with the contents of the layout's navigation section, providing you with a beautiful and powerful method of performing layout extension and inheritance.