/[Frey]/trunk/lib/Frey/Manual.pod
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Diff of /trunk/lib/Frey/Manual.pod

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 704 by dpavlin, Wed Dec 3 21:26:29 2008 UTC revision 991 by dpavlin, Sat Jan 10 23:29:38 2009 UTC
# Line 2  Line 2 
2    
3  This page describes how to use and develop with L<Frey>  This page describes how to use and develop with L<Frey>
4    
5    =head1 Developer parts
6    
7    =head2 Moose classes
8    
9    All Moose classes have simple introspection API which use
10    L<Frey::Introspect> to show class and it's pod (using L<Frey::Pod>).
11    
12    Example of valid REST URL is
13    
14      http://localhost:16001/Frey
15    
16    which will show L<Frey> class introspection.
17    
18    You can also add method invocation and optional parameters to C<new>
19    constructor like this:
20    
21      http://localhost:16001/Frey::Pod/as_markup?class=Frey
22    
23    this is same using L<Frey::Pod> from perl as
24    
25      Frey::Pod->new( class => 'Frey' )->as_markup;
26    
27    Forms to enter required parameters will be generated automatically,
28    allowing you to explore your data while you are making interface for it.
29    
30    =head2 Database
31    
32    FIXME broken if not noted in C<TODO>
33    
34    For database objects we support L<Fey> and when your objects are created
35    C<< with 'Frey::ORM::Collection' >> they will have basic CRUD functionality
36    implemented by L<Frey::ObjectBrowser>.
37    
38    =head1 User parts
39    
40    =head2 Pipes
41    
42    See L<Frey::Pipe> for now.
43    
44    =head1 Designing user interaction flows
45    
46    Frey is all about creating Moose classes as your interaction with pages.
47    Each page is instance of class with some parameters received with post or
48    get request.
49    
50    If you want to access those parameters in your object, you have to define
51    attributes for it using L<Moose/has>
52    
53    You can also generate result in three different forms:
54    
55    
56    =over 20
57    
58    =item as_markup
59    
60    HTML content
61    
62    =item as_sponge
63    
64    Tabular output
65    
66    FIXME link to description
67    
68    =item as_data
69    
70    Any perl hash structure
71    
72    =back
73    
74    
75    =head2 No html templates
76    
77    Frey doesn't have html templates. Since your methods are part of REST URIs,
78    it doesn't make sense to separate html from object itself, which represent
79    web page. L<Frey::Web> provides role which has a bunch of helpful things
80    when creating html.
81    
82    Basically, if html you are generating in readable code semantically correct
83    to you, it the right track.
84    
85    You don't even have to create initial entry form as L<Frey::Run>,
86    which will start your L<Moose> classes, will call L<Frey::Action>
87    for help and generate initial form for you. If this magic is wrong,
88    just define C<< sub render_pipe { 'radio' } >> to force rending of
89    C<pipe> attribute as radio buttons.
90    
91    =head2 Easy skeletons
92    
93    Creating files is mess, so L<Frey::Class::Create/create_class_source> will
94    create class and test skeleton for you.
95    
96    If I did it right, it should read similar to human language, like Smalltalk.
97    
98    L<Frey> is careful to provide enough magic to build skeletons just of files
99    which contain some specific logic to your aplication, so it's not massive code
100    generation as in Java...
101    
102    To make things simple, there are few conventions (with nod to Ruby on Rails)
103    which will help you get started:
104    
105    
106    =head2 HTML markup convetion
107    
108    HTML markup should be enclosed in C< qq| > and C< | > quotes. There is also
109    funny but very readable convention of multi line html when you have to
110    intermix conditions:
111    
112      my $html
113        = qq|<h1>First</h1>|
114        . ( $is_second ? qq|<h2>Second</h2>| : '' )
115        . qq|<h3>Third</h3>|
116        ;
117    
118    This will be checked and reported at some point. Ideally, I would like to
119    write just
120    
121      my $html
122        = qq|<h1>First</h1>|
123        . $is_second ? qq|<h2>Second</h2>| : ''
124        . qq|<h3>Third</h3>|
125        ;
126    
127    which is valid perl syntax but doesn't work as expected.
128    
129    
130    =head2 Smalltalk like refactoring
131    
132    Frey is heavily influenced by Smalltalk, up to the point of syntax. Coding
133    Frey code should be like playing with L<Frey>. And you might end up with
134    result which might surprise you.
135    
136    Refactoring tools are not new in perl. We have L<PPI>, L<App::Ack> and C<vim>
137    so what more do we want?
138    
139    If you look closely into Smalltalk development work-flow, you really need
140    ability to rename class or method without any additional effort. For that,
141    we use L<Frey::Class::Refactor> which allows code modifications at source
142    level with just few clicks.
143    
144    =head2 Default values
145    
146    When L<Frey::Run> tries to create instance of class (usually because of web
147    request) it tried to read default values from C<yaml> files in C<etc/> and
148    if it doesn't find all of required values it will invoke L<Frey::Action> to
149    create end-user html form with missing fields.
150    
151    
152    =head1 Examples
153    
154    To help you get started, here are few implemented flows in Frey:
155    
156    =over 20
157    
158    =item L<Frey::Shell::Grep>
159    
160    Simple interaction with C<grep>
161    
162    =item L<Frey::SVK>
163    
164    Gather data, display selection form with checkboxes
165    
166    =item L<Frey::IconBrowser>
167    
168    Display a huge amount of icons with single HTTP request
169    
170    =back
171    
172    
173  =head1 Command-line integration  =head1 Command-line integration
174    
175  One of key points is that L<Frey> runs under your user. This means it has  One of key points is that L<Frey> runs under your user. This means it has
176  access to your termnial, and ssh keys, so beware!  access to your terminal, and ssh keys, so beware!
177    
178  =head1 Install  =head1 Install
179    
# Line 42  Used for switching focus between browser Line 210  Used for switching focus between browser
210    
211  =head2 bin/dev.sh  =head2 bin/dev.sh
212    
213  Recommeded way to start development L<Frey> server since it will restart it  Recommended way to start development L<Frey> server since it will restart it
214  automatically and kill running instance if existing.  automatically and kill running instance if existing.
215    
216  =head2 bin/check-syntax.sh  =head2 bin/check-syntax.sh
# Line 51  Check syntax of modified files. Line 219  Check syntax of modified files.
219    
220  =head2 bin/grep-iselect.sh  =head2 bin/grep-iselect.sh
221    
222  Helper using C<iselect> to quickly grep, select result and jump to C<vim>  Helper using C<iselect> to quickly grep, select result and jump to C<vim>.
223    
224    You can also pass grep params for context etc, like this:
225    
226            ./bin/grep-iselect.sh something -C 3
227            ./bin/grep-iselect.sh something -A 10 -B 3
228    
229  =head2 bin/log.sh  =head2 bin/log.sh
230    
# Line 65  used in Frey and rest is kind of TODO li Line 238  used in Frey and rest is kind of TODO li
238  =head2 bin/clean-var.sh  =head2 bin/clean-var.sh
239    
240  Cleanup C<var/> directory which gets a lot of dumps. Most of useful data  Cleanup C<var/> directory which gets a lot of dumps. Most of useful data
241  is held forever because I belive that trends are most interesting way to  is held forever because I believe that trends are most interesting way to
242  look at data.  look at data.
243    
244  =cut  =cut
Legend:
Removed from v.704  
changed lines
  Added in v.991
  ViewVC Help
Powered by ViewVC 1.1.26