1. sfView.class.php
  2. /**
 * A view represents the presentation layer of an action. Output can be
 * customized by supplying attributes, which a template can manipulate and
 * display.
 *
 * @package    symfony
 * @subpackage view
 * @author     Fabien Potencier 
 * @author     Sean Kerr 
 * @version    SVN: $Id: sfView.class.php 23940 2009-11-14 17:58:19Z fabien $
 */
  3. abstract class sfView
  4. {
  5.   /**
  6.    * Show an alert view.
  7.    */
  8.   const ALERT = 'Alert';
  10.   /**
  11.    * Show an error view.
  12.    */
  13.   const ERROR = 'Error';
  15.   /**
  16.    * Show a form input view.
  17.    */
  18.   const INPUT = 'Input';
  20.   /**
  21.    * Skip view execution.
  22.    */
  23.   const NONE = 'None';
  25.   /**
  26.    * Show a success view.
  27.    */
  28.   const SUCCESS = 'Success';
  30.   /**
  31.    * Do not render the presentation.
  32.    */
  33.   const RENDER_NONE = 1;
  35.   /**
  36.    * Render the presentation to the client.
  37.    */
  38.   const RENDER_CLIENT = 2;
  40.   /**
  41.    * Render the presentation to a variable.
  42.    */
  43.   const RENDER_VAR = 4;
  45.   /**
  46.    * Skip view rendering but output http headers
  47.    */
  48.   const HEADER_ONLY = 8;
  50.   protected
  51.     $context            = null,
  52.     $dispatcher         = null,
  53.     $decorator          = false,
  54.     $decoratorDirectory = null,
  55.     $decoratorTemplate  = null,
  56.     $directory          = null,
  57.     $componentSlots     = array(),
  58.     $template           = null,
  59.     $attributeHolder    = null,
  60.     $parameterHolder    = null,
  61.     $moduleName         = '',
  62.     $actionName         = '',
  63.     $viewName           = '',
  64.     $extension          = '.php';
  66.   /**
  67.    * Class constructor.
  68.    *
  69.    * @see initialize()
  70.    */
  71.   public function __construct($context, $moduleName, $actionName, $viewName)
  72.   {
  73.     $this->initialize($context, $moduleName, $actionName, $viewName);
  74.   }
  76.   /**
  77.    * Initializes this view.
  78.    *
  79.    * @param  sfContext $context     The current application context
  80.    * @param  string    $moduleName  The module name for this view
  81.    * @param  string    $actionName  The action name for this view
  82.    * @param  string    $viewName    The view name
  83.    *
  84.    * @return bool  true, if initialization completes successfully, otherwise false
  85.    */
  86.   public function initialize($context, $moduleName, $actionName, $viewName)
  87.   {
  88.     $this->moduleName = $moduleName;
  89.     $this->actionName = $actionName;
  90.     $this->viewName   = $viewName;
  92.     $this->context    = $context;
  93.     $this->dispatcher = $context->getEventDispatcher();
  95.     sfOutputEscaper::markClassesAsSafe(array('sfForm', 'sfFormField', 'sfFormFieldSchema', 'sfModelGeneratorHelper'));
  97.     $this->attributeHolder = $this->initializeAttributeHolder();
  99.     $this->parameterHolder = new sfParameterHolder();
  100.     $this->parameterHolder->add(sfConfig::get('mod_'.strtolower($moduleName).'_view_param', array()));
  102.     $request = $context->getRequest();
  104.     $format = $request->getRequestFormat();
  105.     if (null !== $format)
  106.     {
  107.       if ('html' != $format)
  108.       {
  109.         $this->setExtension('.'.$format.$this->getExtension());
  110.       }
  112.       if ($mimeType = $request->getMimeType($format))
  113.       {
  114.         $this->context->getResponse()->setContentType($mimeType);
  116.         if ('html' != $format)
  117.         {
  118.           $this->setDecorator(false);
  119.         }
  120.       }
  121.     }
  122.     $this->dispatcher->notify(new sfEvent($this, 'view.configure_format', array('format' => $format, 'response' => $context->getResponse(), 'request' => $context->getRequest())));
  124.     // include view configuration
  125.     $this->configure();
  127.     return true;
  128.   }
  130.   protected function initializeAttributeHolder($attributes = array())
  131.   {
  132.     $attributeHolder = new sfViewParameterHolder($this->dispatcher, $attributes, array(
  133.       'escaping_method'   => sfConfig::get('sf_escaping_method'),
  134.       'escaping_strategy' => sfConfig::get('sf_escaping_strategy'),
  135.     ));
  137.     return $attributeHolder;
  138.   }
  140.   /**
  141.    * Executes any presentation logic and set template attributes.
  142.    */
  143.   abstract function execute();
  145.   /**
  146.    * Configures template.
  147.    */
  148.   abstract function configure();
  150.   /**
  151.    * Retrieves this views decorator template directory.
  152.    *
  153.    * @return string An absolute filesystem path to this views decorator template directory
  154.    */
  155.   public function getDecoratorDirectory()
  156.   {
  157.     return $this->decoratorDirectory;
  158.   }
  160.   /**
  161.    * Retrieves this views decorator template.
  162.    *
  163.    * @return string A template filename, if a template has been set, otherwise null
  164.    */
  165.   public function getDecoratorTemplate()
  166.   {
  167.     return $this->decoratorTemplate;
  168.   }
  170.   /**
  171.    * Retrieves this view template directory.
  172.    *
  173.    * @return string An absolute filesystem path to this views template directory
  174.    */
  175.   public function getDirectory()
  176.   {
  177.     return $this->directory;
  178.   }
  180.   /**
  181.    * Retrieves the template engine associated with this view.
  182.    *
  183.    * Note: This will return null for PHPView instances.
  184.    *
  185.    * @return mixed A template engine instance
  186.    */
  187.   abstract function getEngine();
  189.   /**
  190.    * Retrieves this views template.
  191.    *
  192.    * @return string A template filename, if a template has been set, otherwise null
  193.    */
  194.   public function getTemplate()
  195.   {
  196.     return $this->template;
  197.   }
  199.   /**
  200.    * Retrieves attributes for the current view.
  201.    *
  202.    * @return sfParameterHolder The attribute parameter holder
  203.    */
  204.   public function getAttributeHolder()
  205.   {
  206.     return $this->attributeHolder;
  207.   }
  209.   /**
  210.    * Retrieves an attribute for the current view.
  211.    *
  212.    * @param  string $name     Name of the attribute
  213.    * @param  string $default  Value of the attribute
  214.    *
  215.    * @return mixed Attribute
  216.    */
  217.   public function getAttribute($name, $default = null)
  218.   {
  219.     return $this->attributeHolder->get($name, $default);
  220.   }
  222.   /**
  223.    * Returns true if the view have attributes.
  224.    *
  225.    * @param  string $name  Name of the attribute
  226.    *
  227.    * @return mixed Attribute of the view
  228.    */
  229.   public function hasAttribute($name)
  230.   {
  231.     return $this->attributeHolder->has($name);
  232.   }
  234.   /**
  235.    * Sets an attribute of the view.
  236.    *
  237.    * @param string $name   Attribute name
  238.    * @param string $value  Value for the attribute
  239.    */
  240.   public function setAttribute($name, $value)
  241.   {
  242.     $this->attributeHolder->set($name, $value);
  243.   }
  245.   /**
  246.    * Retrieves the parameters for the current view.
  247.    *
  248.    * @return sfParameterHolder The parameter holder
  249.    */
  250.   public function getParameterHolder()
  251.   {
  252.     return $this->parameterHolder;
  253.   }
  255.   /**
  256.    * Retrieves a parameter from the current view.
  257.    *
  258.    * @param  string $name     Parameter name
  259.    * @param  string $default  Default parameter value
  260.    *
  261.    * @return mixed A parameter value
  262.    */
  263.   public function getParameter($name, $default = null)
  264.   {
  265.     return $this->parameterHolder->get($name, $default);
  266.   }
  268.   /**
  269.    * Indicates whether or not a parameter exist for the current view.
  270.    *
  271.    * @param  string $name  Name of the paramater
  272.    *
  273.    * @return bool true, if the parameter exists otherwise false
  274.    */
  275.   public function hasParameter($name)
  276.   {
  277.     return $this->parameterHolder->has($name);
  278.   }
  280.   /**
  281.    * Sets a parameter for the view.
  282.    *
  283.    * @param string $name   Name of the parameter
  284.    * @param string $value  The parameter value
  285.    */
  286.   public function setParameter($name, $value)
  287.   {
  288.     $this->parameterHolder->set($name, $value);
  289.   }
  291.   /**
  292.    * Indicates that this view is a decorating view.
  293.    *
  294.    * @return bool true, if this view is a decorating view, otherwise false
  295.    */
  296.   public function isDecorator()
  297.   {
  298.     return $this->decorator;
  299.   }
  301.   /**
  302.    * Sets the decorating mode for the current view.
  303.    *
  304.    * @param bool $boolean  Set the decorating mode for the view
  305.    */
  306.   public function setDecorator($boolean)
  307.   {
  308.     $this->decorator = (boolean) $boolean;
  310.     if (false === $boolean)
  311.     {
  312.       $this->decoratorTemplate = false;
  313.     }
  314.   }
  316.   /**
  317.    * Executes a basic pre-render check to verify all required variables exist
  318.    * and that the template is readable.
  319.    *
  320.    * @throws sfRenderException If the pre-render check fails
  321.    */
  322.   protected function preRenderCheck()
  323.   {
  324.     if (null === $this->template)
  325.     {
  326.       // a template has not been set
  327.       throw new sfRenderException('A template has not been set.');
  328.     }
  330.     if (!is_readable($this->directory.'/'.$this->template))
  331.     {
  332.       // 404?
  333.       if ('404' == $this->context->getResponse()->getStatusCode())
  334.       {
  335.         // use default exception templates
  336.         $this->template = sfException::getTemplatePathForError($this->context->getRequest()->getRequestFormat(), false);
  337.         $this->directory = dirname($this->template);
  338.         $this->template = basename($this->template);
  339.         $this->setAttribute('code', '404');
  340.         $this->setAttribute('text', 'Not Found');
  341.       }
  342.       else
  343.       {
  344.         throw new sfRenderException(sprintf('The template "%s" does not exist or is unreadable in "%s".', $this->template, $this->directory));
  345.       }
  346.     }
  348.     // check to see if this is a decorator template
  349.     if ($this->decorator && !is_readable($this->decoratorDirectory.'/'.$this->decoratorTemplate))
  350.     {
  351.       throw new sfRenderException(sprintf('The decorator template "%s" does not exist or is unreadable in "%s".', $this->decoratorTemplate, $this->decoratorDirectory));
  352.     }
  353.   }
  355.   /**
  356.    * Renders the presentation.
  357.    *
  358.    * @return string A string representing the rendered presentation
  359.    */
  360.   abstract function render();
  362.   /**
  363.    * Sets the decorator template directory for this view.
  364.    *
  365.    * @param string $directory  An absolute filesystem path to a template directory
  366.    */
  367.   public function setDecoratorDirectory($directory)
  368.   {
  369.     $this->decoratorDirectory = $directory;
  370.   }
  372.   /**
  373.    * Sets the decorator template for this view.
  374.    *
  375.    * If the template path is relative, it will be based on the currently
  376.    * executing module's template sub-directory.
  377.    *
  378.    * @param string $template  An absolute or relative filesystem path to a template
  379.    */
  380.   public function setDecoratorTemplate($template)
  381.   {
  382.     if (false === $template)
  383.     {
  384.       $this->setDecorator(false);
  386.       return;
  387.     }
  388.     else if (null === $template)
  389.     {
  390.       return;
  391.     }
  393.     if (!strpos($template, '.'))
  394.     {
  395.       $template .= $this->getExtension();
  396.     }
  398.     if (sfToolkit::isPathAbsolute($template))
  399.     {
  400.       $this->decoratorDirectory = dirname($template);
  401.       $this->decoratorTemplate  = basename($template);
  402.     }
  403.     else
  404.     {
  405.       $this->decoratorDirectory = $this->context->getConfiguration()->getDecoratorDir($template);
  406.       $this->decoratorTemplate = $template;
  407.     }
  409.     // set decorator status
  410.     $this->decorator = true;
  411.   }
  413.   /**
  414.    * Sets the template directory for this view.
  415.    *
  416.    * @param string $directory  An absolute filesystem path to a template directory
  417.    */
  418.   public function setDirectory($directory)
  419.   {
  420.     $this->directory = $directory;
  421.   }
  423.   /**
  424.    * Sets the module and action to be executed in place of a particular template attribute.
  425.    *
  426.    * @param string $attributeName  A template attribute name
  427.    * @param string $moduleName     A module name
  428.    * @param string $componentName  A component name
  429.    */
  430.   public function setComponentSlot($attributeName, $moduleName, $componentName)
  431.   {
  432.     $this->componentSlots[$attributeName]                   = array();
  433.     $this->componentSlots[$attributeName]['module_name']    = $moduleName;
  434.     $this->componentSlots[$attributeName]['component_name'] = $componentName;
  435.   }
  437.   /**
  438.    * Indicates whether or not a component slot exists.
  439.    *
  440.    * @param  string $name  The component slot name
  441.    *
  442.    * @return bool true, if the component slot exists, otherwise false
  443.    */
  444.   public function hasComponentSlot($name)
  445.   {
  446.     return isset($this->componentSlots[$name]);
  447.   }
  449.   /**
  450.    * Gets a component slot
  451.    *
  452.    * @param  string $name  The component slot name
  453.    *
  454.    * @return array The component slot
  455.    */
  456.   public function getComponentSlot($name)
  457.   {
  458.     if (isset($this->componentSlots[$name]) && $this->componentSlots[$name]['module_name'] && $this->componentSlots[$name]['component_name'])
  459.     {
  460.       return array($this->componentSlots[$name]['module_name'], $this->componentSlots[$name]['component_name']);
  461.     }
  463.     return null;
  464.   }
  466.   /**
  467.    * Sets the template for this view.
  468.    *
  469.    * If the template path is relative, it will be based on the currently
  470.    * executing module's template sub-directory.
  471.    *
  472.    * @param string $template  An absolute or relative filesystem path to a template
  473.    */
  474.   public function setTemplate($template)
  475.   {
  476.     if (sfToolkit::isPathAbsolute($template))
  477.     {
  478.       $this->directory = dirname($template);
  479.       $this->template  = basename($template);
  480.     }
  481.     else
  482.     {
  483.       $this->directory = $this->context->getConfiguration()->getTemplateDir($this->moduleName, $template);
  484.       $this->template = $template;
  485.     }
  486.   }
  488.   /**
  489.    * Retrieves the current view extension.
  490.    *
  491.    * @return string The extension for current view.
  492.    */
  493.   public function getExtension()
  494.   {
  495.     return $this->extension;
  496.   }
  498.   /**
  499.    * Sets an extension for the current view.
  500.    *
  501.    * @param string $extension  The extension name.
  502.    */
  503.   public function setExtension($extension)
  504.   {
  505.     $this->extension = $extension;
  506.   }
  508.   /**
  509.    * Gets the module name associated with this view.
  510.    *
  511.    * @return string A module name
  512.    */
  513.   public function getModuleName()
  514.   {
  515.     return $this->moduleName;
  516.   }
  518.   /**
  519.    * Gets the action name associated with this view.
  520.    *
  521.    * @return string An action name
  522.    */
  523.   public function getActionName()
  524.   {
  525.     return $this->actionName;
  526.   }
  528.   /**
  529.    * Gets the view name associated with this view.
  530.    *
  531.    * @return string An action name
  532.    */
  533.   public function getViewName()
  534.   {
  535.     return $this->viewName;
  536.   }
  538.   /**
  539.    * Calls methods defined via sfEventDispatcher.
  540.    *
  541.    * @param  string $method     The method name
  542.    * @param  array  $arguments  The method arguments
  543.    *
  544.    * @return mixed The returned value of the called method
  545.    *
  546.    * @throws sfException< If the calls fails
  547.    */
  548.   public function __call($method, $arguments)
  549.   {
  550.     $event = $this->dispatcher->notifyUntil(new sfEvent($this, 'view.method_not_found', array('method' => $method, 'arguments' => $arguments)));
  551.     if (!$event->isProcessed())
  552.     {
  553.       throw new sfException(sprintf('Call to undefined method %s::%s.', get_class($this), $method));
  554.     }
  556.     return $event->getReturnValue();
  557.   }
  558. }
Debug toolbar