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

Table of Contents

• About
• System Requirements
• Installation
• Configuration
  • Core Configuration Settings
    • Editor Defaults
    • SPAW Engine Settings
    • Dropdown Data
    • Toolbar Sets
    • Colorpicker Predefined Colors
  • SPAW File Manager Plugin Settings
• Usage
  • Adding SPAW Editor through Visual Studio 2005 Designer
  • Adding SPAW Editor through a Tag In ASP .NET Source
  • Adding SPAW Editor at run-time (C#)
  • Changing Configuration At Runtime
  • Adding Pages
  • Toolbars
    • Using Toolbars
    • Floating and/or Shared Toolbars
    • Custom Toolbars
  • FileManager Settings

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

SPAW Engine Settings

These settings determine inner behavior of various SPAW engine components

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.

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.

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:

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):

• right-click somewhere in your toolbox;
• click "Choose Items..." in the context menu;
• "Choose Toolbox Items" dialog opens;
• in the tab ".NET Framework Components" click "Browse..." button;
• navigate to Bin directory of your project, select Solmetra.Spaw2.dll and click Open;
• click "OK"

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