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	dpavlin	693	=head1 Frey Manual
2
3			This page describes how to use and develop with L<Frey>
4
5	dpavlin	738	=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	dpavlin	701	=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	dpavlin	693	=head1 Install
124
125	dpavlin	701	=head2 Firefox
126
127	dpavlin	693	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	dpavlin	701	If nothing else, L<Frey::Bookmarklet> provides Firebug lite bookmarklet.
136	dpavlin	693
137	dpavlin	701	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	dpavlin	693
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	dpavlin	701	=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	dpavlin	693	=head2 bin/check-syntax.sh
162
163			Check syntax of modified files.
164
165	dpavlin	701	=head2 bin/grep-iselect.sh
166
167			Helper using C<iselect> to quickly grep, select result and jump to C<vim>
168
169	dpavlin	738	=head2 bin/log.sh
170
171			Open last 3 logs in vim
172
173	dpavlin	701	=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	dpavlin	693	=cut