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

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

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