MonoRail/Castle.MonoRail.Framework/Helpers/IJSGenerator.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.Helpers
  16 {
  17         using System;
  18         using System.Collections;
  19         using System.Text;
  20         using Framework;
  21         using 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                 /// Shows a JS alert
 210                 /// </summary>
 211                 ///
 212                 /// <example>
 213                 /// The following example uses nvelocity syntax:
 214                 ///
 215                 /// <code>
 216                 ///   $page.Alert('You won a Mercedez')
 217                 /// </code>
 218                 /// </example>
 219                 ///
 220                 /// <param name="message">The message to display.</param>
 221                 void Alert(object message);
 222
 223                 /// <summary>
 224                 /// Redirects to an url using the <c>location.href</c>.
 225                 /// This is required as most ajax libs don't care for the redirect status
 226                 /// in the http reply.
 227                 /// </summary>
 228                 ///
 229                 /// <example>
 230                 /// The following redirects to a static page
 231                 ///
 232                 /// <code>
 233                 ///   $page.RedirectTo('about.aspx')
 234                 /// </code>
 235                 ///
 236                 /// <para>
 237                 /// The following redirects using the <see cref="UrlHelper"/>
 238                 /// </para>
 239                 ///
 240                 /// <code>
 241                 ///   $page.RedirectTo("%{controller='Home',action='index'}")
 242                 /// </code>
 243                 /// </example>
 244                 ///
 245                 /// <param name="url">The URL.</param>
 246                 void RedirectTo(object url);
 247
 248                 /// <summary>
 249                 /// Re-apply Behaviour css' rules.
 250                 /// </summary>
 251                 /// <remarks>
 252                 /// Only makes sense if you are using the Behaviour javascript library.
 253                 /// </remarks>
 254                 void ReApply();
 255
 256                 /// <summary>
 257                 /// Generates a call to a scriptaculous' visual effect.
 258                 /// </summary>
 259                 ///
 260                 /// <seealso cref="ScriptaculousHelper"/>
 261                 ///
 262                 /// <example>
 263                 /// The following example uses nvelocity syntax:
 264                 ///
 265                 /// <code>
 266                 ///   $page.VisualEffect('ToggleSlide', 'myelement')
 267                 /// </code>
 268                 ///
 269                 /// <para>
 270                 /// This is especially useful to show which elements
 271                 /// where updated in an ajax call.
 272                 /// </para>
 273                 ///
 274                 /// <code>
 275                 ///       $page.ReplaceHtml('mydiv', "Hey, I've changed")
 276                 ///   $page.VisualEffect('Highlight', 'mydiv')
 277                 /// </code>
 278                 ///
 279                 /// </example>
 280                 ///
 281                 /// <param name="name">The effect name.</param>
 282                 /// <param name="element">The target element.</param>
 283                 /// <param name="options">The optional options.</param>
 284                 void VisualEffect(String name, String element, IDictionary options);
 285
 286                 /// <summary>
 287                 /// Generates a call to a scriptaculous' drop out visual effect.
 288                 /// </summary>
 289                 ///
 290                 /// <seealso cref="ScriptaculousHelper"/>
 291                 ///
 292                 /// <param name="element">The target element.</param>
 293                 /// <param name="options">The optional options.</param>
 294                 void VisualEffectDropOut(String element, IDictionary options);
 295
 296                 /// <summary>
 297                 /// Assigns a javascript variable with the expression.
 298                 /// </summary>
 299                 ///
 300                 /// <example>
 301                 /// The following example uses nvelocity syntax:
 302                 ///
 303                 /// <code>
 304                 ///   $page.Assign('myvariable', '10')
 305                 /// </code>
 306                 ///
 307                 /// <para>
 308                 /// Which outputs:
 309                 /// </para>
 310                 ///
 311                 /// <code>
 312                 ///   myvariable = 10;
 313                 /// </code>
 314                 ///
 315                 /// <para>
 316                 /// With strings you can escape strings:
 317                 /// </para>
 318                 ///
 319                 /// <code>
 320                 ///   $page.Assign('myvariable', '\'Hello world\'')
 321                 /// </code>
 322                 ///
 323                 /// <para>
 324                 /// Which outputs:
 325                 /// </para>
 326                 ///
 327                 /// <code>
 328                 ///   myvariable = 'Hello world';
 329                 /// </code>
 330                 ///
 331                 /// </example>
 332                 ///
 333                 /// <param name="variable">The target variable</param>
 334                 /// <param name="expression">The right side expression</param>
 335                 void Assign(String variable, String expression);
 336
 337                 /// <summary>
 338                 /// Declares the specified variable as null.
 339                 /// </summary>
 340                 ///
 341                 /// <seealso cref="Assign"/>
 342                 ///
 343                 /// <param name="variable">The variable name.</param>
 344                 void Declare(String variable);
 345
 346                 /// <summary>
 347                 /// Calls the specified function with the optional arguments.
 348                 /// </summary>
 349                 ///
 350                 /// <example>
 351                 /// The following example uses nvelocity syntax:
 352                 ///
 353                 /// <code>
 354                 ///   $page.call('myJsFunctionAlreadyDeclared', '10', "'message'", $somethingfrompropertybag, $anothermessage.to_squote)
 355                 /// </code>
 356                 ///
 357                 /// <para>
 358                 /// Which outputs:
 359                 /// </para>
 360                 ///
 361                 /// <code>
 362                 ///   myJsFunctionAlreadyDeclared(10, 'message', 1001, 'who let the dogs out?')
 363                 /// </code>
 364                 ///
 365                 /// </example>
 366                 ///
 367                 /// <param name="function">The function name.</param>
 368                 /// <param name="args">The arguments.</param>
 369                 void Call(object function, params object[] args);
 370
 371                 /// <summary>
 372                 /// Outputs the content using the renderOptions approach.
 373                 ///
 374                 /// <para>
 375                 /// If the renderOptions is a string, the content is escaped and quoted.
 376                 /// </para>
 377                 ///
 378                 /// <para>
 379                 /// If the renderOptions is a dictionary, we extract the key <c>partial</c>
 380                 /// and evaluate the template it points to. The content is escaped and quoted.
 381                 /// </para>
 382                 ///
 383                 /// </summary>
 384                 ///
 385                 /// <example>
 386                 /// The following example uses nvelocity syntax:
 387                 ///
 388                 /// <code>
 389                 ///   $page.Call('myJsFunction', $page.render("%{partial='shared/newmessage.vm'}") )
 390                 /// </code>
 391                 ///
 392                 /// <para>
 393                 /// Which outputs:
 394                 /// </para>
 395                 ///
 396                 /// <code>
 397                 ///   myJsFunction('the content from the newmessage partial view template')
 398                 /// </code>
 399                 ///
 400                 /// </example>
 401                 ///
 402                 /// <param name="renderOptions">The render options.</param>
 403                 /// <returns></returns>
 404                 object Render(object renderOptions);
 405
 406                 /// <summary>
 407                 /// Writes the content specified to the generator instance
 408                 /// </summary>
 409                 ///
 410                 /// <remarks>
 411                 /// This is for advanced scenarios and for the infrastructure. Usually not useful.
 412                 /// </remarks>
 413                 ///
 414                 /// <param name="content">The content.</param>
 415                 void Write(String content);
 416
 417                 /// <summary>
 418                 /// Writes the content specified to the generator instance
 419                 /// </summary>
 420                 ///
 421                 /// <remarks>
 422                 /// This is for advanced scenarios and for the infrastructure. Usually not useful.
 423                 /// </remarks>
 424                 /// <param name="content">The content.</param>
 425                 void AppendLine(String content);
 426
 427                 /// <summary>
 428                 /// Dump the operations recorded so far as javascript code.
 429                 /// </summary>
 430                 ///
 431                 /// <returns></returns>
 432                 string ToString();
 433
 434                 /// <summary>
 435                 /// Gets the js lines.
 436                 /// </summary>
 437                 /// <value>The js lines.</value>
 438                 StringBuilder Lines { get; }
 439
 440                 /// <summary>
 441                 /// Creates a generator for a collection.
 442                 /// </summary>
 443                 /// <param name="root">The root expression.</param>
 444                 /// <returns></returns>
 445                 IJSCollectionGenerator CreateCollectionGenerator(string root);
 446
 447                 /// <summary>
 448                 /// Creates a generator for an element.
 449                 /// </summary>
 450                 /// <param name="root">The root expression.</param>
 451                 /// <returns></returns>
 452                 IJSElementGenerator CreateElementGenerator(string root);
 453         }
 454 }