view release on metacpan or  search on metacpan

lib/App/Office/Contacts.pm  view on Meta::CPAN

=head1 Description

C<App::Office::Contacts> implements a utf8-aware, web-based, private and group contacts manager.

Here 'private' means you can specify which contacts are not to appear in the search results of other
people using the same database. You do this by setting their visibility to 'Just me'.

C<App::Office::Contacts> uses the light-weight module L<Moo>.

Major features:

=over 4

=item o utf8-aware

=item o Any number of people

=item o Any number of organizations

=item o People can have any number of occupations

=item o Organizations can have any number of staff

=item o People and organizations can have any number of notes

These are displayed with the most recent notes first.

=item o Supports using any database server having a Perl interface

This is controlled via a config file.

=item o 1 to 4 email addresses per person or organization

4 was chosen just to limit the amount of screen real estate occupied. It can be easily changed.

=item o 1 to 4 phone numbers per person or organization

=item o Installers can provide their own FAQ page

=item o On-screen information hidden in tabs is updated if appropriate

For example, if you add a person to the staff list for an organization, and the details for that person
are on another, hidden, tab (the organization tab must have the focus), then the list of occupations for
that peson is updated as soon as they are added.

=item o jQuery-style autocomplete is used for various fields

The list of fields which support autocomplete are listed both on the appropriate forms and on the default
FAQ page.

=item o An add-on package supports importing vCards, as probably output by your email client

=item o An add-on package supports donations per person and per organization

But L<App::Office::Contacts::Donations> has not yet been updated to match V 2.00 of C<App::Office::Contacts>.

=back

Screen shots:

L<The database schema|http://savage.net.au/Module-reviews/images/Contacts/contacts.schema.png>.

L<Sample search results|http://savage.net.au/Module-reviews/images/Contacts/search.results.png>.

L<Sample personal details|http://savage.net.au/Module-reviews/images/Contacts/personal.details.png>.
The organizational details form is very similar.

=head1 Distributions

This module is available as a Unix-style distro (*.tgz).

See L<http://savage.net.au/Perl-modules/html/installing-a-module.html> for
help on unpacking and installing distros.

=head1 Installation

=head2 Installation Pre-requisites

=head3 A note to beginners

At various places I refer to a file, C<share/.htoffice.contacts.conf>,
shipped with this distro.

Please realize that if you edit this file, you must ensure the copy you are editing
is the one used by the code at run-time.

After a module such as this is installed, the code will look for that file
in the directory where I<you> have installed this config file, by running:

	shell> perl scripts/copy.config.pl

The module which reads the file is L<App::Office::Contacts::Util::Config>.

scripts/copy.config.pl installs C<.htoffice.contacts.conf> into a shared directory.

So, if you unpack the distro and edit the file within the unpacked code, you will still need
to copy the patched version by running:

	shell> perl scripts/copy.config.pl
	shell> perl scripts/find.config.pl (as a cross-check)

Alternately, edit the installed copy rather than the copy shipped with the distro.

There is no need to restart your web server after updating this file.

=head3 jQuery, jQuery UI and DataTables

This module does not ship with any of these Javascript libraries. You can get them from:

	http://jquery.com/
	http://jqueryui.com/
	http://datatables.net/

Most development was done using jQuery V 1.8.1, which ships with jQuery V 1.9.2. Lastly, DataTables
V 1.9.4 was used too.

See C<share/.htoffice.contacts.conf>, around lines 23 .. 25 and 61 .. 63, where it
specifies the URLs used by the code to access these libs.

As always, do this after patching the config file:

	shell> perl scripts/copy.config.pl
	shell> perl scripts/find.config.pl (as a cross-check)

Alternately, edit the installed copy rather than the copy shipped with the distro.

lib/App/Office/Contacts.pm  view on Meta::CPAN

=head2 Why not allow multiple Facebook and Twitter tags per org or person?

This is under consideration.

=head2 How can I update the spouses table?

You cannot. I have not yet decided how to provide an on-screen mechanism to update this table.

=head2 How is the code structured?

MVC (Model-View-Controller).

The sample scripts I<contacts.cgi> and I<contacts> use

	prefix => 'App::Office::Contacts::Controller'

so the files in C<lib/App/Office/Contacts/Controller> and C<lib/App/Office/Contacts/Controller/Exporter> are the
modules which are run to respond to http requests.

Files in C<lib/App/Office/Contacts/View> implement views, and those in C<lib/App/Office/Contacts/Database>
implement the model.

Files in C<lib/App/Office/Contacts/Util> are a mixture:

=over 4

=item Config.pm

This is used by all code.

=item Create.pm

This is just used to create tables, populate them, and drop them.

Hence it will not be used by C<CGI> scripts, unless you write such a script yourself.

=item Validator.pm

This is used to validate CGI form data.

=back

=head2 Why did you use Sub::Exporter?

The way I wrote the code, various pairs of classes, e.g.
L<App::Office::Contacts::Controller::Note> and
L<App::Office::Contacts::Donations::Controller::Note>, could share a lot of code,
but they had incompatible parents. Sub::Exporter solved this problem.

And since Controller.pm is derived from CGI::Snapp and not Moo, we cannot use Moo::Role.

=head2 In the source, it seems you use singular words for the names of arrays and array refs.

Yes I do. I think in terms of the nature of each element, not the storage mechanism.

I have switched to plurals for the names of database tables though.

=head2 What is the database schema?

L<The database schema|http://savage.net.au/Module-reviews/images/Contacts/contacts.schema.png>.

The file was created with dbigraph.pl.

dbigraph.pl ships with C<GraphViz::DBI>. I patched it to use C<GraphViz::DBI::General>.

The command is:

	dbigraph.pl --dsn 'dbi:Pg:dbname=contacts' --user contact --pass contact > docs/contacts.schema.png

The username and password are as shipped in C<share/.htapp.office.contacts.conf>.

As always after editing the config file, run:

	shell> perl scripts/copy.config.pl
	shell> perl scripts/find.config.pl (as a cross-check)

Alternately, edit the installed copy rather than the copy shipped with the distro.

=head2 Why do the email_addresses and phone_numbers tables have upper-case fields?

Because the search feature always uses upper-case. And, e.g., phones can have eXtension information built-in,
as in '123456x78'. So the 'x' in a search request needs to be upper-cased. And yes, I have worked on a
personnel + phone number system (at Monash University) which stores (Malaysian) phone numbers like that.

The case for email addresses is rather more obvious.

=head2 Does the database server have pre-requisites?

The code is DBI-based, of course.

Also, the code assumes the database server supports $dbh -> last_insert_id(undef, undef, $table_name, undef).

=head2 What engine type do you use when I use MySQL?

Engine type defaults to innodb when you use MySQL in the dsn.

See C<share/.htapp.office.contacts.conf> for the dsn and the source code of L<App::Office::Contacts::Util::Create>
for the create statements.

As always after editing the config file, run:

	shell> perl scripts/copy.config.pl
	shell> perl scripts/find.config.pl (as a cross-check)

Alternately, edit the installed copy rather than the copy shipped with the distro.

=head2 How do I add tables to the schema?

Do all of these things:

=over 4

=item o Choose a new name which does not conflict with names used by my add-on packages!

=item o Add the table initialization code to C<App::Office::Contacts::Util::Create>

You will need code to create, drop and (perhaps) populate your new table.

There are many examples already in that module.

=item o Add your code to utilize the new table

=back

=head2 Please explain the program, text file, and database table names

Programs are shipped in scripts/, and data files in data/.