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

=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 JSON
direct JSON output.

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.

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

=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	=head1 NAME
2
3	A3C = AAAC; AAA from "Authentication, Authorization and Accounting" and C from "CARNet".
4
5	=head1 DESCRIPTION
6
7	This page describes general idea about A3C application and current status of implementation
8
9	=head1 LDAP
10
11	Implement LDAP entry and edit interface (insteresting problem since most
12	values can have multiple entries which doesn't map nicely to relational
13	schema)
14
15	This can in turn be broken down into following tasks:
16
17	=head2 Import data from existing LDAP server
18
19	C<bin/import-ldap.pl> has embedded documentation
20
21	=head2 Query existing LDAP server
22
23	Since we are creating local copy of data, we need easy way to ask master
24	LDAP server for data. L<A3C::LDAP> provides way to query LDAP and receive
25	something similar enough to L<Jifty::Collection> so that L<A3C::View>s
26	doesn't have to be edited to switch from Jifty models to LDAP
27	data.
28
29	=head2 Create new entries and edit existing ones
30
31	We are in the middle of migaration from (generic) L<A3C::Model::Person> and
32	L<A3C::Model::Organization> to our custom L<A3C::Model::hrEduOrg> and
33	L<A3C::Model::hrEduPerson>
34
35	Most views I guess, will be implemented by subclassing L<Jifty::View::Declare::CRUD>.
36	Right now L<A3C::View::Organization> is such implementation.
37
38	Planned C<A3C::View::hrEduPerson> will implement another such view, and I
39	hope to see some kind of code reuse there (which should probably move to
40	C<Jifty::Plugin::TableCRUD>.
41
42	=head2 Virtual LDAP server to publish data
43
44	This part is in planning stage, and it will probably be based on L<Net::LDAP::Server>.
45
46	=head1 Existing LDAP schema
47
48	First, we needed a clever way to import existing LDAP schema into Jifty. So,
49	C<bin/ldap2model.pl> helper was created to handle that.
50
51	Some entries in LDAP schema have fixed list of attributed, and L<A3C::AAIEduHr>
52	implements fetcher (with cache) for that data.
53
54	=head1 Legacy portal integration
55
56	=head2 Parse PHP config files
57
58	Configuration files in PHP is only place in which part of portal
59	configuration is specified. To handle it in A3C, we use
60	L<A3C::Model::StrixInstance> which agregates all instance data. Parser is
61	implemented by L<A3C::PHP>
62
63	=head2 Connect to remote database
64
65	Implemented in two different ways:
66
67	=head3 Direct SQL execution
68
69	L<A3C::Action::StrixSQL> and interface as L<A3C::View::Strix/sql>.
70
71	=head3 Fetching data hashes
72
73	C<Strix> (which doesn't link well from on-line documentation so you will
74	have to take a look in C<lib/Strix.pm>) implements pure DBI code (ported
75	from php) to access data directly. Keep in mind that this data have to be
76	cached for any resonable performance. On the other hand, data can be
77	structured usefully, for example trees are structured in useful way for JSON
78	direct JSON output.
79
80	If tree has C<class> key, it can be set to C<error> so that we can mark
81	errors in data using same CSS class in views. This might be useful convention.
82
83	=head1 HTML
84
85	We don't generate HTML using templates. In fact, all HTML is encoded in perl
86	code using L<Template::Declare>. This allows easy generation of valid HTML,
87	high-level templates which are perl code and easy skinning using CSS.
88
89	C<share/web/static/css/app.css> is used to store application specific CSS.
90	It should probably be split into several files (Jifty will concatenate them
91	for us anyway) for easier maintenance, probably by same logic as view names
92	to skip additional step of mapping when human are watching into code.
93
94	=head1 BUGS
95
96	Many probably, documented in C<TODO> which is also useful for quick overview
97	what changed between versions if svn commit log is too detailed allthough
98	first line of commit message might be good summary of each individual
99	change.