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.
SPAW Editor .NET Edition v.2 runs on ASP .NET version 2.0 setup (including medium trust environments like shared hosting accounts, etc.).
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.
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).
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.
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 |
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 © etc. |
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 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 |
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.
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:
|
| 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:
|
You can add SPAW Editor to your page in 3 ways
Note: check out source code of demo/demo.aspx and demo/demo2.aspx for usage samples
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
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" />
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);
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.
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"
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
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";
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;
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
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