1: <?php
  2: 
  3: namespace Charcoal\View;
  4: 
  5: // Dependencies from `PHP`
  6: use \InvalidArgumentException;
  7: 
  8: // Local namespace dependencies
  9: use \Charcoal\View\ViewInterface;
 10: 
 11: /**
 12:  * Implementation, as trait, of the {@see \Charcoal\View\ViewableInterface}.
 13:  */
 14: trait ViewableTrait
 15: {
 16:     /**
 17:      * The object's template identifier.
 18:      *
 19:      * @var string
 20:      */
 21:     private $templateIdent;
 22: 
 23:     /**
 24:      * The context for the {@see self::$view} to render templates.
 25:      *
 26:      * @var ViewableInterface
 27:      */
 28:     private $viewController;
 29: 
 30:     /**
 31:      * The renderable view.
 32:      *
 33:      * @var ViewInterface
 34:      */
 35:     private $view;
 36: 
 37:     /**
 38:      * Render the viewable object.
 39:      *
 40:      * @return string
 41:      */
 42:     public function __toString()
 43:     {
 44:         return $this->render();
 45:     }
 46: 
 47:     /**
 48:      * Set the template identifier for this viewable object.
 49:      *
 50:      * Usually, a path to a file containing the template to be rendered at runtime.
 51:      *
 52:      * @param string $templateIdent The template ID.
 53:      * @throws InvalidArgumentException If the template identifier is not a string.
 54:      * @return ViewableInterface Chainable
 55:      */
 56:     public function setTemplateIdent($templateIdent)
 57:     {
 58:         if (!is_string($templateIdent)) {
 59:             throw new InvalidArgumentException(
 60:                 'Template identifier must be a string.'
 61:             );
 62:         }
 63: 
 64:         $this->templateIdent = $templateIdent;
 65: 
 66:         return $this;
 67:     }
 68: 
 69:     /**
 70:      * Retrieve the template identifier for this viewable object.
 71:      *
 72:      * @return string
 73:      */
 74:     public function templateIdent()
 75:     {
 76:         return $this->templateIdent;
 77:     }
 78: 
 79:     /**
 80:      * Set the renderable view.
 81:      *
 82:      * @param ViewInterface|array $view The view instance to use to render.
 83:      * @throws InvalidArgumentException If the view parameter is not an array or a View object.
 84:      * @return ViewableInterface Chainable
 85:      */
 86:     public function setView(ViewInterface $view)
 87:     {
 88:         $this->view = $view;
 89: 
 90:         return $this;
 91:     }
 92: 
 93:     /**
 94:      * Retrieve the renderable view.
 95:      *
 96:      * @return ViewInterface The object's View instance.
 97:      */
 98:     public function view()
 99:     {
100:         return $this->view;
101:     }
102: 
103:     /**
104:      * Render the template by the given identifier.
105:      *
106:      * Usually, a path to a file containing the template to be rendered at runtime.
107:      *
108:      * @param string $templateIdent The template to load, parse, and render.
109:      *     If NULL, will use the object's previously set template identifier.
110:      * @return string The rendered template.
111:      */
112:     public function render($templateIdent = null)
113:     {
114:         if ($templateIdent === null) {
115:             $templateIdent = $this->templateIdent();
116:         }
117: 
118:         return $this->view()->render($templateIdent, $this->viewController());
119:     }
120: 
121:     /**
122:      * Render the given template from string.
123:      *
124:      * @param string $templateString The template  to render from string.
125:      * @return string The rendered template.
126:      */
127:     public function renderTemplate($templateString)
128:     {
129:         return $this->view()->renderTemplate($templateString, $this->viewController());
130:     }
131: 
132:     /**
133:      * Set a view controller for the template's context.
134:      *
135:      * @param ViewableInterface|object|array|null $controller A view controller to use when rendering.
136:      * @throws InvalidArgumentException If the controller is invalid.
137:      * @return ViewableInterface Chainable
138:      */
139:     public function setViewController($controller)
140:     {
141:         if (is_scalar($controller) || is_resource($controller)) {
142:             throw new InvalidArgumentException(
143:                 'View controller must be an object, null or an array'
144:             );
145:         }
146: 
147:         $this->viewController = $controller;
148: 
149:         return $this;
150:     }
151: 
152:     /**
153:      * Retrieve a view controller for the template's context.
154:      *
155:      * If no controller has been defined, it will return itself.
156:      *
157:      * @return ViewableInterface
158:      */
159:     public function viewController()
160:     {
161:         if ($this->viewController === null) {
162:             return $this;
163:         }
164: 
165:         return $this->viewController;
166:     }
167: }
168: