lib/Frey/Manual.pod

=head1 Frey Manual

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

=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 parametars 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.

Creating files is mess, so L<Frey::ClassCreator/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.

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


=head2 default parametars

Default values for


=head2 html markup

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 confitions:

  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 influcenced by SmallTalks, 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. However,


=head2 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 termnial, 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

Recommeded 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>

=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 belive 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 Designing user interaction flows
6
7	Frey is all about creating Moose classes as your interaction with pages.
8	Each page is instance of class with some parametars received with post or
9	get request.
10
11	If you want to access those parameters in your object, you have to define
12	attributes for it using L<Moose/has>
13
14	You can also generate result in three different forms:
15
16
17	=over 20
18
19	=item as_markup
20
21	HTML content
22
23	=item as_sponge
24
25	Tabular output
26
27	FIXME link to description
28
29	=item as_data
30
31	Any perl hash structure
32
33	=back
34
35
36	=head2 No html templates
37
38	Frey doesn't have html templates. Since your methods are part of REST URIs,
39	it doesn't make sense to separate html from object itself, which represent
40	web page. L<Frey::Web> provides role which has a bunch of helpful things
41	when creating html.
42
43	Basically, if html you are generating in readable code semantically correct
44	to you, it the right track.
45
46	You don't even have to create initial entry form as L<Frey::Run>,
47	which will start your L<Moose> classes, will call L<Frey::Action>
48	for help and generate initial form for you.
49
50	Creating files is mess, so L<Frey::ClassCreator/create_class_source> will
51	create class and test skeleton for you.
52
53	If I did it right, it should read similar to human language, like SmallTalk.
54
55	To make things simple, there are few convertions (with nod to Ruby on Rails)
56	which will help you get started:
57
58
59	=head2 default parametars
60
61	Default values for
62
63
64	=head2 html markup
65
66	HTML markup should be enclosed in C< qq\| > and C< \| > quotes. There is also
67	funny but very readable convention of multi line html when you have to
68	intermix confitions:
69
70	my $html
71	= qq\|<h1>First</h1>\|
72	. ( $is_second ? qq\|<h2>Second</h2>\| : '' )
73	. qq\|<h3>Third</h3>\|
74	;
75
76	This will be checked and reported at some point. Ideally, I would like to
77	write just
78
79	my $html
80	= qq\|<h1>First</h1>\|
81	. $is_second ? qq\|<h2>Second</h2>\| : ''
82	. qq\|<h3>Third</h3>\|
83	;
84
85	which is valid perl syntax but doesn't work as expected.
86
87
88	=head2 SmallTalk like refactoring
89
90	Frey is heavily influcenced by SmallTalks, up to the point of syntax. Coding
91	Frey code should be like playing with L<Frey>. And you might end up with
92	result which might surprise you.
93
94	Refactoring tools are not new in perl. However,
95
96
97	=head2 examples
98
99	To help you get started, here are few implemented flows in Frey:
100
101	=over 20
102
103	=item L<Frey::Shell::Grep>
104
105	Simple interaction with C<grep>
106
107	=item L<Frey::SVK>
108
109	Gather data, display selection form with checkboxes
110
111	=item L<Frey::IconBrowser>
112
113	Display a huge amount of icons with single HTTP request
114
115	=back
116
117
118	=head1 Command-line integration
119
120	One of key points is that L<Frey> runs under your user. This means it has
121	access to your termnial, and ssh keys, so beware!
122
123	=head1 Install
124
125	=head2 Firefox
126
127	Frey is designed to provide close integration between your day-to-day data
128	mungling work in console and Firefox.
129
130	You might want to open separate Firefox and terminal for Frey sessions.
131
132	It's also useful to have Firebug extension installed in Firefox to provide
133	quick introspection on html, network traffic and request parameters.
134
135	If nothing else, L<Frey::Bookmarklet> provides Firebug lite bookmarklet.
136
137	It's all Text! Firefox extension at
138	L<https://addons.mozilla.org/en-US/firefox/addon/4125> provides integration
139	between form textarea and your editor, so it's also handy.
140
141	=head2 vim
142
143	Content on page will be linked to vim using L<Frey::Web/html_links>
144
145	You might want to install vim plugin C<prel_synwrite.vim> from
146	L<http://www.vim.org/scripts/script.php?script_id=896>
147	to check syntax on every C<:Write>
148
149
150	=head2 xdotool
151
152	Used for switching focus between browser and terminal
153
154	=head1 Command-line helpers
155
156	=head2 bin/dev.sh
157
158	Recommeded way to start development L<Frey> server since it will restart it
159	automatically and kill running instance if existing.
160
161	=head2 bin/check-syntax.sh
162
163	Check syntax of modified files.
164
165	=head2 bin/grep-iselect.sh
166
167	Helper using C<iselect> to quickly grep, select result and jump to C<vim>
168
169	=head2 bin/log.sh
170
171	Open last 3 logs in vim
172
173	=head2 bin/checkout-js.sh
174
175	Checkout bunch of JavaScript code from all over the net, some of which is
176	used in Frey and rest is kind of TODO list...
177
178	=head2 bin/clean-var.sh
179
180	Cleanup C<var/> directory which gets a lot of dumps. Most of useful data
181	is held forever because I belive that trends are most interesting way to
182	look at data.
183
184	=cut