A3C/lib/A3C.pod

=head1 NAME

A3C = AAAC; AAA from "Authentication, Authorization and Accounting" and C from "CARNet".

=head1 DESCRIPTION

This page describes general idea about A3C application and current status of implementation.

Oppinions should be attributed to Dobrica Pavlinusic, and not other developers :-)
It's surposed to convey a story which is coherent enough for new developer
to join into project. Most of other documentation is more useful when
developing and looking into code usage (if it's not documented and tested,
it doesn't exist) but this part is delivered as pure POD for reading pleasure.

=head1 Models

Models in Jifty are at perl level objects (with validation and
canonicalization) and tables in database.

For a start, we implement some magic documented in L<A3C::Record> on records
(rows in database).

Then, we need to mungle data without re-thinking SQL queries which would
produce same results, so there is L<A3C::SQL> which produce objects that
look like L<Jifty::Collection>s, but aren't. This allows us to switch into
SQL in views if needed.

This method is not perfect, and shouldn't be used instead of Jifty models
just to write SQL because it doesn't do any permission checking. However,
it's a huge help for compex C<GROUP BY> and C<JOIN> queries which are hard
to express using L<Jifty::DBI>.

If we needed to generate those queries from within program (from user data,
for example) something like L<Fey::SQL> would be much better tool.

=head1 LDAP 

Implement LDAP entry and edit interface (insteresting problem since most
values can have multiple entries which doesn't map nicely to relational
schema)

This can in turn be broken down into following tasks:

=head2 Import data from existing LDAP server

C<bin/import-ldap.pl> has embedded documentation

=head2 Query existing LDAP server

Since we are creating local copy of data, we need easy way to ask master
LDAP server for data. L<A3C::LDAP> provides way to query LDAP and receive
something similar enough to L<Jifty::Collection> so that L<A3C::View>s
doesn't have to be edited to switch from Jifty models to LDAP
data.

=head2 Create new entries and edit existing ones

We are in the middle of migaration from (generic) L<A3C::Model::Person> and
L<A3C::Model::Organization> to our custom L<A3C::Model::hrEduOrg> and
L<A3C::Model::hrEduPerson>

Most views I guess, will be implemented by subclassing L<Jifty::View::Declare::CRUD>.
Right now L<A3C::View::Organization> is such implementation.

Planned C<A3C::View::hrEduPerson> will implement another such view, and I
hope to see some kind of code reuse there (which should probably move to
C<Jifty::Plugin::TableCRUD>.

=head2 Virtual LDAP server to publish data

This part is in planning stage, and it will probably be based on L<Net::LDAP::Server>.

=head1 Existing LDAP schema

First, we needed a clever way to import existing LDAP schema into Jifty. So,
C<bin/ldap2model.pl> helper was created to handle that.

Some entries in LDAP schema have fixed list of attributed, and L<A3C::AAIEduHr>
implements fetcher (with cache) for that data.

=head1 Legacy portal integration

=head2 Parse PHP config files

Configuration files in PHP is only place in which part of portal
configuration is specified. To handle it in A3C, we use
L<A3C::Model::StrixInstance> which agregates all instance data. Parser is
implemented by L<A3C::PHP>

=head2 Connect to remote database

Implemented in two different ways:

=head3 Direct SQL execution

L<A3C::Action::StrixSQL> and interface as L<A3C::View::Strix/sql>.

=head3 Fetching data hashes

C<Strix> (which doesn't link well from on-line documentation so you will
have to take a look in C<lib/Strix.pm>) implements pure DBI code (ported
from php) to access data directly. Keep in mind that this data have to be
cached for any resonable performance. On the other hand, data can be
structured usefully, for example trees are structured in useful way for 
direct output to JSON.

If tree has C<class> key, it can be set to C<error> so that we can mark
errors in data using same CSS class in views. This might be useful convention.

I prefer to keep this file documented up to level that make it's usage from Jifty and 
C<t/50-strix.t> makes sanse, but not more than that.

=head1 HTML

We don't generate HTML using templates. In fact, all HTML is encoded in perl
code using L<Template::Declare>. This allows easy generation of valid HTML,
high-level templates which are perl code and easy skinning using CSS.

C<share/web/static/css/app.css> is used to store application specific CSS.
It should probably be split into several files (Jifty will concatenate them
for us anyway) for easier maintenance, probably by same logic as view names
to skip additional step of mapping when human are watching into code.

In long run, this should allow us to refactor templates at code level and
create different re-usable widgets which brings us to following topic...

=head1 AJAX

Jifty's way of AJAX are L<Jifty::Manual::PageRegions>.

=head2 Strix navigation

L<http://a3c.skole.hr/strix/navigation>

For now, we have implementation of two-level select which is in sync with
instance clipboard (implemented by L<A3C::Model::StrixInstanceSelection> and
L<A3C::View::Strix> and L<A3C::Action::StrixSelectSite>. This is
good candidate to refactor into reusable widget on it's own.

=head1 BUGS

Many probably, documented in C<TODO> which is also useful for quick overview
what changed between versions if svn commit log is too detailed allthough
first line of commit message might be good summary of each individual
change.
1	dpavlin	204	=head1 NAME
2
3			A3C = AAAC; AAA from "Authentication, Authorization and Accounting" and C from "CARNet".
4
5			=head1 DESCRIPTION
6
7	dpavlin	205	This page describes general idea about A3C application and current status of implementation.
8	dpavlin	204
9	dpavlin	205	Oppinions should be attributed to Dobrica Pavlinusic, and not other developers :-)
10			It's surposed to convey a story which is coherent enough for new developer
11			to join into project. Most of other documentation is more useful when
12			developing and looking into code usage (if it's not documented and tested,
13			it doesn't exist) but this part is delivered as pure POD for reading pleasure.
14
15	dpavlin	207	=head1 Models
16
17			Models in Jifty are at perl level objects (with validation and
18			canonicalization) and tables in database.
19
20			For a start, we implement some magic documented in L<A3C::Record> on records
21			(rows in database).
22
23			Then, we need to mungle data without re-thinking SQL queries which would
24			produce same results, so there is L<A3C::SQL> which produce objects that
25			look like L<Jifty::Collection>s, but aren't. This allows us to switch into
26			SQL in views if needed.
27
28			This method is not perfect, and shouldn't be used instead of Jifty models
29			just to write SQL because it doesn't do any permission checking. However,
30			it's a huge help for compex C<GROUP BY> and C<JOIN> queries which are hard
31			to express using L<Jifty::DBI>.
32
33			If we needed to generate those queries from within program (from user data,
34			for example) something like L<Fey::SQL> would be much better tool.
35
36	dpavlin	204	=head1 LDAP
37
38			Implement LDAP entry and edit interface (insteresting problem since most
39			values can have multiple entries which doesn't map nicely to relational
40			schema)
41
42			This can in turn be broken down into following tasks:
43
44			=head2 Import data from existing LDAP server
45
46			C<bin/import-ldap.pl> has embedded documentation
47
48			=head2 Query existing LDAP server
49
50			Since we are creating local copy of data, we need easy way to ask master
51			LDAP server for data. L<A3C::LDAP> provides way to query LDAP and receive
52			something similar enough to L<Jifty::Collection> so that L<A3C::View>s
53			doesn't have to be edited to switch from Jifty models to LDAP
54			data.
55
56			=head2 Create new entries and edit existing ones
57
58			We are in the middle of migaration from (generic) L<A3C::Model::Person> and
59			L<A3C::Model::Organization> to our custom L<A3C::Model::hrEduOrg> and
60			L<A3C::Model::hrEduPerson>
61
62			Most views I guess, will be implemented by subclassing L<Jifty::View::Declare::CRUD>.
63			Right now L<A3C::View::Organization> is such implementation.
64
65			Planned C<A3C::View::hrEduPerson> will implement another such view, and I
66			hope to see some kind of code reuse there (which should probably move to
67			C<Jifty::Plugin::TableCRUD>.
68
69			=head2 Virtual LDAP server to publish data
70
71			This part is in planning stage, and it will probably be based on L<Net::LDAP::Server>.
72
73			=head1 Existing LDAP schema
74
75			First, we needed a clever way to import existing LDAP schema into Jifty. So,
76			C<bin/ldap2model.pl> helper was created to handle that.
77
78			Some entries in LDAP schema have fixed list of attributed, and L<A3C::AAIEduHr>
79			implements fetcher (with cache) for that data.
80
81			=head1 Legacy portal integration
82
83			=head2 Parse PHP config files
84
85			Configuration files in PHP is only place in which part of portal
86			configuration is specified. To handle it in A3C, we use
87			L<A3C::Model::StrixInstance> which agregates all instance data. Parser is
88			implemented by L<A3C::PHP>
89
90			=head2 Connect to remote database
91
92			Implemented in two different ways:
93
94			=head3 Direct SQL execution
95
96			L<A3C::Action::StrixSQL> and interface as L<A3C::View::Strix/sql>.
97
98			=head3 Fetching data hashes
99
100			C<Strix> (which doesn't link well from on-line documentation so you will
101			have to take a look in C<lib/Strix.pm>) implements pure DBI code (ported
102			from php) to access data directly. Keep in mind that this data have to be
103			cached for any resonable performance. On the other hand, data can be
104	dpavlin	205	structured usefully, for example trees are structured in useful way for
105			direct output to JSON.
106	dpavlin	204
107			If tree has C<class> key, it can be set to C<error> so that we can mark
108			errors in data using same CSS class in views. This might be useful convention.
109
110	dpavlin	205	I prefer to keep this file documented up to level that make it's usage from Jifty and
111			C<t/50-strix.t> makes sanse, but not more than that.
112
113	dpavlin	204	=head1 HTML
114
115			We don't generate HTML using templates. In fact, all HTML is encoded in perl
116			code using L<Template::Declare>. This allows easy generation of valid HTML,
117			high-level templates which are perl code and easy skinning using CSS.
118
119			C<share/web/static/css/app.css> is used to store application specific CSS.
120			It should probably be split into several files (Jifty will concatenate them
121			for us anyway) for easier maintenance, probably by same logic as view names
122			to skip additional step of mapping when human are watching into code.
123
124	dpavlin	205	In long run, this should allow us to refactor templates at code level and
125			create different re-usable widgets which brings us to following topic...
126
127			=head1 AJAX
128
129			Jifty's way of AJAX are L<Jifty::Manual::PageRegions>.
130
131			=head2 Strix navigation
132
133			L<http://a3c.skole.hr/strix/navigation>
134
135			For now, we have implementation of two-level select which is in sync with
136			instance clipboard (implemented by L<A3C::Model::StrixInstanceSelection> and
137			L<A3C::View::Strix> and L<A3C::Action::StrixSelectSite>. This is
138			good candidate to refactor into reusable widget on it's own.
139
140	dpavlin	204	=head1 BUGS
141
142			Many probably, documented in C<TODO> which is also useful for quick overview
143			what changed between versions if svn commit log is too detailed allthough
144			first line of commit message might be good summary of each individual
145			change.