/[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 701 by dpavlin, Wed Dec 3 19:00:10 2008 UTC revision 1020 by dpavlin, Mon Jan 26 14:51:11 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<DBIx::Class> to introspect existing
35    database and implement user interface for it.
36    
37    Steps to create classes for your existing L<Reblog> database:
38    
39     ./bin/dbic-generate-schema.pl 'DBI:mysql:database=reblog;host=127.0.0.1;port=13306' Reblog
40    
41    Open L<Frey::DBIC::Browser/as_sponge> and verify that your generated schema works
42    
43    =back
44    
45    =head1 User parts
46    
47    =head2 Pipes
48    
49    See L<Frey::Pipe> for now.
50    
51    =head1 Designing user interaction flows
52    
53    Frey is all about creating Moose classes as your interaction with pages.
54    Each page is instance of class with some parameters received with post or
55    get request.
56    
57    If you want to access those parameters in your object, you have to define
58    attributes for it using L<Moose/has>
59    
60    You can also generate result in three different forms:
61    
62    
63    =over 20
64    
65    =item as_markup
66    
67    HTML content
68    
69    =item as_sponge
70    
71    Tabular output
72    
73    FIXME link to description
74    
75    =item as_data
76    
77    Any perl hash structure
78    
79    =back
80    
81    
82    =head2 No html templates
83    
84    Frey doesn't have html templates. Since your methods are part of REST URIs,
85    it doesn't make sense to separate html from object itself, which represent
86    web page. L<Frey::Web> provides role which has a bunch of helpful things
87    when creating html.
88    
89    Basically, if html you are generating in readable code semantically correct
90    to you, it the right track.
91    
92    You don't even have to create initial entry form as L<Frey::Run>,
93    which will start your L<Moose> classes, will call L<Frey::Action>
94    for help and generate initial form for you. If this magic is wrong,
95    just define C<< sub render_pipe { 'radio' } >> to force rending of
96    C<pipe> attribute as radio buttons.
97    
98    =head2 Easy skeletons
99    
100    Creating files is mess, so L<Frey::Class::Create/create_class_source> will
101    create class and test skeleton for you.
102    
103    If I did it right, it should read similar to human language, like Smalltalk.
104    
105    L<Frey> is careful to provide enough magic to build skeletons just of files
106    which contain some specific logic to your aplication, so it's not massive code
107    generation as in Java...
108    
109    To make things simple, there are few conventions (with nod to Ruby on Rails)
110    which will help you get started:
111    
112    
113    =head2 HTML markup convetion
114    
115    HTML markup should be enclosed in C< qq| > and C< | > quotes. There is also
116    funny but very readable convention of multi line html when you have to
117    intermix conditions:
118    
119      my $html
120        = qq|<h1>First</h1>|
121        . ( $is_second ? qq|<h2>Second</h2>| : '' )
122        . qq|<h3>Third</h3>|
123        ;
124    
125    This will be checked and reported at some point. Ideally, I would like to
126    write just
127    
128      my $html
129        = qq|<h1>First</h1>|
130        . $is_second ? qq|<h2>Second</h2>| : ''
131        . qq|<h3>Third</h3>|
132        ;
133    
134    which is valid perl syntax but doesn't work as expected.
135    
136    
137    =head2 Smalltalk like refactoring
138    
139    Frey is heavily influenced by Smalltalk, up to the point of syntax. Coding
140    Frey code should be like playing with L<Frey>. And you might end up with
141    result which might surprise you.
142    
143    Refactoring tools are not new in perl. We have L<PPI>, L<App::Ack> and C<vim>
144    so what more do we want?
145    
146    If you look closely into Smalltalk development work-flow, you really need
147    ability to rename class or method without any additional effort. For that,
148    we use L<Frey::Class::Refactor> which allows code modifications at source
149    level with just few clicks.
150    
151    =head2 Default values
152    
153    When L<Frey::Run> tries to create instance of class (usually because of web
154    request) it tried to read default values from C<yaml> files in C<etc/> and
155    if it doesn't find all of required values it will invoke L<Frey::Action> to
156    create end-user html form with missing fields.
157    
158    
159    =head1 Examples
160    
161    To help you get started, here are few implemented flows in Frey:
162    
163    =over 20
164    
165    =item L<Frey::Shell::Grep>
166    
167    Simple interaction with C<grep>
168    
169    =item L<Frey::SVK>
170    
171    Gather data, display selection form with checkboxes
172    
173    =item L<Frey::IconBrowser>
174    
175    Display a huge amount of icons with single HTTP request
176    
177    =back
178    
179    
180  =head1 Command-line integration  =head1 Command-line integration
181    
182  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
183  access to your termnial, and ssh keys, so beware!  access to your terminal, and ssh keys, so beware!
184    
185  =head1 Install  =head1 Install
186    
# Line 42  Used for switching focus between browser Line 217  Used for switching focus between browser
217    
218  =head2 bin/dev.sh  =head2 bin/dev.sh
219    
220  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
221  automatically and kill running instance if existing.  automatically and kill running instance if existing.
222    
223  =head2 bin/check-syntax.sh  =head2 bin/check-syntax.sh
# Line 51  Check syntax of modified files. Line 226  Check syntax of modified files.
226    
227  =head2 bin/grep-iselect.sh  =head2 bin/grep-iselect.sh
228    
229  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>.
230    
231    You can also pass grep params for context etc, like this:
232    
233            ./bin/grep-iselect.sh something -C 3
234            ./bin/grep-iselect.sh something -A 10 -B 3
235    
236    =head2 bin/log.sh
237    
238    Open last 3 logs in vim
239    
240  =head2 bin/checkout-js.sh  =head2 bin/checkout-js.sh
241    
# Line 61  used in Frey and rest is kind of TODO li Line 245  used in Frey and rest is kind of TODO li
245  =head2 bin/clean-var.sh  =head2 bin/clean-var.sh
246    
247  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
248  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
249  look at data.  look at data.
250    
251  =cut  =cut
Legend:
Removed from v.701  
changed lines
  Added in v.1020
  ViewVC Help
Powered by ViewVC 1.1.26