SEE ALSO

NAME

org::puremvc::perl5::patterns::facade::Facade

Singleton providing a single entry point for performing MVC pattern actions.

SYNOPSIS

  package com::me::myapp::Facade;

  use strict; use warnings;

  use org::puremvc::perl5::patterns::facade::Facade;
  our @ISA = qw( org::puremvc::perl5::patterns::facade::Facade );

  use base 'Exporter';

  # Notification constants. The Facade is the ideal location for these constants, since any part
  # of the application participating in PureMVC Observer Notification will know the Facade.
  use constant GO_COMMAND => "com::me::myapp::Facade::go";
  our @EXPORT_OK = ('GO_COMMAND');

  use com::me::myapp::MyModel;
  use com::me::myapp::MyView;
  use com::me::myapp::MyController;
  use com::me::myapp::proxies::CountryListProxy;
  use com::me::myapp::mediators::LoginMediator;
  use com::me::myapp::commands::GoCommand;

  my $_instance;

  # Private constructor called by getInstance class method
  my $new = sub {
    my $class = shift;

    my $self = $class->SUPER::getInstance(); # Calls parent class constructor
    bless( $self, $class ); # $self is now an instance of com::me::myapp::Facade class
    
    return $self;
      };

  #**********************
  #**********************
  # Optional overriding of org::puremvc::perl5::patterns::facade::Facade::initializeFacade() method
  # Overriding is necessary if you need to do extra initialization during construction of your own Facade instance
  sub initializeFacade {
    my $self = shift;

    $self->SUPER::initializeFacade();

    # Add special initialization code here
    # If none, no need to override initializeFacade method
  }

  #**********************
  sub getInstance {
    my $class = shift;

    $_instance = $new->($class) if ! defined $_instance;

    return $_instance;
      }

  #**********************
  # Optional overriding of org::puremvc::perl5::patterns::facade::Facade::initializeController() method
  # This where you can register your Commands and define your own Controller singleton
  sub initializeController {
    my $self = shift;

    # The following must not be executed if you use your own Controller class as
    # it is the case here
    #$self->SUPER::initializeController();

    # Registering personal Controller
    $self->{_controller} = com::me::myapp::MyController->getInstance() unless exists $self->{_controller};

    # Command registration for GO_COMMAND notification
    $self->registerCommand( GO_COMMAND, "com::me::myapp::commands::GoCommand" );
      }

  #**********************
  # Optional overriding of org::puremvc::perl5::patterns::facade::Facade::initializeModel() method
  # This where you can register SOME SPECIAL Proxys and define your own Model singleton
  sub initializeModel {
    my $self = shift;

    # The following must not be executed if you use your own Model class as below
    # it is the case here
    #$self->SUPER::initializeModel();

    # Registering personal Model
    $self->{_model} = com::me::myapp::MyModel->getInstance() unless exists $self->{_model};

    # Proxy registration
    # CAREFUL: as initializeModel method is part of Facade construction process,
    # DO NOT register Proxys needing to send notification here as notification sending
    # by a Proxy requires Facade to be constructed.
    $self->registerProxy( com::me::myapp::proxies::CountryListProxy->new() );
      }

  #**********************
  # Optional overriding of org::puremvc::perl5::patterns::facade::Facade::initializeView() method
  # This where you can register SOME SPECIAL Mediators and define your own View singleton
  sub initializeView {
    my $self = shift;

    # The following must not be executed if you use your own View class as below
    # it is the case here
    #$self->SUPER::initializeView();

    # Registering personal View
    $self->{_view} = com::me::myapp::MyView->getInstance() unless exists $self->{_view};

    # Mediator registration
    # CAREFUL: as initializeView method is part of Facade construction process,
    # DO NOT register Mediator needing to access your Facade instance.
    # Usually Mediators send/receive notifications, and are registered elsewhere in the application
    # for this reason.
    $self->registerMediator( com::me::myapp::mediators::LoginMediator->new() );
      }

  #**********************
  #**********************
  1;

DESCRIPTION

In PureMVC, the Facade class assumes these responsibilities:

Initializing the Model, View and Controller singletons.
Providing all the methods defined by the Model, View & Controller singletons.
Providing the ability to override the specific Model, View and Controller singletons created.
Providing a single point of contact to the application for registering Commands and notifying Observers.

Using the Facade interface methods should be sufficient for your application to use all the MVC patterns.

INTERFACE

Methods

getInstance

sub getInstance();

Returns the singleton instance of the Facade. During first call, Facade instance is created. Future calls just return already created instance. Facade creation process includes Model, View & Controller singletons initialization (see initializeFacade method).

Returns

org::puremvc::perl5::patterns::facade::Facade - The singleton instance of the Facade.

initializeFacade

sub initializeFacade();

Automatically called during getInstance method first run (Facade instance creation). This is where Model, View & Controller singletons initialization methods are called. If you use a subclass of Facade, make sure to call SUPER::initializeFacade() during Facade singleton construction.

initializeController

sub initializeController();

Called by initializeFacade method. Override this method in your subclass of Facade if one or both of the following are true:

You wish to initialize your own Controller class.
You have Commands to register with the Controller at startup.

If you don't want to initialize a different Controller call SUPER::initializeController() at the beginning of your method, then register Commands.

initializeModel

sub initializeModel();

Called by initializeFacade method. Override this method in your subclass of Facade if one or both of the following are true:

You wish to initialize your own Model class.
You have Proxies to register with the Model that do not retrieve a reference to the Facade at construction time.

If you don't want to initialize a different Model call SUPER::initializeModel() at the beginning of your method, then register Proxies.

Note: This method is rarely overridden; in practice you are more likely to use a Command to create and register Proxies with the Model, since Proxies with mutable data will likely need to send notifications and thus will likely want to fetch a reference to the Facade during their construction.

initializeView

sub initializeView();

Called by initializeFacade method. Override this method in your subclass of Facade if one or both of the following are true:

You wish to initialize your own View class.
You have Mediators to register with the View that do not retrieve a reference to the Facade at construction time.

If you don't want to initialize a different View call SUPER::initializeView() at the beginning of your method, then register Mediators.

Note: This method is rarely overridden; in practice you are more likely to use a Command to create and register Mediators with the View, since Mediators will likely need to send notifications and thus will likely want to fetch a reference to the Facade during their construction.

registerCommand

sub registerCommand( $notification_name, $command_class_ref );

When a notifier will send a notification whose name is $notification_name, the Controller will create an instance of $command_class_ref Command class and execute its execute method.

$command_class_ref is a string holding the name of the Command class, e.g. "com::me::myapp::MyCommand".

Note that there can only be one and only one Command registered with the Controller for a given notification name. A call to this method will replace any previously registered Command for that notification name.

Parameters

$notification_name - String

Name of the notifications the registered Command will handle.
$command_class_ref - String

Class name of the Command to handle notification called $notification_name.

removeCommand

sub removeCommand( $notification_name );

Remove a previously registered Command with the Controller by notification name.

Parameters

$notification_name - String

Name of the notification for which to remove a registered command.

hasCommand

sub hasCommand( $notification_name );

Check if a Command is registered with the Controller by Notification name.

Parameters

$notification_name - String

Name of the notification for which to check a registered command.

Returns

scalar - 1 if a Command class is registered with the Controller for notifications named $notification_name, "" otherwise.

registerProxy

sub registerProxy( $proxy );

During registration the Model uses Proxy's getProxyName method to map the Proxy instance to its name. This will serve for retrieval of the Proxy instance by its name (see retrieveProxy method).

Parameters

$proxy - org::puremvc::perl5::patterns::proxy::Proxy

A Proxy instance to register with the Model.

retrieveProxy

sub retrieveProxy( $proxy_name );

Retrieve a Proxy from the Model by name.

Parameters

$proxy_name - String

Name of the proxy to retrieve from the Model.

Returns

org::puremvc::perl5::patterns::proxy::Proxy - The Proxy instance retrieved from the Model.

removeProxy

sub removeProxy( $proxy_name );

Remove a Proxy from the Model by name.

Parameters

$proxy_name - String

Name of the proxy to remove from the Model.

Returns

org::puremvc::perl5::patterns::proxy::Proxy - The Proxy instance removed from the Model.

hasProxy

sub hasProxy( $proxy_name );

Check if a Proxy is registered with the Model by name.

Parameters

$proxy_name - String

Name of the proxy to check.

Returns

scalar - 1 if a Proxy instance is registered with the Model with name $proxy_name, "" otherwise.

registerMediator

sub registerMediator( $mediator );

During registration the View uses Mediator's getMediatorName method to map the Mediator instance to its name. This will serve for retrieval of the Mediator instance by its name (see retrieveMediator method).

Parameters

$mediator - org::puremvc::perl5::patterns::mediator::Mediator

A Mediator instance to register with the View.

retrieveMediator

sub retrieveMediator( $mediator_name );

Retrieve a Mediator from the View by name.

Parameters

$mediator_name - String

Name of the mediator to retrieve from the View.

Returns

org::puremvc::perl5::patterns::mediator::Mediator - The Mediator instance retrieved from the View.

removeMediator

sub removeMediator( $mediator_name );

Remove a Mediator from the View by name.

Parameters

$mediator_name - String

Name of the mediator to remove from the View.

Returns

org::puremvc::perl5::patterns::mediator::Mediator - The Mediator instance removed from the View.

hasMediator

sub hasMediator( $mediator_name );

Check if a Mediator is registered with the View by name.

Parameters

$mediator_name - String

Name of the mediator to check.

Returns

scalar - 1 if a Mediator instance is registered with the View with name $mediator_name, "" otherwise.

sendNotification

sub sendNotification( $notification_name, $body, $type );

Keeps us from having to construct new Notification objects in our implementation code.

This method will construct a new Notification named $notification_name with optional $body and $type parameters.

Parameters

$notification_name - String

Name of the constructed Notification instance.
$body - *

Body or (business data) of the notification. Can be any object or scalar. - Optional
$type - *

Type of the notification. This data can be useful to distinguish several types of the same Notification. Usually is a string but could be any other object or scalar. - Optional

notifyObservers

sub notifyObservers( $notification );

You should not have to use this method ; instead use sendNotification method to notify registered observers for $notification.

Parameters

$notification - org::puremvc::perl5::patterns::observer::Notification

Instance of Notification the observers will receive as a parameter when notified.

Properties

_model: Holds the Model singleton instance of the application. You should not have to access it and must not update it in normal usage.
_view: Holds the View singleton instance of the application. You should not have to access it and must not update it in normal usage.
_controller: Holds the Controller singleton instance of the application. You should not have to access it and must not update it in normal usage.

NAME

SYNOPSIS

DESCRIPTION

INTERFACE

Methods

Properties

SEE ALSO