MonoRail/Castle.MonoRail.Framework/ViewComponent.cs

   1 // Copyright 2004-2007 Castle Project - http://www.castleproject.org/
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 namespace Castle.MonoRail.Framework
  16 {
  17         using System;
  18         using System.Collections.Specialized;
  19         using System.IO;
  20         using System.Collections;
  21         using System.Reflection;
  22         using System.Web;
  23         using Castle.Components.Binder;
  24
  25         /// <summary>
  26         /// Base class for reusable UI Components.
  27         /// </summary>
  28         /// <remarks>
  29         /// Implementors should override <see cref="ViewComponent.Initialize"/>
  30         /// for implement proper initialization (if necessary).
  31         /// Also implement <see cref="ViewComponent.Render"/> as by default it
  32         /// will render a <c>default</c> view on <c>[ViewFolderRoot]/components/[componentname]</c>.
  33         /// <para>
  34         /// You can also override <see cref="ViewComponent.SupportsSection"/> if your component supports
  35         /// neste sections (ie templates provided on the view that uses the view component.
  36         /// </para>
  37         /// <para>
  38         /// Another way is to use the <see cref="ViewComponentDetailsAttribute"/> to specify a custom name
  39         /// and the sections supported.
  40         /// </para>
  41         /// <para>
  42         /// Notice that view components can render strings or views on their folder. You can
  43         /// create sophisticate components with that mixture. Sections allow the users of your component
  44         /// to give it a block of content, usually customizing or definiting the content to be especially
  45         /// rendered by your component.
  46         /// </para>
  47         ///
  48         /// <example>
  49         /// A very simplist view component that renders the time.
  50         /// <code>
  51         /// public class ShowTime : ViewComponent
  52         /// {
  53         ///             public override void Initialize()
  54         ///             {
  55         ///             }
  56         ///
  57         ///             public override void Render()
  58         ///             {
  59         ///                     RenderText("Time: " + DateTime.Now.ToString());
  60         ///             }
  61         /// }
  62         /// </code>
  63         /// <para>
  64         /// This can be used from the view using the following syntax (NVelocity view engine)
  65         /// </para>
  66         /// <code>
  67         /// #component(ShowTime)
  68         /// </code>
  69         /// </example>
  70         /// </remarks>
  71         public abstract class ViewComponent
  72         {
  73                 /// <summary>
  74                 /// Holds the component context
  75                 /// </summary>
  76                 private IViewComponentContext context;
  77
  78                 /// <summary>
  79                 /// Holds the <see cref="IRailsEngineContext"/> associated
  80                 /// to the request lifetime.
  81                 /// </summary>
  82                 private IRailsEngineContext railsContext;
  83
  84                 private string[] sectionsFromAttribute;
  85
  86                 #region "Internal" core methods
  87
  88                 /// <summary>
  89                 /// Invoked by the framework.
  90                 /// </summary>
  91                 /// <param name="engineContext">Request context</param>
  92                 /// <param name="componentContext">ViewComponent context</param>
  93                 public void Init(IRailsEngineContext engineContext, IViewComponentContext componentContext)
  94                 {
  95                         railsContext = engineContext;
  96                         context = componentContext;
  97
  98                         BindComponentParameters();
  99
 100                         Initialize();
 101                 }
 102
 103                 /// <summary>
 104                 /// Binds the component parameters.
 105                 /// </summary>
 106                 private void BindComponentParameters()
 107                 {
 108                         IConverter converter = new DefaultConverter();
 109
 110                         PropertyInfo[] properties = GetType().GetProperties(BindingFlags.Public | BindingFlags.Instance);
 111
 112                         foreach(PropertyInfo property in properties)
 113                         {
 114                                 if (!property.CanWrite) continue;
 115
 116                                 object[] attributes = property.GetCustomAttributes(typeof(ViewComponentParamAttribute), true);
 117
 118                                 if (attributes.Length == 1)
 119                                 {
 120                                         BindParameter((ViewComponentParamAttribute) attributes[0], property, converter);
 121                                 }
 122                         }
 123                 }
 124
 125                 private void BindParameter(ViewComponentParamAttribute paramAtt, PropertyInfo property, IConverter converter)
 126                 {
 127                         string compParamKey = string.IsNullOrEmpty(paramAtt.ParamName) ? property.Name : paramAtt.ParamName;
 128
 129                         object value = ComponentParams[compParamKey];
 130
 131                         if (value == null)
 132                         {
 133                                 if (paramAtt.Required &&
 134                                         (property.PropertyType.IsValueType || property.GetValue(this, null) == null))
 135                                 {
 136                                         throw new ViewComponentException(string.Format("The parameter '{0}' is required by " +
 137                                                 "the ViewComponent {1} but was not passed or had a null value", compParamKey, GetType().Name));
 138                                 }
 139                         }
 140                         else
 141                         {
 142                                 try
 143                                 {
 144                                         bool succeeded;
 145
 146                                         object converted = converter.Convert(property.PropertyType, value.GetType(), value, out succeeded);
 147
 148                                         if (succeeded)
 149                                         {
 150                                                 property.SetValue(this, converted, null);
 151                                         }
 152                                         else
 153                                         {
 154                                                 throw new Exception("Could not convert '" + value + "' to type " + property.PropertyType);
 155                                         }
 156                                 }
 157                                 catch(Exception ex)
 158                                 {
 159                                         throw new ViewComponentException(string.Format("Error trying to set value for parameter '{0}' " +
 160                                                 "on ViewComponent {1}: {2}", compParamKey, GetType().Name, ex.Message), ex);
 161                                 }
 162                         }
 163                 }
 164
 165                 #endregion
 166
 167                 #region Lifecycle methods (overridables)
 168
 169                 /// <summary>
 170                 /// Called by the framework once the component instance
 171                 /// is initialized
 172                 /// </summary>
 173                 public virtual void Initialize()
 174                 {
 175                 }
 176
 177                 /// <summary>
 178                 /// Called by the framework so the component can
 179                 /// render its content
 180                 /// </summary>
 181                 public virtual void Render()
 182                 {
 183                         RenderView("default");
 184                 }
 185
 186                 /// <summary>
 187                 /// Implementor should return true only if the
 188                 /// <c>name</c> is a known section the view component
 189                 /// supports.
 190                 /// </summary>
 191                 /// <param name="name">section being added</param>
 192                 /// <returns><see langword="true"/> if section is supported</returns>
 193                 public virtual bool SupportsSection(string name)
 194                 {
 195                         // TODO: We need to cache this
 196
 197                         if (sectionsFromAttribute == null)
 198                         {
 199                                 object[] attributes = GetType().GetCustomAttributes(typeof(ViewComponentDetailsAttribute), true);
 200
 201                                 if (attributes.Length != 0)
 202                                 {
 203                                         ViewComponentDetailsAttribute detailsAtt = (ViewComponentDetailsAttribute) attributes[0];
 204
 205                                         if (!string.IsNullOrEmpty(detailsAtt.Sections))
 206                                         {
 207                                                 sectionsFromAttribute = detailsAtt.Sections.Split(',');
 208                                         }
 209                                 }
 210
 211                                 if (sectionsFromAttribute == null)
 212                                 {
 213                                         sectionsFromAttribute = new string[0];
 214                                 }
 215                         }
 216
 217                         return Array.Find(sectionsFromAttribute,
 218                                 delegate(string item)
 219                                         { return string.Equals(item, name, StringComparison.InvariantCultureIgnoreCase); }) != null;
 220                 }
 221
 222                 #endregion
 223
 224                 #region Usefull properties
 225
 226                 /// <summary>
 227                 /// Gets the Component Context
 228                 /// </summary>
 229                 public IViewComponentContext Context
 230                 {
 231                         get { return context; }
 232                 }
 233
 234                 /// <summary>
 235                 /// Gets the <see cref="IRailsEngineContext"/>
 236                 /// associated with the current request
 237                 /// </summary>
 238                 protected IRailsEngineContext RailsContext
 239                 {
 240                         get { return railsContext; }
 241                 }
 242
 243                 /// <summary>
 244                 /// Gets the component parameters
 245                 /// </summary>
 246                 protected IDictionary ComponentParams
 247                 {
 248                         get { return context.ComponentParameters; }
 249                 }
 250
 251                 /// <summary>
 252                 /// Gets the Session dictionary.
 253                 /// </summary>
 254                 protected IDictionary Session
 255                 {
 256                         get { return railsContext.Session; }
 257                 }
 258
 259                 /// <summary>
 260                 /// Gets a dictionary of volative items.
 261                 /// Ideal for showing success and failures messages.
 262                 /// </summary>
 263                 protected Flash Flash
 264                 {
 265                         get { return railsContext.Flash; }
 266                 }
 267
 268                 /// <summary>
 269                 /// Gets the web context of ASP.NET API.
 270                 /// </summary>
 271                 protected HttpContext HttpContext
 272                 {
 273                         get { return railsContext.UnderlyingContext; }
 274                 }
 275
 276                 /// <summary>
 277                 /// Gets the request object.
 278                 /// </summary>
 279                 protected IRequest Request
 280                 {
 281                         get { return railsContext.Request; }
 282                 }
 283
 284                 /// <summary>
 285                 /// Gets the response object.
 286                 /// </summary>
 287                 protected IResponse Response
 288                 {
 289                         get { return railsContext.Response; }
 290                 }
 291
 292                 /// <summary>
 293                 /// Provides a way to make data available
 294                 /// to the view that the component uses
 295                 /// </summary>
 296                 protected IDictionary PropertyBag
 297                 {
 298                         get { return context.ContextVars; }
 299                 }
 300
 301                 /// <summary>
 302                 /// Shortcut to Request.Params
 303                 /// </summary>
 304                 protected NameValueCollection Params
 305                 {
 306                         get { return Request.Params; }
 307                 }
 308
 309                 #endregion
 310
 311                 #region Useful operations
 312
 313                 /// <summary>
 314                 /// Specifies the view to be processed after the component has finished its processing.
 315                 /// </summary>
 316                 protected void RenderView(String name)
 317                 {
 318                         context.ViewToRender = Path.Combine(GetBaseViewPath(), name);
 319                 }
 320
 321                 /// <summary>
 322                 /// Specifies the view to be processed after the component has finished its processing.
 323                 /// </summary>
 324                 protected void RenderView(String component, String name)
 325                 {
 326                         context.ViewToRender = Path.Combine(GetBaseViewPath(component), name);
 327                 }
 328
 329                 /// <summary>
 330                 /// Specifies the shared view to be processed after the component has finished its
 331                 /// processing. (A partial view shared
 332                 /// by others views and usually in the root folder
 333                 /// of the view directory).
 334                 /// </summary>
 335                 protected void RenderSharedView(String name)
 336                 {
 337                         context.ViewToRender = name;
 338                 }
 339
 340                 /// <summary>
 341                 /// Cancels the view processing.
 342                 /// </summary>
 343                 protected void CancelView()
 344                 {
 345                         context.ViewToRender = null;
 346                 }
 347
 348                 /// <summary>
 349                 /// Renders the specified content back to the browser
 350                 /// </summary>
 351                 /// <param name="content">The content to render.</param>
 352                 protected void RenderText(String content)
 353                 {
 354                         context.Writer.Write(content);
 355                 }
 356
 357                 /// <summary>
 358                 /// Determines whether the current component declaration on the view
 359                 /// has the specified section.
 360                 /// </summary>
 361                 /// <param name="sectionName">Name of the section.</param>
 362                 /// <returns>
 363                 /// <c>true</c> if the specified section exists; otherwise, <c>false</c>.
 364                 /// </returns>
 365                 protected bool HasSection(String sectionName)
 366                 {
 367                         return context.HasSection(sectionName);
 368                 }
 369
 370                 /// <summary>
 371                 /// Renders the component body.
 372                 /// </summary>
 373                 protected void RenderBody()
 374                 {
 375                         context.RenderBody();
 376                 }
 377
 378                 /// <summary>
 379                 /// Renders the body into the specified <see cref="TextWriter"/>
 380                 /// </summary>
 381                 /// <param name="writer">The writer.</param>
 382                 protected void RenderBody(TextWriter writer)
 383                 {
 384                         context.RenderBody(writer);
 385                 }
 386
 387                 /// <summary>
 388                 /// Renders the the specified section
 389                 /// </summary>
 390                 /// <param name="sectionName">Name of the section.</param>
 391                 protected void RenderSection(String sectionName)
 392                 {
 393                         context.RenderSection(sectionName);
 394                 }
 395
 396                 /// <summary>
 397                 /// Renders the the specified section
 398                 /// </summary>
 399                 /// <param name="sectionName">Name of the section.</param>
 400                 /// <param name="writer">The writer.</param>
 401                 protected void RenderSection(String sectionName, TextWriter writer)
 402                 {
 403                         context.RenderSection(sectionName, writer);
 404                 }
 405
 406                 #endregion
 407
 408                 #region private helper methods
 409
 410                 private String GetBaseViewPath()
 411                 {
 412                         return GetBaseViewPath(context.ComponentName);
 413                 }
 414
 415                 private String GetBaseViewPath(String componentName)
 416                 {
 417                         return String.Format("components/{0}", componentName);
 418                 }
 419
 420                 #endregion
 421         }
 422 }