1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
__END__
=pod
=head1 NAME
Mason::Manual::RequestDispatch - How request paths get mapped to page
components
=head1 DESCRIPTION
Given the request path
/news/sports/hockey
Mason searches for the following components in order, setting $m->path_info as
noted.
/news/sports/hockey.{mp,mc}
/news/sports/hockey/index.{mp,mc}
/news/sports/hockey/dhandler.{mp,mc}
/news/sports/dhandler.{mp,mc} # $m->path_info = hockey
/news/sports.{mp,mc} # $m->path_info = hockey (but see next section)
/news/dhandler.{mp,mc} # $m->path_info = sports/hockey
/news.{mp,mc} # $m->path_info = sports/hockey (but see next section)
/dhandler.{mp,mc} # $m->path_info = news/sports/hockey
where C<< .{mp,mc} >> means either C<.mp> (indicating a I<pure-perl>
component). or C<.mc> (indicating a I<top-level> component).
The following sections describe these elements in more detail.
=head2 Autoextended path
The request path is suffixed with ".mp" and ".mc" to translate it to a
component path.
/news/sports/hockey.{mp,mc}
=head2 Index
An index matches its exact directory, nothing underneath.
/news/sports/hockey/index.{mp,mc}
=head2 Dhandlers
A dhandler matches its directory as well as anything underneath, setting C<<
$m->path_info >> to the remainder.
/news/sports/hockey/dhandler.{mp,mc}
/news/sports/dhandler.{mp,mc} # $m->path_info = hockey
/news/dhandler.{mp,mc} # $m->path_info = sports/hockey
/dhandler.{mp,mc} # $m->path_info = news/sports/hockey
=head2 Partial paths
A component can match an initial part of the URL, setting C<< $m->path_info >>
to the remainder:
/news/sports.{mp,mc} # $m->path_info = hockey
/news.{mp,mc} # $m->path_info = sports/hockey
Since this isn't always desirable behavior, it must be explicitly enabled for
the component. Mason will call method C<allow_path_info> on the component
class, and will only allow the match if it returns true:
<%class>
method allow_path_info { 1 }
</%class>
The default C<allow_path_info> returns false.
C<allow_path_info> is not checked on dhandlers, since the whole point of
dhandlers is to match partial paths.
=head2 Trailing slash
If the request URL has a trailing slash (ends with C</>), we remove it before
the match process begins and add it to the C<< $m->path_info >>. Components
that should match must have C<allow_path_info> return true.
For example:
## request URL /news/
/news/index.{mp,mc} # $m->path_info = / if index.{mp,mc} has
# allow_path_info => true
/news/dhandler.{mp,mc} # $m->path_info = /
/news.{mp,mc} # $m->path_info = / if news.{mp,mc} has
# allow_path_info => true
## request URL /news/sports/
/news/sports/index.{mp,mc} # $m->path_info = / if index.{mp,mc} has
# allow_path_info => true
/news/sports/dhandler.{mp,mc} # $m->path_info = /
/news/sports.{mp,mc} # $m->path_info = / if sports.{mp,mc}
# has allow_path_info => true
/news/dhandler.{mp,mc} # $m->path_info = sports/
/news.{mp,mc} # $m->path_info = /sports/ if news.{mp,mc}
# has allow_path_info => true
=head2 Routes
It is possible to use route syntax to more elegantly parse C<< $m->path_info >>
for dhandlers and partial paths, e.g.
<%class>
route "{year:[0-9]+}/{month:[0-9]{2}}";
</%class>
See L<Mason::Plugin::RouterSimple>.
=head1 SEE ALSO
L<Mason|Mason>
=head1 AUTHOR
Jonathan Swartz <swartz@pobox.com>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Jonathan Swartz.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut
|
