MonoRail/Castle.MonoRail.Framework/JSGeneration/IJSGenerator.cs

   1 // Copyright 2004-2008 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.JSGeneration
  16 {
  17         using System;
  18         using System.Collections;
  19         using Castle.MonoRail.Framework;
  20         using Castle.MonoRail.Framework.Helpers;
  21         using Castle.MonoRail.Framework.Services;
  22
  23         /// <summary>
  24         /// Depicts the contract for javascript generators.
  25         /// </summary>
  26         ///
  27         /// <remarks>
  28         /// <para>
  29         /// Urls can be specified as string or a dictionary. If the latter, the <see cref="UrlHelper"/>
  30         /// is used. See <see cref="DefaultUrlBuilder.BuildUrl(UrlInfo,IDictionary)"/>
  31         /// </para>
  32         ///
  33         /// <para>
  34         /// The <c>renderOptions</c> is also a common parameter. If you pass a string,
  35         /// the string will be rendered. If it is a dictionary, it instructs the infrastructure to
  36         /// render a partial content. The dictionary must contain an entry named <c>partial</c>
  37         /// with the absolute path to the view to render.
  38         /// </para>
  39         ///
  40         /// </remarks>
  41         ///
  42         /// <example>
  43         /// The following is an example of using it with a nvelocity
  44         /// syntax and renders static content:
  45         ///
  46         /// <code>
  47         ///   $page.InsertHtml('Bottom', 'messagestable', "Message sent")
  48         /// </code>
  49         ///
  50         /// <para>
  51         /// The following uses a partial view:
  52         /// </para>
  53         ///
  54         /// <code>
  55         ///   $page.InsertHtml('Bottom', 'messagestable', "%{partial='shared/newmessage.vm'}")
  56         /// </code>
  57         ///
  58         /// <para>
  59         /// The following redirects to a static page
  60         /// </para>
  61         ///
  62         /// <code>
  63         ///   $page.RedirectTo('about.aspx')
  64         /// </code>
  65         ///
  66         /// <para>
  67         /// The following redirects using the <see cref="UrlHelper"/>
  68         /// </para>
  69         ///
  70         /// <code>
  71         ///   $page.RedirectTo("%{controller='Home',action='index'}")
  72         /// </code>
  73         ///
  74         /// </example>
  75         public interface IJSGenerator
  76         {
  77                 /// <summary>
  78                 /// Inserts a content snippet relative to the element specified by the <paramref name="id"/>
  79                 ///
  80                 /// <para>
  81                 /// The supported positions are
  82                 /// Top, After, Before, Bottom
  83                 /// </para>
  84                 /// </summary>
  85                 ///
  86                 /// <example>
  87                 /// The following example uses nvelocity syntax:
  88                 ///
  89                 /// <code>
  90                 ///   $page.InsertHtml('Bottom', 'messagestable', "%{partial='shared/newmessage.vm'}")
  91                 /// </code>
  92                 /// </example>
  93                 ///
  94                 /// <param name="position">The position to insert the content relative to the element id</param>
  95                 /// <param name="id">The target element id</param>
  96                 /// <param name="renderOptions">Defines what to render</param>
  97                 void InsertHtml(string position, string id, object renderOptions);
  98
  99                 /// <summary>
 100                 /// Replaces the content of the specified target element.
 101                 /// </summary>
 102                 ///
 103                 /// <example>
 104                 /// The following example uses nvelocity syntax:
 105                 ///
 106                 /// <code>
 107                 ///   $page.ReplaceHtml('messagediv', "%{partial='shared/newmessage.vm'}")
 108                 /// </code>
 109                 /// </example>
 110                 ///
 111                 /// <param name="id">The target element id</param>
 112                 /// <param name="renderOptions">Defines what to render</param>
 113                 void ReplaceHtml(String id, object renderOptions);
 114
 115                 /// <summary>
 116                 /// Replaces the entire target element -- and not only its innerHTML --
 117                 ///  by the content evaluated.
 118                 /// </summary>
 119                 ///
 120                 /// <example>
 121                 /// The following example uses nvelocity syntax:
 122                 ///
 123                 /// <code>
 124                 ///   $page.Replace('messagediv', "%{partial='shared/newmessage.vm'}")
 125                 /// </code>
 126                 /// </example>
 127                 ///
 128                 /// <param name="id">The target element id</param>
 129                 /// <param name="renderOptions">Defines what to render</param>
 130                 void Replace(String id, object renderOptions);
 131
 132                 /// <summary>
 133                 /// Shows the specified elements.
 134                 /// </summary>
 135                 ///
 136                 /// <remarks>
 137                 /// The elements must exist.
 138                 /// </remarks>
 139                 ///
 140                 /// <example>
 141                 /// The following example uses nvelocity syntax:
 142                 ///
 143                 /// <code>
 144                 ///   $page.Show('div1', 'div2')
 145                 /// </code>
 146                 /// </example>
 147                 ///
 148                 /// <param name="ids">The elements ids.</param>
 149                 void Show(params string[] ids);
 150
 151                 /// <summary>
 152                 /// Hides the specified elements.
 153                 /// </summary>
 154                 ///
 155                 /// <remarks>
 156                 /// The elements must exist.
 157                 /// </remarks>
 158                 ///
 159                 /// <example>
 160                 /// The following example uses nvelocity syntax:
 161                 ///
 162                 /// <code>
 163                 ///   $page.Hide('div1', 'div2')
 164                 /// </code>
 165                 /// </example>
 166                 ///
 167                 /// <param name="ids">The elements ids.</param>
 168                 void Hide(params string[] ids);
 169
 170                 /// <summary>
 171                 /// Toggles the display status of the specified elements.
 172                 /// </summary>
 173                 ///
 174                 /// <remarks>
 175                 /// The elements must exist.
 176                 /// </remarks>
 177                 ///
 178                 /// <example>
 179                 /// The following example uses nvelocity syntax:
 180                 ///
 181                 /// <code>
 182                 ///   $page.Toggle('div1', 'div2')
 183                 /// </code>
 184                 /// </example>
 185                 ///
 186                 /// <param name="ids">The elements ids.</param>
 187                 void Toggle(params string[] ids);
 188
 189                 /// <summary>
 190                 /// Remove the specified elements from the DOM.
 191                 /// </summary>
 192                 ///
 193                 /// <remarks>
 194                 /// The elements must exist.
 195                 /// </remarks>
 196                 ///
 197                 /// <example>
 198                 /// The following example uses nvelocity syntax:
 199                 ///
 200                 /// <code>
 201                 ///   $page.Remove('div1', 'div2')
 202                 /// </code>
 203                 /// </example>
 204                 ///
 205                 /// <param name="ids">The elements ids.</param>
 206                 void Remove(params string[] ids);
 207
 208                 /// <summary>
 209                 /// Outputs the content using the renderOptions approach.
 210                 ///
 211                 /// <para>
 212                 /// If the renderOptions is a string, the content is escaped and quoted.
 213                 /// </para>
 214                 ///
 215                 /// <para>
 216                 /// If the renderOptions is a dictionary, we extract the key <c>partial</c>
 217                 /// and evaluate the template it points to. The content is escaped and quoted.
 218                 /// </para>
 219                 ///
 220                 /// </summary>
 221                 ///
 222                 /// <example>
 223                 /// The following example uses nvelocity syntax:
 224                 ///
 225                 /// <code>
 226                 ///   $page.Call('myJsFunction', $page.render("%{partial='shared/newmessage.vm'}") )
 227                 /// </code>
 228                 ///
 229                 /// <para>
 230                 /// Which outputs:
 231                 /// </para>
 232                 ///
 233                 /// <code>
 234                 ///   myJsFunction('the content from the newmessage partial view template')
 235                 /// </code>
 236                 ///
 237                 /// </example>
 238                 ///
 239                 /// <param name="renderOptions">The render options.</param>
 240                 /// <returns></returns>
 241                 object Render(object renderOptions);
 242
 243                 /// <summary>
 244                 /// Creates a generator for an element.
 245                 /// </summary>
 246                 /// <param name="root">The root expression.</param>
 247                 /// <returns></returns>
 248                 IJSElementGenerator CreateElementGenerator(string root);
 249
 250 //              /// <summary>
 251 //              /// Creates a generator for a collection.
 252 //              /// </summary>
 253 //              /// <param name="root">The root expression.</param>
 254 //              /// <returns></returns>
 255 //              IJSCollectionGenerator CreateCollectionGenerator(string root);
 256
 257         }
 258 }