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


=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	=head1 Frey Manual
2
3	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
44	=head1 User parts
45
46	=head2 Pipes
47
48	See L<Frey::Pipe> for now.
49
50	=head1 Designing user interaction flows
51
52	Frey is all about creating Moose classes as your interaction with pages.
53	Each page is instance of class with some parameters received with post or
54	get request.
55
56	If you want to access those parameters in your object, you have to define
57	attributes for it using L<Moose/has>
58
59	You can also generate result in three different forms:
60
61
62	=over 20
63
64	=item as_markup
65
66	HTML content
67
68	=item as_sponge
69
70	Tabular output
71
72	FIXME link to description
73
74	=item as_data
75
76	Any perl hash structure
77
78	=back
79
80
81	=head2 No html templates
82
83	Frey doesn't have html templates. Since your methods are part of REST URIs,
84	it doesn't make sense to separate html from object itself, which represent
85	web page. L<Frey::Web> provides role which has a bunch of helpful things
86	when creating html.
87
88	Basically, if html you are generating in readable code semantically correct
89	to you, it the right track.
90
91	You don't even have to create initial entry form as L<Frey::Run>,
92	which will start your L<Moose> classes, will call L<Frey::Action>
93	for help and generate initial form for you. If this magic is wrong,
94	just define C<< sub render_pipe { 'radio' } >> to force rending of
95	C<pipe> attribute as radio buttons.
96
97	=head2 Easy skeletons
98
99	Creating files is mess, so L<Frey::Class::Create/create_class_source> will
100	create class and test skeleton for you.
101
102	If I did it right, it should read similar to human language, like Smalltalk.
103
104	L<Frey> is careful to provide enough magic to build skeletons just of files
105	which contain some specific logic to your aplication, so it's not massive code
106	generation as in Java...
107
108	To make things simple, there are few conventions (with nod to Ruby on Rails)
109	which will help you get started:
110
111
112	=head2 HTML markup convetion
113
114	HTML markup should be enclosed in C< qq\| > and C< \| > quotes. There is also
115	funny but very readable convention of multi line html when you have to
116	intermix conditions:
117
118	my $html
119	= qq\|<h1>First</h1>\|
120	. ( $is_second ? qq\|<h2>Second</h2>\| : '' )
121	. qq\|<h3>Third</h3>\|
122	;
123
124	This will be checked and reported at some point. Ideally, I would like to
125	write just
126
127	my $html
128	= qq\|<h1>First</h1>\|
129	. $is_second ? qq\|<h2>Second</h2>\| : ''
130	. qq\|<h3>Third</h3>\|
131	;
132
133	which is valid perl syntax but doesn't work as expected.
134
135
136	=head2 Smalltalk like refactoring
137
138	Frey is heavily influenced by Smalltalk, up to the point of syntax. Coding
139	Frey code should be like playing with L<Frey>. And you might end up with
140	result which might surprise you.
141
142	Refactoring tools are not new in perl. We have L<PPI>, L<App::Ack> and C<vim>
143	so what more do we want?
144
145	If you look closely into Smalltalk development work-flow, you really need
146	ability to rename class or method without any additional effort. For that,
147	we use L<Frey::Class::Refactor> which allows code modifications at source
148	level with just few clicks.
149
150	=head2 Default values
151
152	When L<Frey::Run> tries to create instance of class (usually because of web
153	request) it tried to read default values from C<yaml> files in C<etc/> and
154	if it doesn't find all of required values it will invoke L<Frey::Action> to
155	create end-user html form with missing fields.
156
157
158	=head1 Examples
159
160	To help you get started, here are few implemented flows in Frey:
161
162	=over 20
163
164	=item L<Frey::Shell::Grep>
165
166	Simple interaction with C<grep>
167
168	=item L<Frey::SVK>
169
170	Gather data, display selection form with checkboxes
171
172	=item L<Frey::IconBrowser>
173
174	Display a huge amount of icons with single HTTP request
175
176	=back
177
178
179	=head1 Command-line integration
180
181	One of key points is that L<Frey> runs under your user. This means it has
182	access to your terminal, and ssh keys, so beware!
183
184	=head1 Install
185
186	=head2 Firefox
187
188	Frey is designed to provide close integration between your day-to-day data
189	mungling work in console and Firefox.
190
191	You might want to open separate Firefox and terminal for Frey sessions.
192
193	It's also useful to have Firebug extension installed in Firefox to provide
194	quick introspection on html, network traffic and request parameters.
195
196	If nothing else, L<Frey::Bookmarklet> provides Firebug lite bookmarklet.
197
198	It's all Text! Firefox extension at
199	L<https://addons.mozilla.org/en-US/firefox/addon/4125> provides integration
200	between form textarea and your editor, so it's also handy.
201
202	=head2 vim
203
204	Content on page will be linked to vim using L<Frey::Web/html_links>
205
206	You might want to install vim plugin C<prel_synwrite.vim> from
207	L<http://www.vim.org/scripts/script.php?script_id=896>
208	to check syntax on every C<:Write>
209
210
211	=head2 xdotool
212
213	Used for switching focus between browser and terminal
214
215	=head1 Command-line helpers
216
217	=head2 bin/dev.sh
218
219	Recommended way to start development L<Frey> server since it will restart it
220	automatically and kill running instance if existing.
221
222	=head2 bin/check-syntax.sh
223
224	Check syntax of modified files.
225
226	=head2 bin/grep-iselect.sh
227
228	Helper using C<iselect> to quickly grep, select result and jump to C<vim>.
229
230	You can also pass grep params for context etc, like this:
231
232	./bin/grep-iselect.sh something -C 3
233	./bin/grep-iselect.sh something -A 10 -B 3
234
235	=head2 bin/log.sh
236
237	Open last 3 logs in vim
238
239	=head2 bin/checkout-js.sh
240
241	Checkout bunch of JavaScript code from all over the net, some of which is
242	used in Frey and rest is kind of TODO list...
243
244	=head2 bin/clean-var.sh
245
246	Cleanup C<var/> directory which gets a lot of dumps. Most of useful data
247	is held forever because I believe that trends are most interesting way to
248	look at data.
249
250	=cut