lib/Frey/Manual.pod

=head1 Frey Manual

This page describes how to use and develop with L<Frey>

=head1 Developer parts

=head2 Moose classes

All Moose classes have simple introspection API which use
L<Frey::Introspect> to show class and it's pod (using L<Frey::Pod>). 

Example of valid REST URL is

  http://localhost:16001/Frey

which will show L<Frey> class introspection.

You can also add method invocation and optional parameters to C<new>
constructor like this:

  http://localhost:16001/Frey::Pod/as_markup?class=Frey

this is same using L<Frey::Pod> from perl as

  Frey::Pod->new( class => 'Frey' )->as_markup;

Forms to enter required parameters will be generated automatically, 
allowing you to explore your data while you are making interface for it.

=head2 Database

FIXME broken if not noted in C<TODO>

For database objects we support L<DBIx::Class> to introspect existing
database and implement user interface for it.

Steps to create classes for your existing L<Reblog> database:

 ./bin/dbic-generate-schema.pl 'DBI:mysql:database=reblog;host=127.0.0.1;port=13306' Reblog

Open L<Frey::DBIC::Browser/as_sponge> and verify that your generated schema works

=back

=head1 User parts

=head2 Pipes

See L<Frey::Pipe> for now.

=head1 Designing user interaction flows

Frey is all about creating Moose classes as your interaction with pages.
Each page is instance of class with some parameters received with post or
get request.

If you want to access those parameters in your object, you have to define
attributes for it using L<Moose/has>

You can also generate result in three different forms:


=over 20

=item as_markup

HTML content

=item as_sponge

Tabular output

FIXME link to description

=item as_data

Any perl hash structure

=back


=head2 No html templates

Frey doesn't have html templates. Since your methods are part of REST URIs,
it doesn't make sense to separate html from object itself, which represent
web page. L<Frey::Web> provides role which has a bunch of helpful things
when creating html.

Basically, if html you are generating in readable code semantically correct
to you, it the right track.

You don't even have to create initial entry form as L<Frey::Run>,
which will start your L<Moose> classes, will call L<Frey::Action>
for help and generate initial form for you. If this magic is wrong,
just define C<< sub render_pipe { 'radio' } >> to force rending of
C<pipe> attribute as radio buttons.

=head2 Easy skeletons

Creating files is mess, so L<Frey::Class::Create/create_class_source> will
create class and test skeleton for you.

If I did it right, it should read similar to human language, like Smalltalk.

L<Frey> is careful to provide enough magic to build skeletons just of files
which contain some specific logic to your aplication, so it's not massive code
generation as in Java...

To make things simple, there are few conventions (with nod to Ruby on Rails)
which will help you get started:


=head2 HTML markup convetion

HTML markup should be enclosed in C< qq| > and C< | > quotes. There is also
funny but very readable convention of multi line html when you have to
intermix conditions:

  my $html
    = qq|<h1>First</h1>|
    . ( $is_second ? qq|<h2>Second</h2>| : '' )
    . qq|<h3>Third</h3>|
    ;

This will be checked and reported at some point. Ideally, I would like to
write just

  my $html
    = qq|<h1>First</h1>|
    . $is_second ? qq|<h2>Second</h2>| : ''
    . qq|<h3>Third</h3>|
    ;

which is valid perl syntax but doesn't work as expected.


=head2 Smalltalk like refactoring

Frey is heavily influenced by Smalltalk, up to the point of syntax. Coding
Frey code should be like playing with L<Frey>. And you might end up with
result which might surprise you.

Refactoring tools are not new in perl. We have L<PPI>, L<App::Ack> and C<vim>
so what more do we want?

If you look closely into Smalltalk development work-flow, you really need
ability to rename class or method without any additional effort. For that,
we use L<Frey::Class::Refactor> which allows code modifications at source
level with just few clicks.

=head2 Default values

When L<Frey::Run> tries to create instance of class (usually because of web
request) it tried to read default values from C<yaml> files in C<etc/> and
if it doesn't find all of required values it will invoke L<Frey::Action> to
create end-user html form with missing fields.


=head1 Examples

To help you get started, here are few implemented flows in Frey:

=over 20

=item L<Frey::Shell::Grep>

Simple interaction with C<grep>

=item L<Frey::SVK>

Gather data, display selection form with checkboxes

=item L<Frey::IconBrowser>

Display a huge amount of icons with single HTTP request

=back


=head1 Command-line integration

One of key points is that L<Frey> runs under your user. This means it has
access to your terminal, and ssh keys, so beware!

=head1 Install

=head2 Firefox

Frey is designed to provide close integration between your day-to-day data
mungling work in console and Firefox.

You might want to open separate Firefox and terminal for Frey sessions.

It's also useful to have Firebug extension installed in Firefox to provide
quick introspection on html, network traffic and request parameters.

If nothing else, L<Frey::Bookmarklet> provides Firebug lite bookmarklet.

It's all Text! Firefox extension at
L<https://addons.mozilla.org/en-US/firefox/addon/4125> provides integration
between form textarea and your editor, so it's also handy.

=head2 vim

Content on page will be linked to vim using L<Frey::Web/html_links>

You might want to install vim plugin C<prel_synwrite.vim> from
L<http://www.vim.org/scripts/script.php?script_id=896>
to check syntax on every C<:Write>


=head2 xdotool

Used for switching focus between browser and terminal

=head1 Command-line helpers

=head2 bin/dev.sh

Recommended way to start development L<Frey> server since it will restart it
automatically and kill running instance if existing.

=head2 bin/check-syntax.sh

Check syntax of modified files.

=head2 bin/grep-iselect.sh

Helper using C<iselect> to quickly grep, select result and jump to C<vim>.

You can also pass grep params for context etc, like this:

        ./bin/grep-iselect.sh something -C 3
        ./bin/grep-iselect.sh something -A 10 -B 3

=head2 bin/log.sh

Open last 3 logs in vim

=head2 bin/checkout-js.sh

Checkout bunch of JavaScript code from all over the net, some of which is
used in Frey and rest is kind of TODO list...

=head2 bin/clean-var.sh

Cleanup C<var/> directory which gets a lot of dumps. Most of useful data
is held forever because I believe that trends are most interesting way to
look at data.

=cut
1	dpavlin	693	=head1 Frey Manual
2
3			This page describes how to use and develop with L<Frey>
4
5	dpavlin	801	=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	dpavlin	1014	For database objects we support L<DBIx::Class> to introspect existing
35			database and implement user interface for it.
36	dpavlin	801
37	dpavlin	1014	Steps to create classes for your existing L<Reblog> database:
38
39	dpavlin	1020	./bin/dbic-generate-schema.pl 'DBI:mysql:database=reblog;host=127.0.0.1;port=13306' Reblog
40	dpavlin	1014
41	dpavlin	1020	Open L<Frey::DBIC::Browser/as_sponge> and verify that your generated schema works
42	dpavlin	1014
43			=back
44
45	dpavlin	801	=head1 User parts
46
47			=head2 Pipes
48
49			See L<Frey::Pipe> for now.
50
51	dpavlin	722	=head1 Designing user interaction flows
52
53			Frey is all about creating Moose classes as your interaction with pages.
54	dpavlin	801	Each page is instance of class with some parameters received with post or
55	dpavlin	722	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	dpavlin	729
63	dpavlin	722	=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	dpavlin	729
82			=head2 No html templates
83
84	dpavlin	722	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	dpavlin	941	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	dpavlin	722
98	dpavlin	941	=head2 Easy skeletons
99
100	dpavlin	778	Creating files is mess, so L<Frey::Class::Create/create_class_source> will
101	dpavlin	722	create class and test skeleton for you.
102
103	dpavlin	801	If I did it right, it should read similar to human language, like Smalltalk.
104	dpavlin	722
105	dpavlin	941	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	dpavlin	801	To make things simple, there are few conventions (with nod to Ruby on Rails)
110	dpavlin	722	which will help you get started:
111
112	dpavlin	729
113	dpavlin	941	=head2 HTML markup convetion
114	dpavlin	722
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	dpavlin	801	intermix conditions:
118	dpavlin	722
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	dpavlin	729
137	dpavlin	801	=head2 Smalltalk like refactoring
138	dpavlin	729
139	dpavlin	801	Frey is heavily influenced by Smalltalk, up to the point of syntax. Coding
140	dpavlin	729	Frey code should be like playing with L<Frey>. And you might end up with
141			result which might surprise you.
142
143	dpavlin	801	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	dpavlin	729
146	dpavlin	801	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	dpavlin	729
151	dpavlin	801	=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	dpavlin	722
159	dpavlin	941	=head1 Examples
160
161	dpavlin	722	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	dpavlin	729
180	dpavlin	701	=head1 Command-line integration
181
182			One of key points is that L<Frey> runs under your user. This means it has
183	dpavlin	801	access to your terminal, and ssh keys, so beware!
184	dpavlin	701
185	dpavlin	693	=head1 Install
186
187	dpavlin	701	=head2 Firefox
188
189	dpavlin	693	Frey is designed to provide close integration between your day-to-day data
190			mungling work in console and Firefox.
191
192			You might want to open separate Firefox and terminal for Frey sessions.
193
194			It's also useful to have Firebug extension installed in Firefox to provide
195			quick introspection on html, network traffic and request parameters.
196
197	dpavlin	701	If nothing else, L<Frey::Bookmarklet> provides Firebug lite bookmarklet.
198	dpavlin	693
199	dpavlin	701	It's all Text! Firefox extension at
200			L<https://addons.mozilla.org/en-US/firefox/addon/4125> provides integration
201			between form textarea and your editor, so it's also handy.
202	dpavlin	693
203			=head2 vim
204
205			Content on page will be linked to vim using L<Frey::Web/html_links>
206
207			You might want to install vim plugin C<prel_synwrite.vim> from
208			L<http://www.vim.org/scripts/script.php?script_id=896>
209			to check syntax on every C<:Write>
210
211
212			=head2 xdotool
213
214			Used for switching focus between browser and terminal
215
216			=head1 Command-line helpers
217
218	dpavlin	701	=head2 bin/dev.sh
219
220	dpavlin	801	Recommended way to start development L<Frey> server since it will restart it
221	dpavlin	701	automatically and kill running instance if existing.
222
223	dpavlin	693	=head2 bin/check-syntax.sh
224
225			Check syntax of modified files.
226
227	dpavlin	701	=head2 bin/grep-iselect.sh
228
229	dpavlin	937	Helper using C<iselect> to quickly grep, select result and jump to C<vim>.
230	dpavlin	701
231	dpavlin	937	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	dpavlin	704	=head2 bin/log.sh
237
238			Open last 3 logs in vim
239
240	dpavlin	701	=head2 bin/checkout-js.sh
241
242			Checkout bunch of JavaScript code from all over the net, some of which is
243			used in Frey and rest is kind of TODO list...
244
245			=head2 bin/clean-var.sh
246
247			Cleanup C<var/> directory which gets a lot of dumps. Most of useful data
248	dpavlin	801	is held forever because I believe that trends are most interesting way to
249	dpavlin	701	look at data.
250
251	dpavlin	693	=cut