view release on metacpan or  search on metacpan

lib/Konstrukt/Lib.pm  view on Meta::CPAN

The backend modules themselves pass a string containing SQL-statements
(among others) to create the needed tables.

The section for the creation is named C<dbi: create>. The section must be
declared using the scheme described in L</extract_data_sections>.

The statements in each block are separated through semicolons.

Example:

	-- 8< -- dbi: create -- >8 --
	
	CREATE TABLE IF NOT EXISTS foo ( <definition> );
	CREATE TABLE IF NOT EXISTS bar ( <definition> );

The backend plugin stores these SQL-statements in it's C<__DATA__>-section
at the end of the file.

The C<install> method of the backend module then can get as simple as:

	sub install {
		my ($self) = @_;
		return $Konstrukt::Lib->plugin_dbi_install_helper($self->{db_settings});
	}

This method returns true on success.

B<Parameters:>

=over

=item * $db - Either an array reference containing the DBI source, user and
password of the database your backend uses or a database handle to this db.

=back

=cut
sub plugin_dbi_install_helper {
	my ($self, $db) = @_;
	
	#determine calling package
	my $package = caller;
	
	#use supplied dbh or create one from the supplied db connection settings
	my $dbh;
	if ((ref $db) =~ /^(Apache::)?DBI::db$/) {
		$dbh = $db;
	} elsif (ref $db eq 'ARRAY') {
		$dbh = $Konstrukt::DBI->get_connection(@{$db})
	} else {
		$Konstrukt::Debug->error_message("Cannot install DBI backend for plugin $package: Parameter \$db is neither a database handle nor an arrayref containing database connection settings.") if Konstrukt::Debug::ERROR;
		return;
	}
	
	$Konstrukt::Debug->debug_message("Installing DBI backend for plugin $package") if Konstrukt::Debug::INFO;
	
	#extract relevant sections
	my $sections = $self->extract_data_sections($package);
	
	#only take the relevant sections and split multiple queries into single queries
	my @queries = split /;/, ($sections->{'dbi: create'} || '');
	
	#create tables
	foreach my $query (@queries) {
		next if $query =~ /^\s*$/; #skip "empty" queries
		$dbh->do($query) or return;
	}
	
	return 1;
}
# /plugin_dbi_install_helper

=head2 plugin_file_install_helper

May be used to do the installation work of the necessary files (like templates
or images) of some plugins.

The section for the each text file (e.g. a template) is named
C<textfile: subfolder/name.extension>.
The section must be declared using the scheme described in L</extract_data_sections>.
The section for a binary file must be named C<binaryfile: subfolder/name.extension>.
The content of the binary file must be base64 encoded and put into the section.
(You can use the supplied script C<base64enc.pl> which reads from STDIN and
writes the encoded data to STDOUT.)

The path/filename of template files should follow this scheme:

	<template type>/<name of the template>.template

C<template type> should be used to group different types of templates.
This may be:

=over

=item * layout: Templates to display the data

=item * messages: Templates to display messages like errors (e.g. "permission
denied") and confirmations (e.g. "entry successfully created") 

=back

Of course you can use other "directory names".

If the filename starts with a slash (C</>), the path will not be prepended by the
basepath. It will be put into the document root.

Example:

	-- 8< -- textfile: layout/display.template -- >8 --
	
	This is the data:
	<+$ data $+>(no data specified)<+$ / $+>

	-- 8< -- textfile: layout/display_something_else.template -- >8 --
	
	-- 8< -- binaryfile: /gfx/some_icon.gif -- >8 --
	
	R0lGODlhEAAQAKIAAEuVzf+MO////v96G/fMrdDj8v/izf+1fyH5BAAAAAAALAAAAAAQABAAAANE
	KLrcziQMOZ8gI2sCOliYNhmC9wmHWCkmqh6MGWpw7M0D4cgi2fCi2qKVCto6iqIm4GspcCNBYVpg
	GFQ5i8AgoQy0jwQAOw==