SPAW Editor .NET Edition v.2 Integrator's Guide

Table of Contents

About

SPAW Editor .NET Edition is a web based WYSIWYG HTML editor control used to replace standard textarea fields in Content Management Systems (CMS) and other web based solutions requiring advanced, non-technical user friendly HTML snippet editing.

This document is a guide for CMS developers describing aspects of SPAW Editor integration in their respective systems. This guide doesn't contain any information on development of SPAW Editor plug-ins, visual skins, localization or client usage. For a complete guide, please, visit documentation section of our web site.

System Requirements

SPAW Editor .NET Edition v.2 runs on ASP .NET version 2.0 setup (including medium trust environments like shared hosting accounts, etc.).

Installation

Installation is as simple as extracting files from the archive and uploading them to your web server/copying to a subdirectory in your website project. If this is a new SPAW v.2 installation then you also have to copy (or rename) configuration file spaw2.default.config to spaw2.config in config subdirectory. This step is necessary so you don't accidentally overwrite your configuration file when upgrading to a newer version.

In case you are installing SPAW Editor to a subdirectory other than "spaw2" in your application root, copy contents of the Bin directory to Bin directory of your application and add following setting to your Web.config file:

<appSettings>
  <add key="spaw_dir" value="~/path/to/spaw2/" />
</appSettings>

where value is a path to a directory where you copied contents of the spaw2 directory

You should be able to see a working instance of SPAW Editor v.2 by pointing your browser to demo/demo.aspx script under your SPAW directory.

Configuration

SPAW Editor is initially configured by setting values in config/spaw2.config file. This is an XML file where each "simple" setting is an element with name and value attribute. You set a value attribute in this file to change a configuration option described by name. Most of the configuration options can be changed through code at design or run time. Configuration API is described in greater detail in plugin developers guide.

Plugins can have their own configuration settings which can be included in the global configuration file (config/spaw2.config) or in a local config file in config subdirectory of plugins folder. It is safe to move plugin configuration settings from local config files to the global config file for better maintainability (unless otherwise specified by plugins author).

Core Configuration Settings

This section describes static (default for all instances) configuration settings for features that come with core SPAW Editor .NET Edition v.2 distribution. You can change values of these configuration parameters by modifying them in config/spaw2.config file. You can also modify these settings on per instance basis in your code (see chapter on usage). Plugin related settings are described in their respective documentation.

Editor Defaults

These editor settings are used when certain properties aren't specified for SPAW instance

Name

Description

default_output_charset Specifies character set to use for output. If empty string is specified charset specified in language file will be used.

default_theme

Specifies default GUI theme (skin)

default_toolbarset

Specifies default toolbar set. Note: toolbar concept has changed dramatically from v.1.x.

default_stylesheet

Specifies path to the default CSS stylesheet file to be used for editing area

default_width

Specifies default editor width

default_height

Specifies default editor height

SPAW Engine Settings

These settings determine inner behavior of various SPAW engine components

Name

Description

rendering_mode Specifies which HTML rendering method should be used. Applicable values are "xhtml" and "builtin". "xhtml" mode uses SPAW's own rendering engine to produce well-formed XHTML across browsers. "builtin" uses browsers internal engine which works faster but produces different results across browsers.

beautify_xhtml_output

If set to true specifies that XHTML rendering subsystem should "beautify" output html structure by using indentation, etc.

base_href Specifies protocol, host and port part (like http://mydomain.com) to be added to urls returned from file manager. Use in conjunction with 'strip_absolute_urls' to force absolute urls.
strip_absolute_urls If set to true, SPAW will strip domain and path parts from all "local" (pointing to the current web site and/or directory) urls in hyperlinks and images. Note: Microsoft Internet Explorer converts all urls to absolute so this is a workaround to get rid of the absolute part apended to the relative urls users enter.
resizing_directions Specifies allowed direction in which users resize editor window. Allowed values: none, horizontal, vertical, both
convert_html_entities Specifies that special characters should be converted to the respective html entities like &copy; etc.

Dropdown Data

These items hold data used to populate dropdown lists in the toolbars and dialogs. <setting> elements here contain child XML <setting> nodes. Value of name attribute goes to dropdowns option value, value of value attribute is displayed as dropdown text.

Name

Description

dropdown_data_core_style

List of CSS classes for the Styles dropdown. Empty string value removes class attribute from the HTML element

table_styles List of CCS classes used in table properties dialog
dropdown_data_core_fontname List of font names for Fonts dropdown
dropdown_data_core_fontsize List of font sizes for Fontsize dropdown
dropdown_data_core_formatBlock List of paragraph styles for Paragraph dropdown
a_targets List of hyperlink targets for Hyperlink dialog

Toolbar Sets

Toolbar sets are just lists of toolbars. You can specify toolbars to be shown in your instance one by one or you can specify a toolbar set that contains all the toolbars you need.  The following table contains a list of predefined toolbar sets. You can create your own toolbar sets. Standard toolbar names are: edit, format, font, insert, table, tools and plugins. Theme developers specify places for specific toolbars but you can substitute "standard" toolbar with your own. To substitute a standard toolbar in toolbarset you set name attribute of toolbar element to standard toolbar name (like format) and add substitute attribute which is set to your substitute toolbar name (like format_mini). See "mini" toolbar set definition in default config file for a sample. Toolbar set config item names start with "toolbarset_" followed by toolbar name. For detailed explanation of toolbar customization read toolbar customization section below.

Name

Description

toolbarset_standard

Includes all standard toolbars except "font"

toolbarset_all Includes all standard toolbars
toolbarset_mini Includes edit and tools toolbars and smaller version of format toolbar

Colorpicker Predefined Colors

You can customize predefined colors in colorpicker dialog. To do that you set config item called "colorpicker_predefined_colors". This setting should contain 16 child <color> nodes with value attribute representing color in CSS compatible format.

SPAW File Manager Plugin Settings

File Manager plugin allows managing files on the server and selecting them for embedding into the text being edited (i.e. images, flash movies). It's task also is to let you control how your users access these files and what they can do with them.
To configure SPAW File Manager to match your needs you have to specify two main setting nodes: a "global" settings which specifies what can be done with the directories accessible to SPAW File Manager, and a directories list. The global settings can be overriden for each specific directory so you can allow handling only images in your "Images" directory, only flash movies in your "Flash movies" directory and so on. Here is the detailed description for each of these two main parameters:

Name

Description

PG_SPAWFM_SETTINGS

"Global" settings for all directories, specified as attributes of <settings> child node and <allowedFileTypes> and <forbiddenExtensions> elements:

  • allowUpload - boolean value, specifies files upload possibility, "false" by default;
  • maxUploadFilesize - integer value, specifies max file size in bytes to be uploaded, or zero to ignore (default value);
  • maxImgWidth - integer value, specifies max uploaded image width allowed, or zero to ignore (default value);
  • maxImgHeight - integer value, specifies max uploaded image height allowed, or zero to ignore (default value);
  • allowModify - boolean value, specifies if deleting files is allowed, "false" by default;
  • allowedFileTypes - list of allowed file types specified as child <fileType> nodes with value attribute set to file type name: images/flash/documents/audio/video/archives. It specifies files of which type(s) will be listed/allowed to upload. You can add your own filetypes or edit existing by adding/removing extensions in file /plugins/spawfm/config/spawfm.config. If you set to true attriubte named any on allowedFileTypes element, files of all types are allowed. All defined filetypes are allowed by default;
  • recursive - boolean value, specifies if viewing/opening subdirectories is allowed, "false" by default;
  • allowCreateSubdirectories - boolean value, specifies if creating subdirectories is allowed ("recursive" setting must be true), "false" by default;
  • allowModifySubdirectories - boolean value, specifies if renaming/deleting subdirectories is allowed ("recursive" setting must be true), "false" by default;
  • forbiddenExtensions - list of extensions which are forbidden for upload for security or other reasons independenlty of other settings;
PG_SPAWFM_DIRECTORIES

Specific directories to be accessible by SPAW File Manager. Child nodes are <directory> elements each defining a specific directory and it's settings. Each <directory> attribute can have <allowedFileTypes> and <settings> child elements which override defaults set in PG_SPAWFM_SETTINGS setting. <directory> attribute has following attirbutes:

  • path - directory path. This attribute is mandatory.
  • caption - directory title to be seen by users in SPAW File Manager. Plain directory path will be shown if this is not specified, so this is optional parameter.
  • defaultDirectory - if set to true this directory will be selected by default when File Manager loads and no directory is specified.

Usage

You can add SPAW Editor to your page in 3 ways

  1. Through Visual Studio 2005 designer;
  2. By adding declarative tag in your ASP .NET web form/user control;
  3. From code at runtime.

Note: check out source code of demo/demo.aspx and demo/demo2.aspx for usage samples

Adding SPAW Editor through Visual Studio 2005 Designer

Add Editor control to your toolbox (if it's not already there):

Now you should be able to drag-and-drop Editor control from your toolbox on to your Web Form. You can modify various properties through Properties panel in Visual Studio

Adding SPAW Editor through a Tag In ASP .NET Source

First you'll need to register SPAW Editor in your page. To do that add @Register directive at the top of your page like this:

<%@ Register TagPrefix="spaw" Namespace="Solmetra.Spaw2" Assembly="Solmetra.Spaw2" %>

Now you can place SPAW Editor's tag where you want it in your web form like this:

<spaw:Editor ID="Editor1" runat="server" />

Adding SPAW Editor at run-time (C#)

Add using directive:

using Solmetra.Spaw2;

Create Editor control and add it to your page:

Editor spaw1 = new Editor();
spaw1.ID = "Editor1";
Page.Controls.Add(spaw1);

Setting and Retrieving The Content

You can set initial SPAW Editor's content and retrieve the edited content on post-back as you would normally do with a standard TextBox control - using Text property.

Changing Configuration At Design or Runtime

You can override configuration settings at runtime on per-instance basis. Many of the configuration options described in the section of configuration are represented by their respective properties of Editor class. Use Visual Studio properties sheet or Intellisense in the code editor to set any of them.

When a configuration setting has no respective property in Editor class (plugin configuration settings don't), you can access configuration settings directly through Configuation property of Editor object. This code

spaw1.Configuration["PG_SAMPLEPLUGIN_COLOR"].Value = "Red";

sets value of the configuration property named PG_SAMPLEPLUGIN_COLOR to "Red"

Adding Pages

You can edit multiple documents (html snippets) with a single instance of SPAW Editor v.2.

Pages could be added using Visual Studio dialogs, declaratively or through code.

This snippet

<spaw:Editor ID="spaw1" runat="server">
 <Pages>
    <spaw:EditorPage Caption="English text" ClientID="spaw1" />
    <spaw:EditorPage Caption="Lithianian translation" ClientID="spaw1_2" />
  </Pages>
</spaw:Editor>

specifies that SPAW Editor "spaw1" should have 2 pages (tabs): English text and Lithuanian translation. ClientID attribute of the first page should be equal to the ID of editor instance. Caption attribute specifies text visible to users as title on the "tabs". You can also set initial content by setting Text property of the page.

To add pages through code you add EditorPage objectes to Pages collection of the Editor object like this

spaw1.Pages.Add(new EditorPage("spaw1_2", "Lithianian translation", initialContent));

First parameter is page's ClientID, second - Caption, third - initial content (html snippet). Note that the first page (with the same ClientID as editor's ID) is added automatically. You can modify it's properties (caption and text) by accessing respective properties of the first EditorPage object in Pages collection like this:

spaw1.Pages[0].Text = dbvalue1;
spaw1.Pages[0].Caption = "First page";

Pages can be accessed by their ClientID too:

spaw1.Pages["spaw1_2"].Caption = "Second page";

To read modified page content after the page is submitted you just access the Text property of the EditorPage object:

string myValue = spaw1.Pages["spaw1_2"].Text;

Text property of the Editor object always returns Text property value of the first page.

Note: see source code of demo/demo2.aspx for a samples

Toolbars

Using Toolbars

You can control which toolbars are included with your instance by adding a toolbar set to your instance. You define toolbar sets in the config file (see section on Toolbarset configuration) and the specify which toolbar set you want to use by setting ToolbarSet property of Editor object

spaw1.ToolbarSet = "mini";

Floating and/or Shared Toolbars

In SPAW Editor v.2 single toolbar can control one or several editor instances. It can either be attached to one of the instances or floating around.

To enable floating toolbar you set FloatingMode property to true.

If you set ToolbarFromID property to ID of another instance of Editor object this editor will be controlled by toolbar of specified editor instance. Instead of setting ToolbarFromID you can assign actual Editor instance of the master toolbar to ToolbarFrom property.

spaw2.ToolbarFrom = spaw1;

Custom Toolbars

You can create custom toolbars by copying one of the standard toolbars in plugins/core/lib/toolbars/ subdirectory and removing/adding toolbar items in that file. Unless you are a plugin developer (see plugin developers documentation) you only need to copy/paste or delete rows in these files. Theme designers can designate special placements for standard toolbars so, if you want your custom toolbar to appear in a place of standard toolbar you should use the toolbar substitute concept described earlier

FileManager Settings

To modify File Manager settings at runtime you use a special helper class called SpawFMConfiguration in Solmetra.Spaw2.SpawFM. To get current File Manager configuration you use static methods GetFileManagerConfiguration(Editor editor) and pass your Editor instance as a parameter

SpawFMConfiguration fmcfg2 = SpawFMConfiguration.GetFileManagerConfiguration(spaw2);

GlobalSettings property of SpawFMConfiguration object provides access to global settings of the File Manager configuration specified in PG_SPAWFM_SETTINGS configuration setting. For example to allow browsing of subdirectories across all directories defined in config file (unless otherwise specified on per-directory level) you set fmcfg2.GlobalSettings.Recursive = true;

Directories property holds a collection (DirectoryCollection) of Directory objects representing each directory configured for File Manager access. Settings property provides access to directory-level settings overriding global settings set through SpawFMConfiguration.GlobalSettings property.

Important: changes to directories and settings aren't applied immediately as they are set. After you have finished changing File Manager configuration you should call Apply() method like this fmcfg2.Apply()

The following example taken from Demo #2 (demo/demo2.aspx) removes all the directories except "Images" from the spaw2 instance of Editor and allows browsing of subdirectories of Images in that instance (other instances on the same or other pages aren't affected)

// we retrieve file manager configuration for the spaw2 instance
SpawFMConfiguration fmcfg2 = SpawFMConfiguration.GetFileManagerConfiguration(spaw2);
// We look for Images directory configured in default config file (this will fail if config file has been modified in this section)
if (fmcfg2.Directories.IndexOf(Solmetra.Spaw2.Configuration.SpawDirectory + "uploads/images/") > -1)
{
  // we get the Directory object
  Directory d = fmcfg2.Directories[fmcfg2.Directories.IndexOf(Solmetra.Spaw2.Configuration.SpawDirectory + "uploads/images/")];
  // and set Recursive setting on it
  d.Settings.Recursive = true;
  // we remove all the other directories from configuration
  fmcfg2.Directories.Clear();
  // and add only the Images directory (retrieved above)
  fmcfg2.Directories.Add(d);
  // then we apply the configuration
  fmcfg2.Apply();
}

Note: see source code of demo/demo2.aspx for a sample