Tag Archives: WebTextEditor

New Properties, Events, and Client-side API added in WebTextEditor

As published previously, we have released WebUI Studio 2009 R1 SP1 which includes many enhancements, especially to WebTextEditor and WebScheduler 2. Specifically in WebTextEditor, some new properties, client-side events, and client-side API are included.

New Properties

  • ToolBarSettings >> SerializationMode, determines the serialization mode used for toolbars definition. When set to Client, the page output will be much reduced. Read the complete explanation here
  • ToolBarSettings >> SynchronizeCommandLatency, determines the latency used to synchronize the toolbar commands with the format of selected content. When users navigate through contents that has different format, the toolbar commands will be synchronized to the selected content. This property determines the latency used before the synchronization action is invoked.
  • PreventScriptInjection, determines whether WebTextEditor should detect whether the content contains script injection. If this property is enabled, all script tags and its content will be removed when the content is saved.
  • ShowCallOutOnMediaInsert, determines whether callout should be automatically displayed when a media is inserted as editor content.
  • ShowMediaActionOnMediaSelect, determines whether media action should be displayed when a media is selected.

New client-side events

  • OnKeyDown, will be invoked when there is a key down input in editor.
    function WebTextEditor1_OnKeyDown(controlId, keyCode)
         var rte = ISGetObject(controlId);
         //implement your codes here
  • OnMediaSelected, will be invoked when a media is selected. Users can input media to editor content from Media Gallery. When the media is selected, this event will be invoked when specified.
    function WebTextEditor1_OnMediaSelected(contolId, element)
         var rte = ISGetObject(controlId);
         //implement your codes here
  • OnBeforeResize and OnAfterResize, will be invoked before and after editor is resized using the footer resize element.
    function WebTextEditor1_OnBeforeResize(controlId)
         var rte = ISGetObject(controlId);
         //implement your codes here
    function WebTextEditor1_OnAfterResize(controlId)
         var rte = ISGetObject(controlId);
         //implement your codes here
  • Integrated file-uploader client side events, which are OnBeforeUpload, OnUploaderValidate, OnUploading, OnAfterUpload, OnCancelUpload, OnUploaderInitialize, OnUploaderError, OnUploaderFileAdded, and OnUploaderFileRemoved. When WebFileUploader is integrated to WebTextEditor and users perform specific action related to it, the above events will be invoked when specified.

New client-side APIs

  • SetValueToCurrentPosition, used to set value on the last active cursor position. When users navigate through the content and lost focus from editor, a specific value can be added to editor. When this API is used, the value will be added to the last active cursor position before users lost focus from editor.
    var rte = ISGetObject(“WebTextEditor1”);
    rte.SetValueToCurrentPosition(“new value”);
  • SetFocus, used to set focus to WebTextEditor. When watermark is enabled, this function will remove the watermark and set focus to editor content.
    var rte = ISGetObject(“WebTextEditor1”);
  • ToggleToolBar, used to toggle or un-toggle a specific toolbar.
    var rte = ISGetObject(“WebTextEditor1”);
    var toolbar = rte.ClientToolBar[1];
    rte.ToggleToolBar(toolbar, false);
  • ResetEditorState, used to reset the editor state to default state. This API will set the content to empty, close the task pane, reset the state of commands in all toolbars, reset the undo and redo collections, and reset the integrated uploader status.
    var rte = ISGetObject(“WebTextEditor1”);
  • HideCallOut, used to hide the callout. You can specify whether the hide action will be performed using animation.
    var rte = ISGetObject(“WebTextEditor1”);
    rte.HideCallOut(false); //hide callout without animation
  • RegisterIFrameBehavior and UnregisterIFrameBehavior, used to register and unregister the behavior attached to IFrame element of WebTextEditor. When WebTextEditor element is removed and placed in various elements in the page, the behavior attached to the IFrame element will be lost. These new APIs can be used to re-register or unregister the behavior when needed.

If you have installed WebUI Studio 2009 R1 SP1, you can read the complete version history of the enhancements and fixes in Intersoft WebUI Studio 2009 R1 SP1 Release Notes.pdf.

Bind Value to WebTextEditor When Used As Template

WebTextEditor can be used as editing tool in many scenarios. If you have details view or other data list control, WebTextEditor can be used as the item or edit template and the related data can be displayed in WebTextEditor.

DetailsView control is used to demonstrate this capability. After it is bound properly to Employees table, users can navigate through employee data using the navigation links provided. Data can be bound to WebTextEditor when it is used as item or edit template. Simply set the Content property to the related data.

<asp:TemplateField HeaderText="Notes" SortExpression="Notes">
      <ISWebTextEditor:WebTextEditor ID="WebTextEditor1" runat="server" Height="200px"
      	   Width="500px" Content='<%# Bind("Notes") %>'>
         <ViewSettings EnableHTMLView="false" EnableSplitView="false" />
         <ToolBarSettings ToolBarMode="None" />
         <RootTextEditor ReadOnly="true">
      <ISWebTextEditor:WebTextEditor ID="WebTextEditor1" runat="server" Height="200px"
	    Width="500px" Content='<%# Bind("Notes") %>'>
         <ViewSettings EnableHTMLView="false" EnableSplitView="false" />
	 <ToolBarSettings ToolBarMode="Minimal" />
 	    <MediaGallery Enabled="false" />

As item template, the related Notes data will be displayed in WebTextEditor. As item template, users are unable to edit the content. Read-only status can be set in WebTextEditor when it is used as item template.

WebTextEditor used as item template

When users click Edit, the related Notes data will be displayed in WebTextEditor. Users can easily modify the content and save the update.

WebTextEditor used as edit template
WebTextEditor used as edit template

When used as either template, WebTextEditor configuration can be customized based on your requirement. Please browse to this sample in Intersoft Live Demo to try it yourself.

Integrate WebSpellChecker to ASP.NET Controls

In addition to its easy integration with our own WebTextEditor, WebSpellChecker can also be used to target standard ASP.NET controls such as simple textbox, multiline textarea as well as IFRAME. Similar to the WebTextEditor integration, using WebSpellChecker with ASP.NET controls is very easy and requires no coding at all.

To use WebSpellChecker in standard ASP.NET controls, simply pay attention on these two properties, TargetControlId and TargetControlIdValue. The properties are explained in the following.

  • TargetControlId
    This property is required to determine the target control for spell check.For instance, TargetControlId should be filled with “TextBox1” value if you would like to spell check on TextBox1 control.
  • TargetControlIdValue
    This property determines the client-side property of the element from which WebSpellChecker should obtain the value for spell check. It’s important to note that the value or content property should be accessible from client-side.For instance, if WebSpellChecker is targetting TextBox server side control, then the TargetControlIdValue property should be set to “value” instead of “Text”.

When WebSpellChecker is not integrated to WebTextEditor or editable IFrame, it will use the built-in DialogBox interface instead of “red wave underline highlight” mode. For further information about WebSpellChecker interface mode, you can find read the detail explanation in here.

To integrate WebSpellChecker to a ASP.NET TextBox, please follow the step-by-step guide below.

  1. Drag and drop ASP.NET TextBox control and TextBox control with ID’s TextBox1 will appear.
  2. Drag and drop HTML Button control and Button control with the ID’s Button1 will appear. This button is used to start the spell checking from TextBox’s value.
  3. Drag and drop Intersoft WebSpellChecker control and WebSpellChecker control with ID’s WebSpellChecker1 will appear.
  4. Set WebSpellChecker’s TargetControlId to TextBox1 and TargetControlIdValue to value.
  5. Attach onclick client side event to Button1 and set it to CheckSpell function.
    <input id=”Button1″ type=”button” value=”button” onclick=”CheckSpell()” /><script language=”javascript” type=”text/javascript”>
    function CheckSpell()
    var sp = ISGetObject(“WebSpellChecker1”);
  6. Integration is finished.

The above sample can be found here. Other samples about WebSpellChecker and the explanation can be found in Intersoft’s live sample.

If you have any questions or feedback, please don’t hesitate to post your questions in Intersoft Forums.

Best Regards,
Budianto Muliawan

Built-in Mail Merge Support in WebTextEditor

Many people are familiar with Mail Merge feature in Microsoft Word. It is used when you want to send a set of documents that has the same kind of information, but personalized for each recipient. For example: you want to send a gathering invitation to all members of IT division. You can send the invitation to all members using the same template but personalized for each recipient. This feature is also supported in WebTextEditor.

You can enable this feature instantly by setting the EnableMailMerge property available in MailMergeSettings. The collection of recipients can be specified as data bound collection or custom collection. When data bound collection is used, the datasource control id can be specified as DataSourceID property.

<ISWebTextEditor:WebTextEditor ID="WebTextEditor1" runat="server" Height="80%" 
Width="100%" DataMember="DefaultView" DataSourceID="AccessDataSource1">

When custom collection is used, the collection can be added to Recipients collection.

private void BindCustomCollection() 
   List<ISEmployee> employees = new List<ISEmployee>(); 
   ISEmployee emp = new ISEmployee(); 
   emp.EmployeeID = 1; 
   emp.FirstName = "Nancy"; 
   emp.LastName = "Davolio"; 
   emp.Address = "Bridge Street"; 
   emp.City = "London"; 
   emp.Country = "UK"; 

   emp = new ISEmployee(); 
   emp.EmployeeID = 2; 
   emp.FirstName = "Andrew"; 
   emp.LastName = "Fuller"; 
   emp.Address = "Wood Street"; 
   emp.City = "Washington"; 
   emp.Country = "USA"; 

   WebTextEditor1.MailMergeSettings.Recipients = employees; 

When the collection of recipients are ready, you need to specify the labels. Labels are used to indicate parts of the content that will be replaced with the related data in the data context. You can specify as many labels as needed in the template. Each label contain the following properties:

  • Label (mandatory): specifies the text used as label.
  • DataMember (mandatory): specifies the field or property in data context that will be used to replace the label text.
  • FormatString (optional): specifies the format string of the label. This property can be specified if you want to have a specific format on dates or numbers.

The collection of labels can be added in MailMergeSettings >> Labels property.

Insert Labels

The labels will be added to Insert Merge Label dropdown in main toolbar. Users can easily select an item from this command in main toolbar and it will be added to editor. Users will not be able to modify the labels manually in the editor window.

Collections of labels added to toolbar

Users can preview the mail merge result in Preview tab. The labels will be automatically replaced with the related data in the data context and users can navigate through the data using the previous and next commands in toolbar.

Preview Mail Merge content

Users can also send the mail using Send Mail Merge command. Some related properties that need to be configured are:

  • EmailField: specifies the field or property in data context that contains email data.
  • From: specifies the email of sender.
  • IsHTML: specifies whether or not the email should be sent as HTML format.
  • MailPriority: specifies the priority status of the email.
  • SMTP: specifies the SMTP server.
  • SubjectExpression: specifies the subject of the email. Labels can be included as the value of this property and they will automatically be replaced with related data when the email is sent.

Mail Merge configuration

WebTextEditor provides various server-side events that will be invoked when the emails are about to be sent. If you have specific scenarios that need custom actions, these events can be used to implement those actions.

  • OnBeforeSendMail event is invoked the emails are sent.
  • OnMailMerge event is invoked when each email is merged with the related data from data context.
  • OnMailMergeCompleted event is invoked when all emails have been merged with the related data from the data context.
  • OnSendMail event is invoked when each email is about to be sent.
  • OnSendMailCompleted event is invoked after all emails are sent.

If you set AutomaticSendMail property to False, you can specify your own configuration and send mail process in OnSendMail event.

protected void WebTextEditor1_SendMail(object sender, ISNet.WebUI.WebTextEditor.WebTextEditorSendMailArgs e) 
   //specify your own configuration 
   e.Cancel = true; // needed to cancel built-in send mail process 

After all emails are sent, you might need to display specific custom status in WebTextEditor or perform other custom actions in client-side. In this case, you can use OnSendMailCompleted client-side event. In this event, the failed emails data will also be passed as parameters. So, in cases where emails are failed to be sent to recipients, you can perform custom actions to handle the scenario.

<script type="text/javascript"> 
   function OnSendMailCompleted(controlId, failed, failedEmails) 
      var editor = ISGetObject(controlId); 

      if (failed > 0) 
	 // you can implement custom action to handle this scenario 
 	 editor.SetStatus("All emails are successfully sent at " + new Date() + "."); 

If you have feedback regarding this feature, feel free to drop a comment or create a new discussion in our new Forum.

Reduce Page Output in WebTextEditor

In WebTextEditor, there are three kinds of views that have their own set of toolbars, such as Design view, HTML view, and Preview. Each toolbars are created in server-side and then serialized to client for UI rendering. This will result in a large page output, especially if you have a large number of tool commands in each toolbar.

If you view source in the page, you will find the following toolbar definition in the xml output.

   <WebTextEditorToolBar Text="Formatting" Category="Formatting">
	 <WebTextEditorToolCommand Text="Bold" DisplayMode="Image" 
	    Image="/WebTextEditor/ISRes.axd?E/tb_bold.gif" ToggleGroupName="Bold" />
	 <WebTextEditorToolCommand Text="Italic" CommandType="Italic" 
	    DisplayMode="Image" Image="/WebTextEditor/ISRes.axd?E/tb_italic.gif" 
	    ToggleGroupName="Italic" />
	 <WebTextEditorToolCommand Text="Underline" CommandType="Underline" 
  	    DisplayMode="Image" Image="/WebTextEditor/ISRes.axd?E/tb_underline.gif" 
	    ToggleGroupName="Underline" />

The page output will automatically increase if you have more toolbars and more tool commands. We have made many enhancements in the latest WebTextEditor included in Intersoft WebUI Studio 2009 R1 SP1 installer. One of the enhancements is to significantly reduce the page output size due to the huge toolbar definition.

In ToolBarSettings category, we introduced a new property, SerializationMode. To prevent breaking changes with the previous implementation, the default value is set to Server. In this case, toolbars and its tool commands will be specified in server-side and serialized to client-side for UI rendering.

SerializationMode property

The other value of SerializationMode property which is added in SP1 is Client. When Client is selected, the toolbars and its commands will be created in client-side, thus reducing the large toolbar definition that previously affects the page output. You can view the page source and see that the toolbar definition is no longer included in the xml output. On the other hands, all toolbar functionalities and behaviors remain the same, thus maintaining the stability achieved in both modes.

In addition to this enhancement, OnInitializeToolBar client-side event is added to WebTextEditor. In this event, you can customize the tool command sequence, add new tool command, and remove existing tool command. The object parameter passed to this event includes all ToolBar collections in WebTextEditor, such as ToolBar, HTMLToolBar, PreviewToolBar, and FloatingToolBar. Note that these are toolbars collection, not the toolbar instance itself.

<script type="text/javascript"> 
   function WebTextEditor1_OnInitializeToolBar(controlId, args) 
      var rte = ISGetObject(controlId); 
      //args parameter includes all toolbar collections 

Argument passed in OnInitializeToolBar event

The object parameter also has some built-in functions which can be easily used to customize the toolbars collection. Each collection can have more than one toolbar and you can add custom toolbars to the existing collection. Simply use AddToolBar function to add the new toolbar to the toolbar collection.

In the following code, two new toolbar are added to ToolBar collection. One toolbar contains Hyperlink and RemoveLink commands, the other toolbar contains Undo and Redo commands.

<script type="text/javascript"> 
   function WebTextEditor1_OnInitializeToolBar(controlId, args) 
      var rte = ISGetObject(controlId);

      // add new toolbars 
      var toolbars = [ 
	 "Name": rte.ID + "_tbLink", "Text": "Link", 
	 "Category": "Custom", "Commands": new Array("Hyperlink", "RemoveLink")  
	 "Name": rte.ID + "_tbOther", "Text": "Other", 
	 "Category": "Custom", "Commands": new Array("Undo", "Redo")

      args.AddToolBar(args.ToolBar, toolbars); 

Add New ToolBars

Since each collection can have more than one toolbar, you can use GetToolBar function to get a specific toolbar object using its category and name. In the following code, category is used to get Custom category toolbar. If there are multiple toolbars in Custom category (such as mentioned above), the first toolbar will be returned. In this scenario, tb variable will contains tbLink toolbar instance.

var tb = args.GetToolBar("Custom");

If you want to get tbOther toolbar instance, you can use category and name to get a specific toolbar as described in the following code. The tb2 variable will now contains tbOther toolbar instance.

var tb2 = args.GetToolBar("Custom", rte.Id + "_tbOther");

A new command can be added using AddCommand function. You need to specify the toolbar where the new command will be added, the new command, and the position index. If the position index is not specified, the command will be added to the last position in the toolbar. The following code will add a new command, Emoticon, to tbOther toolbar.

var command1 = { "Name": "cmdEmoticon", "Text": "Emoticon", 
	"DisplayMode": "Image", "Image": "./Images/smiley1.gif", 
	"Type": "ToggleButton", "ToggleGroupName": "TaskPane", 
	"Items" : new ISArray() };

args.AddCommand(tb2, command1);

Add New Command

RemoveCommand function can be used to remove a command. Simply specify the toolbar and the command that will be removed. The following command will remove RemoveLink command from tbLink toolbar.

var command2 = tb.ToolCommands.GetNamedItem("cmdRemoveLink"); 
args.RemoveCommand(tb, command2);

Remove Command

Another useful function is MoveCommand function, which can be used to move a command to another position within one toolbar. You need to specify the toolbar, the command name, and the destination index. The following code will move Emoticon command from the last position to the first position in tbOther toolbar.

args.MoveCommand(tb2, "cmdEmoticon", 0);

Move Command

There is other point to note when this enhancement is enabled. In ToolBarSettings, you can specify the ToolBarMode as Custom and specify your own toolbar definition in XML file. In this case, you are required to use Server serialization mode. Another alternative is to specify the toolbars and commands manually in OnInitializeToolBar client-side event.

Click here to download the sample.

We have other enhancements in WebTextEditor that includes new client-side event, new client-side API, new properties and other points as described in Intersoft WebUI Studio 2009 R1 SP1 Release Notes. Stay tune as we will write more about them in the coming blogs.