Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

documentation page now links to CPAN instead of providing a bad rewri…

…ting the PODs
  • Loading branch information...
commit 7928c03b13a697c4884e3f7b40e5d26381ea127c 1 parent 8db128e
Alexis Sukrieh authored
Showing with 14 additions and 550 deletions.
  1. +1 −1  public/css/style.css
  2. +12 −548 views/documentation.tt
  3. +1 −1  views/download.tt
View
2  public/css/style.css
@@ -147,7 +147,7 @@ p {
font-family:'georgia','bitstream vera serif',serif;
font-size: 16px;
margin-right: 10px;
- width: 700px;
+ width: 650px;
}
code, pre {
View
560 views/documentation.tt
@@ -1,559 +1,23 @@
<h2>Dancer's Documentation</h2>
<p>
-This documentation was written for Dancer <a
-href="http://search.cpan.org/~sukria/Dancer-0.9904/">0.9004</a>
-</p>
-
-<h3>Contents</h3>
-
-<ol>
-<li><a href="#usage">Usage</a></li>
-<li><a href="#named-matching">Named Matching</a></li>
-<li><a href="#wildcard-matching">Wildcards Matching</a></li>
-<li><a href="#regexp-matching">Regular-Expression Matching</a></li>
-<li><a href="#running">Running the Webserver</a></li>
-<li><a href="#skipping">Action Skipping</a></li>
-<li><a href="#response">Action Responses</a></li>
-<li><a href="#errors">Errors Handling</a></li>
-<li><a href="#before">Before Filters</a></li>
-<li><a href="#configuration">Configuration and Environments</a></li>
-<li><a href="#logging">Logging</a></li>
-<li><a href="#views">Views</a></li>
-<li><a href="#static">Static Files</a></li>
-<li><a href="#settings">Settings</a></li>
-<li><a href="#dependencies">Dependencies</a></li>
-</ol>
-
-<a name="usage"> <h3>Usage</h3></a>
-
-<p>
-As soon as Dancer is imported to a script, that script becomes a webapp. All
-the script has to do is to declare a list of routes. A route handler is
-composed by an HTTP method, a path pattern and a code block.
-</p>
-
-<p>
-The code block given to the route handler has to return a string which will be
-used as the content to render to the client.
-</p>
-
-<p>
-Routes are defined for a given HTTP method (get or post). For each method
-supported, a keyword is exported by the module.
-</p>
-
-<p>
-Here is an example of a route definition:
-</p>
+The documentation is available on
+<a href="http://search.cpan.org/dist/Dancer/">Dancer's CPAN page</a>.
-<pre class="prettyprint">
- get '/hello/:name' => sub {
- # do something important here
-
- return "Hello ".params->{name};
- };
-</pre>
-
-<p>
-The route is defined for the method <code>get</code>, so only GET requests will be honoured
-by that route.
-</p>
-
-<p>
-The route action is the code reference declared, it can access parameters through
-the `params' keyword, which returns an hashref.
-This hashref is a merge of the route pattern matches and the request params.
-</p>
-
-<p>
-Below are all the possible ways to define a route, note that it is not
-possible to mix them up. Don't expect to have a working application if you mix
-different kinds of route!
-</p>
-
-<a name="named-matching"> <h3>Named Matching</h3></a>
-
-<p>
-A route pattern can contain one or more tokens (a word prefixed with ':'). Each
-token found in a route pattern is used as a named-pattern match. Any match will
-be set in the params hashref.
-</p>
-
-
-<pre class="prettyprint">
- get '/hello/:name' => sub {
- "Hey ".params->{name}.", welcome here!";
- };
-</pre>
-
-<a name="wildcard-matching"> <h3>WILDCARDS MATCHING </h3></a>
-
-<p>
-A route can contain a wildcard (represented by a '*'). Each wildcard match will
-be returned in an arrayref, accessible via the `splat' keyword.
-</p>
-
-
-<pre class="prettyprint">
- get '/download/*.*' => sub {
- my ($file, $ext) = splat;
- # do something with $file.$ext here
- };
-</pre>
-
-<a name="regexp-matching"> <h3>REGULAR EXPRESSION MATCHING</h3></a>
-
-<p>
-A route can be defined with a Perl regular expression. The syntax is assumed to
-be a classic Perl regexp except for the slashes that will be escaped before
-running the match.
-</p>
-
-<p>
-For instance, don't do <code>'\/hello\/(.+)'</code> but rather:
-<code>'/hello/(.+)'</code>
-</p>
-
-<p>
-In order to tell Dancer to consider the route as a real regexp, the route must
-be defined explicitly with the keyword <code>r</code>, like the following:
-</p>
-
-
-<pre class="prettyprint">
- get r( '/hello/([\w]+)' ) => sub {
- my ($name) = splat;
- return "Hello $name";
- };
-</pre>
-
-<a name="running"> <h3>RUNNING THE WEBSERVER</h3></a>
-
-<p>
-Once the script is ready, you can run the webserver just by running the
-script. The following options are supported:
+The documentation has been divided into sections in order to
+make the reading more confortable.
</p>
<ul>
-
-<li><b>--port=XXXX</b> set the port to listen to (default is 1915)</li>
-
-<li><b>--daemon</b> run the webserver in the background</li>
-
-<li><b>--help</b> display a detailed help message</li>
-
+<li><a href="http://search.cpan.org/dist/Dancer/lib/Dancer.pm">Dancer</a> :
+ the main documentation, explaining all the details you want about Dancer's syntax.</li>
+<li><a href="http://search.cpan.org/dist/Dancer/lib/Dancer/Config.pm">Dancer::Config</a> :
+ details about configuration files for your application</li>
+<li><a href="http://search.cpan.org/dist/Dancer/lib/Dancer/Session.pm">Dancer::Session</a>
+ : detail about session support and usage</li>
</ul>
-<a name="skipping"> <h3>ACTION SKIPPING</h3></a>
-
<p>
-An action can choose not to serve the current request and ask Dancer to process
-the request with the next matching route.
+Even though a special care is given to documentation, there might be some
+errors, so feel free to <a href="/about">contact the development team</a> if you find one.
</p>
-
-<p>
-This is done with the <code>pass</code> keyword, like in the following example
-</p>
-
-
-<pre class="prettyprint">
- get '/say/:word' => sub {
- pass if (params->{word} =~ /^\d+$/);
- "I say a word: ".params->{word};
- };
-
- get '/say/:number' => sub {
- "I say a number: ".params->{number};
- };
-</pre>
-
-<a name="response"> <h3>ACTION RESPONSES</h3></a>
-
-<p>
-The action's return value is always considered to be the content to render. So
-take care to your return value.
-</p>
-
-<p>
-In order to change the default behaviour of the rendering of an action, you can
-use the following keywords.
-</p>
-
-
-<h4>status</h4>
-
-<p>
-By default, an action will produce an <code>HTTP 200 OK</code> status code, meaning
-everything is OK. It's possible to change that with the keyword <code>status</code> :
-</p>
-
-
-<pre class="prettyprint">
- get '/download/:file' => {
- if (! -f params->{file}) {
- status 'not_found';
- return "File does not exist, unable to download";
- }
- # serving the file...
- };
-</pre>
-
-<p>
-In that example, Dancer will notice that the status has changed, and will
-render the response accordingly.
-</p>
-
-<p>
-The status keyword receives the name of the status to render, it can be either
-an HTTP code or its alias, as defined in <code>Dancer::HTTP</code>.
-</p>
-
-<h4>content_type</h4>
-
-<p>
-You can also change the content type rendered in the same maner, with the
-keyword <code>content_type</code>
-</p>
-
-
-<pre class="prettyprint">
- get '/cat/:txtfile' => {
- content_type 'text/plain';
-
- # here we can dump the contents of params->{txtfile}
- };
-</pre>
-
-<a name="errors"><h3>Error handling</h3></a>
-
-<p>
-When an error is renderered (the action responded with a status code different
-than 200), Dancer first looks in the public directory for an HTML file matching
-the error code (eg: 500.html or 404.html).
-</p>
-
-<p>
-If such a file exists, it's used to render the error, otherwise, a default
-error page will be rendered on the fly.
-</p>
-
-<p>
-When an error occurs during the route execution, Dancer will render an error
-page with the HTTP status code 500.
-</p>
-
-<p>
-It's possible either to display the content of the error message or to hide it
-with a generic error page.
-</p>
-
-<p>
-This is a choice left to the end-user and can be set with the
-<code>show_errors</code> setting.
-</p>
-
-<p>
-Note that you can also choose to consider all warnings in your route handlers
-as errors when the setting <code>warnings</code> is set to 1.
-</p>
-
-<a name="before"> <h3>Before filters</h3></a>
-
-<p>
-Before filters are evaluated before each request within the context of the
-request and can modify the request and response. It's possible to define variable
-that will be accessible in the action blocks with the keyword <code>var</code>.
-</p>
-
-
-<pre class="prettyprint">
- before sub {
- var note => 'Hi there';
- request->path_info('/foo/oversee')
- };
-
- get '/foo/*' => sub {
- my ($match) = splat; # 'oversee';
- vars->{note}; # 'Hi there'
- };
-</pre>
-
-<p>
-The request keyword returns the current CGI object representing the incoming request.
-See the documentation of the <code>CGI</code> module for details.
-</p>
-
-<a name="configuration"> <h3>CONFIGURATION AND ENVIRONMENTS</h3></a>
-
-<p>
-Configuring a Dancer application can be done in many ways. The easiest one (and
-maybe the the dirtiest) is to put all your settings statements at the top of
-your script, before calling the dance() method.
-</p>
-
-<p>
-Other ways are possible, you can write all your setting calls in the file
-<code>appdir/config.yml</code>. For this, you must have installed the <code>YAML</code>
-module, and of course, write the conffile in YAML format.
-</p>
-
-<p>
-That's better than the first option, but it's still not
-perfect as you can't switch easily from an environment to another without
-rewriting the <code>config.yml</code> file.
-</p>
-
-<p>
-The better way is to have one config.yml file with default global settings,
-like the following:
-</p>
-
-<pre class="prettyprint">
- # appdir/config.yml
- logger: 'file'
- layout: 'main'
-</pre>
-
-<p>
-And then write as many environment file as you like in <code>appdir/environements</code>.
-That way, the appropriate environment config file will be loaded according to the
-running environment (if none specified, it will be <code>development</code>).
-</p>
-
-<p>
-Note that you can change the running environment using the --environment
-commandline switch.
-</p>
-
-<p>
-Typically, you'll want to set the following values in a development config
-file:
-</p>
-
-<pre class="prettyprint">
- # appdir/environments/development.yml
- log: 'debug'
- access_log: 1
-</pre>
-
-<p>
-And in a production one:
-</p>
-
-<pre class="prettyprint">
- # appdir/environments/production.yml
- log: 'warning'
- access_log: 0
-</pre>
-
-<a name="logging"> <h3>LOGGING</h3></a>
-
-<p>
-It's possible to log messages sent by the application. In the current version,
-only one method is possible for logging messages but it may come in future
-releases new methods.
-</p>
-
-<p>
-In order to enable the logging system for your application, you first have to
-start the logger engine in your config.yml
-</p>
-
-<pre class="prettyprint">
- logger: 'file'
-</pre>
-
-<p>
-Then you can choose which kind of messages you want to actually log:
-</p>
-
-
-<pre class="prettyprint">
- log: 'debug' # will log debug, warning and errors
- log: 'warning' # will log warning and errors
- log: 'error' # will log only errors
-</pre>
-
-<p>
-A directory appdir/logs will be created and will host one logfile per
-environment. The log message contains the time it was written, the PID of the
-current process, the message and the caller information (file and line).
-</p>
-
-<a name="views"> <h3>VIEWS </h3></a>
-
-<p>
-It's possible to render the action's content with a template, this is called a
-view. The `appdir/views' directory is the place where views are located.
-</p>
-
-<p>
-You can change this location by changing the setting <code>views</code>, for instance if
-your templates are located in the <code>templates</code> directory, do the following:
-</p>
-
-
-<pre class="prettyprint">
- set views => path(dirname(__FILE__), 'templates');
-</pre>
-
-<p>
-A view should have a <code>.tt</code> extension and is rendered with the
-<code>Template</code> module. You have to import the `Template' module in your script if
-you want to render views within your actions.
-</p>
-
-<p>
-In order to render a view, just call the 'template' keyword at the end of the
-action by giving the view name and the HASHREF of tokens to interpolate in the
-view (note that all the route params are accessible in the view):
-</p>
-
-
-<pre class="prettyprint">
- use Dancer;
- use Template;
-
- get '/hello/:name' => sub {
- template 'hello' => {var => 42};
- };
-</pre>
-
-<h3>LAYOUTS</h3>
-
-<p>
-A layout is a special view, located in the <code>layouts</code> directory (inside the
-views directory) which must have a token named `content'. That token marks the
-place where to render the action view. This lets you define a global layout for
-your actions.
-</p>
-
-<p>
-A layout can be used like the following:
-</p>
-
-<pre class="prettyprint">
- use Dancer;
- use Template;
-
- layout 'main';
-
- get '/' => sub {
- template 'index';
- };
-</pre>
-
-
-<a name="static"> <h3>STATIC FILES</h3></a>
-
-<p>
-Static files are served from the ./public directory. You can specify a
-different location by setting the <code>public</code> option:
-</p>
-
-
-<pre class="prettyprint">
- set public => path(dirname(__FILE__), 'static');
-</pre>
-
-<p>
-Note that the public directory name is not included in the URL. A file
-<code>./public/css/style.css</code> is made available as
-<code>example.com/css/style.css</code>.
-</p>
-
-<h4>MIME-TYPES CONFIGURATION</h4>
-
-<p>
-By default, Dancer will automatically detect the mime-types to use for
-the static files accessed.
-</p>
-
-<p>
-It's possible to choose specific mime-type per file extensions. For instance,
-we can imagine you want to sever *.foo as a text/foo content, instead of
-text/plain (which would be the content type detected by Dancer if *.foo are
-text files).
-</p>
-
-<pre class="prettyprint">
- mime_type foo => 'text/foo';
-</pre>
-
-<p>
-This configures the 'text/foo' content type for any file matching '*.foo'.
-</p>
-
-<h4>STATIC FILE FROM A ROUTE HANDLER</h4>
-
-<p>
-It's possible for a route handler to pass the batton to a static file, like
-the following.
-</p>
-
-
-<pre class="prettyprint">
- get '/download/*' => sub {
- my $params = shift;
- my ($file) = @{ $params->{splat} };
-
- send_file $file;
- };
-</pre>
-
-<p>
-Or even if you want your index page to be a plain old index.html file, just do:
-</p>
-
-<pre class="prettyprint">
- get '/' => sub {
- send_file '/index.html'
- };
-</pre>
-
-<a name="settings"> <h3>SETTINGS</h3></a>
-
-<p>
-It's possible to change quite every parameter of the application via the
-settings mechanism.
-</p>
-
-<p>
-A setting is key/value pair assigned by the keyword <code>set</code>:
-</p>
-
-
-<pre class="prettyprint">
- set setting_name => 'setting_value';
-</pre>
-
-<a name="dependencies"> <h3>DEPENDENCIES</h3></a>
-
-<p>
-Dancer depends on the following modules:
-</p>
-
-<p>
-The following modules are mandatory (Dancer cannot run without them)
-</p>
-
-<ul>
-<li>HTTP::Server::Simple</li>
-<li>CGI</li>
-<li>File::MimeInfo</li>
-</ul>
-
-<p>
-The following modules are optional
-</p>
-
-<ul>
-<li>Template : needed for the views rendering system</li>
-</ul>
-
-<a name="license"> <h3>LICENSE</h3></a>
-
-This module is free software and is published under the same
-terms as Perl itself.
-
View
2  views/download.tt
@@ -3,7 +3,7 @@
<h3>Releases</h3>
<p>
-Last stable release is <a href="/downloads/Dancer-1.100.tar.gz">1.100</a>, you can
+Last release is <a href="/downloads/Dancer-1.122.tar.gz">1.122</a>, you can
also check out the <a href="http://search.cpan.org/dist/Dancer/">CPAN page</a>.
</p>
Please sign in to comment.
Something went wrong with that request. Please try again.