/ 
MKDoc-2.01
/ MKDoc::Setup

NAME

MKDoc::Setup - Generic user setup for the MKDoc framework.

SUMMARY

MKDoc::Setup provides a generic base class to make user-friendly installation procedures for applications which are meant to integrate in the MKDoc framework.

Although this class stands on its two feet, it is a mockup class. It is meant to be subclassed for different installations.

MKDoc::Setup doesn't do anything useful on it's own, however you can run it 'as is' for testing purposes, e.g:

perl -MMKDoc::Setup -e install

If you want to see actual subclasses, look at MKDoc::Setup::MKDoc and MKDoc::Setup::Site.

Methods which you should know about

$self->keys();

You MUST subclass this method.

In this method you define a list of keys which you want configuration values for and in the order in which you want them displayed. For example:

sub keys
{
    my $self = shift;
    return qw /foo bar baz/;
}

Might display something like this once run:

1. Foo: Carrot
2. Bar: Tomato
3. Baz: Banana

$self->label ($key);

You MUST subclass this method.

Returns a human readable label for a given key. In the example above, the menu displays 'Foo' (notice the capital letter) for a key 'foo'. This is done as follows:

sub label
{
    my $self = shift;
  
    $_ = shift;
    /foo/ and return 'Foo';
    /bar/ and return 'Bar';
    /baz/ and return 'Baz';
    return;
}

$self->install();

You MUST subclass this method - assuming you want your installer to actually install things :-)

sub install
{
    # some install code here...
    print "\n\nDone.\n";
    exit (0);
}

$self->initialize();

You MAY subclass this method.

Initializes $self, the setup object. $self is a hash which contains key / value pairs for setup config. This method gives you a chance to initialize your object with sensible, default values before those values are presented to the user.

$self->validate();

You MAY subclass this method.

If you must do any tests on the data to make sure it complies witch whichever validation rules you choose to implement, you can do it by subclassing validate().

Returns TRUE if the object validates, FALSE otherwise.

I suggest your validate method looks like this:

sub validate
{
    my $self = shift;
    $self->validate_xxx() &
    $self->validate_yyy() &
    $self->validate_zzz();
}

sub validate_xxx
{
    my $self = shift;
    $self->some_failure_condition() and do {
        print "Meaningful error message;
        return 0;
    };

    return 1;
}

Other methods / functions

main::install()

Just a bit of syntaxic sugar to ease command line usage, i.e.

perl -MMKDoc::Setup -e install

$self->display_value ($key);

Returns the same as $self->{$key}, except when $self->{$key} is undef.

When $self->{$key} is undef, the string "(undef") is sent back rather than the value itself.

This is used by the menu as a way to display the information 'undef' to the user.

$self->display_error();

When the object does not validate, this method displays a message error and waits for a keystroke before re-displaying the main menu.

$class->new (%args);

Constructor - Creates a new MKDoc::Setup object.

$self->process();

Method which initializes the state of the object to 'display_menu' and starts the FSM mechanism.

$self->display_menu();

Displays the main user menu with a list of options to choose from.

$self->display_value_set();

When the user chooses to set a given value to another value, this method is invoked. It basically prompts the user for the new value.

$self->display_value_delete();

When the user chooses to delete some value, this method is invoked. It basically prompts the user for which value to delete / undefine.

$self->message_prompt ($message, $default_value);

Prompts the user for a value by displaying $message. If the user just hits 'enter', $default_value is returned instead.

$self->cancel();

Cancels the installation process, exits to system.

$self->proceed();

Invokes $self->validate() first. If there are errors, invokes $self->display_error().

Otherwise if everything's OK invokes $self->install() which performs the installation.

$self->get_stdin_line();

Reads one line from <STDIN>, chomps it, and returns it.

AUTHOR

Copyright 2003 - MKDoc Holdings Ltd.

Author: Jean-Michel Hiver <jhiver@mkdoc.com>

This module is free software and is distributed under the same license as Perl itself. Use it at your own risk.

SEE ALSO

Petal: http://search.cpan.org/author/JHIVER/Petal/
MKDoc: http://www.mkdoc.com/

Help us open-source MKDoc. Join the mkdoc-modules mailing list:

mkdoc-modules@lists.webarch.co.uk