Web Crossing Customization Management Suite (WCMS) Developer Documentation

» API for Developers (WCMS Projects)

Web Crossing's goal in creating the Web Crossing Customization Management Suite (WCMS) is to make it easy for non-technical Web Crossing administrators to customize their sites and add new features. From the sysop perspective, WCMS is a set of menus and forms which allow them to add new features or change the look and feel of their site at the click of a button. Besides look and feel customization, new kinds of predefined objects can be added to the site automatically, appearing in the user interface without any additional scripting.

At the developer level, WCMS is an API which allows developer projects to "plug in" to the Web Crossing user interface automatically, without scripting on the part of the end-user/sysop. Web forms are used for any configuration or setup that is necessary. As a shortcut, these macro sets will be referred to as "projects" in this document.

A project consists of a group of files and images which make use of the WCMS API to provide the sysop of a site with an additional option for a Theme, Component, Extension, Folder Item or User Item. Installing and configuring macros and files is automated in most cases.

The WCMS API allows you to easily create or adapt projects, along with the settings-edit pages necessary to provide sysop control over the variables you create. You can edit an existing Theme or WCMS project or create your own from scratch. You can create a new button set or use an existing one, and include any number of custom images. Projects' file names, file structure, macro construction, etc. must conform to the API in order to work.

Types of Projects
You can create any one of 5 different types of projects:

• Theme: a look/feel "wrapper" for the page.
• Component: a top level view, folder view, message view, or toolbar.
• Extension: a project which adds a new function, but which doesn't fit into any of the other existing project types. LiveX, sysop tools.
• Folder Item: adds a new type of item inside a folder. Weblogs, shared calendars.
• User Item: adds a user-specific function. User calendar, subscriptions manager.

The list of files required for each given type of project is covered in more detail below.

To help you get started, we've created a number of working developer demo projects which you can study and use as starting points for your own development or adaptations. Look for the files (they're not encrypted) in the Documentation and Developer Support folder on the Plugins Server.

• Demo Theme
• Demo Component (a toolbar)
• Demo Extension
• Demo Folder Item
• Demo User Item

» Project Names

» WCMS Inheritance and path$xxxxx variables

A set of automated form processors in webxWcms-admin.tpl set whatever variables are fed to the forms from the various edit macros for Themes or projects, allowing you to easily develop editable variables for use in your macros without worrying about processing macros.

The processor will set a path.xxxxx for any variable which comes to it in a form field. So by simply setting up your Edit page correctly, the built-in form processor will write an Edit Confirm page automatically, and the path variables will be set.

Because of the way the automatic processor works, a variable can have one of three values:

• A specific value specified by the user (this specific value would then be used)


• An empty-string value (no value, and the inherited parent value would be used)


• The text string "none," (no value, and the value from the parent would not be inherited)

%% set myValue path$inner_fl_myValue %%
%% if myValue && myValue != "none" %%
	%% myValue %%
%% endif %%

Note that a significant performance advantage is obtained by first setting the local variable "myValue" to the path$inner_fl_myValue variable. Subsequently the value of "myValue" is checked and displayed. This avoids the cost of looking up the hierarchical value of the path$inner_fl_myValue variable multiple times.

» Naming Conventions, FileNames, and Variables

Path variables

Project type	Variable prefix
Themes	wrap_
Component: top level	inner_tl_
Component: folder list	inner_fl_
Component: message list	inner_ml_
Component: toolbar	inner_tb_
Extension	inner_
Folder Item	inner_
User Item	inner_

A path variable which does not begin with either "wrap_" or "inner_" will not be exported when you create a Theme configuration ".set" file and thus is not importable or installable unless you specifically set it in an init function.

Examples: path.wrap_leftSide, path.inner_fl_leftSide.

For the most part, variables already exist within the Theme Manager system, so you if you're developing a new Theme, you won't need to create any new variables unless you have special Theme elements that require them.

Language String Variables

Localization within Web Crossing takes place by string substitutions from a global JavaScript object holding all the strings for a given project. Your project's language object name (the object holding the strings for your particular project) should be the same as your project. More specific information is below in the Localization section.

The names of your language strings are less critical. You should name them something which makes the associated text easy to identify by looking at the string name, but the exact syntax and any naming conventions are up to you.

Since localizability can be turned on and off, you shouldn't count on any strings from other projects (such as webxStd-Local.tpl) on being available. However, webxextn.tpl is always localizable, and always loaded, so those strings are always available for you to use if you want to avoid re-defining common terms such as "Cancel," "OK," etc.

For more information on filename conventions, see Files Needed for A Project, below.

» HTML and CSS

Web Crossing 5.0 has stylesheet-based HTML. Since our goal is to support as broad a browser base as possible for our customers, we have taken some steps to ensure that the user interface works acceptably-well for older browsers back through 4.0, and that options are available for sites supporting users with browsers older than that.

We strongly encourage you to follow the WCMS conventions for HTML and CSS.

Specifically, we have done the following:

Technique	Rationale
Surrounded all text inside table cells with <p> tags or span class="text"	Older browsers, specifically Netscape 4, do not always deal with inheritance properly. This ensures that text inside table cells will be properly styled
Close all tags with optional close tags, such as <p> and </p> and <li> and </li>, <a name="x"> and </a>, etc.	Required by CSS
All text should be inside a container of some kind, probably <p> tags. You can also apply a style to a <div> and use that.	Work around Netscape 4 inheritance bugs.
<p> tags shouldn't be used as line breaks, but as containers for text.	Required by CSS
Text following form fields	Netscape 4 has a habit of dropping styles in text which appears after a form field. Thus, best practice is to surround this text with a specific <span class="text">text</span> tag (or div, or p, etc.) to ensure that styles are applied to this text properly.
Quoted Attributes	Reqired by XHTML. In most cases (but not all) we have quoted HTML attributes in template code, but the server code has not been updated yet this way.
Lowercase HTML	Required by XHTML. In most cases (but not all) we have lowercased all HTML in template code, but the server code may not have been updated yet.
Font tags	As much as is practical, get rid of font tags and use stylesheet indications for font face, color, and size. There are predefined classes for sizes 1 through 6 (size1, size2, etc.) which roughly approximate the old font size=NN values. (OK for span, div, p, etc.).

CSS

We have provided some basic CSS classes which are available for you to use, and you can create your own classes for your projects and include them in a custom stylesheet. The default Web Crossing (no themes) stylesheet macro is in webxextn.tpl (defaultStylesheet). The default stylesheet for Themes is also in webxextn.tpl (themeStylesheet). If no stylesheet variable is present, the contents of the file "default.css" in the /system directory are imported, saved, and used. We calculate the initial font size measurement using a site default with a user preference to change the site default in the user preferences area. Once a base font size is determined, everything else is calculated from that using ems or percentages. You can also install the Quick Set Fonts extension to allow registered users and guests to set their preference directly from your sidebars.

Available classes are:

Class	Function
.text	Mirrors the body text size in case you need to invoke it specifically where it may not be inherited as it should be
.size1 through .size6	These roughly correspond to the old <font size=N> tags
.treeTitle	For message titles
.alert	Bold red for warnings, errors, important status messages
.red	Red text, but not bold.
.pathTitle	Folder and discussion titles, as well as other titles appearing in the title position at the top of the page
H3.subtitle	For H3s used in a "subtitle" role
.mlMsg	Surrounds the message itself
.fl	Surrounds the folder listing
.backpath	Surrounds the backpath
.preparedFor	Surrounds the optional "prepared for..." statement at the top of the page.

All textareas and text input tags have a sysop-definable monospaced font applied to them to attempt to get the fields to appear the same size in Internet Explorer and older Netscapes.

There are some basic Web Crossing CSS conventions you should employ for consistency:

	Situation	Example
Page Titles	For all "title" type headings at the top of the page, whether or not it truly Is the "pathTitle." Note that these are no longer indented with <ul>'s, but can be indented with stylesheet control if desired.	<h1 class="pathTitle">Title of Page</h1>
Subtitles	For all H3's used as subtitles	<h3 class="subtitle">Subsection</h3>
Backpath	For %% backpath %% and %% backpaththis %%	<p class="backpath">%% backpath %%</p>
Alert	For warning or important alerts (also can use for span, div, p, H3, etc.)	<span class="alert">Alert Text</span>
Red	For red text, not necessarily a warning (example: "subscribe by email" text in addMessage) (also can use for span, div, p, H3, etc.)	<p class="treeTitle">Title</p>
pathTreeTitle	All pathTreeTitles (or places where pathTitle is used where the tree title should have been, were there one) (also can use for span, div, p, H3, etc.)	<p class="treeTitle">Title</p>
Same-page Anchors	Anchors needs to be closed, but without text inside them, and with a class of "none."	<a name="xxxx" class="none"></a>
Message text	Surround all cases where messages are displayed with class "mlMsg." This includes search results, moderation preview/edit pages, messageListItem, discussionTree, message center page, etc.	<div class="mlMsg">... </div>

For more information on replacing the stylesheet or adding to it see the Stylesheet section just below.

» Colors

Color variables are set as path.varName and called as path$varName. These are the predefined variables you can use (the exact colors these represent will vary by Theme, but the names give you an idea). The indicator after the variable name represents its default use. You can use any of these you want elsewhere.

path.wrap_Icons	regular icon directory
path.wrap_Images	regular button directory
path.wrap_hotImages	rollover directory (not defined by default)
path.wrap_clickImages	onmousedown directory (not defined by default)
path.wrap_sectionHeadingColor	for section-heading background colors
path.wrap_hostHeadingColor	host-only links or headings (see subscribe page for an example)
path.wrap_BgColor	body tag page bg color
path.wrap_TextColor	body tag text color
path.wrap_LinkColor	body tag link color
path.wrap_ALinkColor	body tag active link color
path.wrap_VLinkColor	body tag visited link color
path.wrap_HoverColor	stylesheet hover color
path.wrap_pathTitleColor	"pathTitle" h1 title color
path.wrap_h3SubtitleColor	subtitle h3 color
path.wrap_bannerBackground	top cell background image
path.wrap_bannerBgcolor	top cell background color
path.wrap_bannerFontColor	top cell font color
path.wrap_bannerLinkColor	top cell link color
path.wrap_bannerVLinkColor	top cell vlink color
path.wrap_bannerALinkColor	top cell alink color
path.wrap_bannerHoverColor	top cell hover color
path.wrap_contentBackground	content cell background image
path.wrap_contentBgcolor	content cell background color
path.wrap_navBackground	nav cell background image
path.wrap_navBgcolor	nav cell background color
path.wrap_navFontColor	nav cell text color
path.wrap_navLinkColor	nav cell link color
path.wrap_navVLinkColor	nav cell vlink color
path.wrap_navALinkColor	nav cell alink color
path.wrap_navHoverColor	nav cell hover color
path.wrap_specialEventsBackground	multi-purpose column background image
path.wrap_specialEventsBgcolor	multi-purpose column background color
path.wrap_multiFontColor	multi-purpose cell font color
path.wrap_multiLinkColor	multi-purpose cell link color
path.wrap_multiVLinkColor	multi-purpose cell vlink color
path.wrap_multiALinkColor	multi-purpose cell alink color
path.wrap_multiHoverColor	multi-purpose cell hover color
path.wrap_footerBackground	bottom cell background image
path.wrap_footerBgcolor	bottom cell background color
path.wrap_footerFontColor	bottom cell font color
path.wrap_footerLinkColor	bottom cell link color
path.wrap_footerVLinkColor	bottom cell vlink color
path.wrap_footerALinkColor	bottom cell alink color
path.wrap_footerHoverColor	bottom cell hover color
path.wrap_footerBgcolor	bottom cell background color
path.inner_fl_darkerColor	folder listing darker color
path.inner_fl_lighterColor	folder listing lighter color
path.inner_fl_lightestColor	folder listing lightest color
path.inner_fl_whiteColor	folder listing white equivalent
path.inner_fl_fontColor	font color for table headings (folder listing)
path.inner_ml_darkerColor	message listing darker color
path.inner_ml_lighterColor	message listing lighter color
path.inner_ml_lightestColor	message listing lightest color
path.inner_ml_whiteColor	message listing white equivalent

» Buttons and Rollovers

Here's an example of a typical localized button call in 5.0:

%% set id "cancel" %%%% use getAttr %%%% "cancel.gif".siteImagesImg( user.language, Â
"lang( 'extn', 'btncancel' )".jsEval, "align=""middle"" border=""0"" hspace=""0""" & attr ) %%

If a path$wrap_hotImages directory (e.g. "/Images/b29" is defined, those buttons will be used for onmouseover events. If, in addition, a path$wrap_clickImages is defined, those buttons will be used for onmousedown events.

Without rollover and click directories defined, the HTML returned by the Cancel button call above is:

<img src="/Images/b26/cancel.gif" width=68 height=30 alt="Cancel" border="0" hspace="0" name="cancel">

<script language="javascript"><!--
if ( document.images ) {
cancel_hot = new Image;
cancel_cold = new Image;
cancel_click = new Image;
cancel_click.src = "/Images/b20/cancel.gif";
cancel_hot.src = "/Images/b27/cancel.gif";
cancel_cold.src = "/Images/b26/cancel.gif";
} else {
cancel_click = "";
cancel_hot = "";
cancel_cold = "";
document.cancel ="";
}//-->
</script>
<img src="/Images/b26/cancel.gif" width=68 height=30 alt="Cancel" border="0" Â
hspace="0" name="cancel" onmouseover='this.src=cancel_hot.src;' Â
onmouseout='this.src=cancel_cold.src;' onmousedown='this.src=cancel_click.src;'>

The "id" variable is used for the "name" attribute of the image tag, and is typically the filename of the button minus the extension, with a couple of exceptions:

• The id must be unique for each button on the page, so if you have a situation where you have two cancel buttons, or two OK buttons, etc. on one page, each one needs a different id. You can accomplish this by prefixing the button name with "btnN", where N is a number. The first 4 characters will be discarded when the attributes are constructed.

  %% set id "btn1ok" %%

• If the button name is a Javascript reserved word, you must prefix this with "btnN", where N is a number. The first 4 characters will be discarded.

  %% set id "btn1ok" %%

• If you have two submit buttons for one form, the "name" value is used for form processing, and sometimes you need to specify a "name" value different from the button name. You can do this by prefixing the name of the button with "inpN", where N is a number, the name value you want set, an underscore, and the button filename.

  %% set id "inp1Post_pstmymsg" %%

For WCJS, you can use the makeButton(), makeIcon() and makeSubmit() functions to simplify button creation. See the documentation for more details.

» Date Formatting

The defaults are:

path$wrap_defaultLongDateFormat	"Mmm D1, Y4 H2:I2 a"	Jan 1, 2004 08:02 am
path$wrap_defaultShortDateFormat	"M1/D1/Y4 Y4 H2:I2 a"	1/1/2004 08:02 am
path$wrap_defaultMiniDateFormat	"D2 Mmm Y4"	01 Jan 2004

A real-life coding example:

%% set longDate path$wrap_defaultLongDateFormat %%
%% if longDate && longDate != "none" %%
	%% set date_format longDate %%
%% else %%
	%% set date_format "Mmm D1, Y4 H2:I2 a" %%
%% endif %%
%% pathModifiedDate( date_format ) %%

» Accessibility Issues

The two main Priority 1 tasks in Web Crossing are:

All graphical elements, buttons, and submit input tags need alt tags., and all scripts and applets providing necessary functionality need an alternative accessible link or function.

We also support some of the Priority 2 recommendations, in particular the <label> tag, which allows the form element to be associated with its text label in disability access browsers.

The form field itself needs a unique ID, which is referenced in the label tag:

<label for="username">User Name</label> <input type="text" name="username" value="" id="username">

<input type="radio" id="name_value1" value="value1" name="name">
<label for="name_value1">Yes</label><br>
<input type="radio" id="name_value2" value="value2" name="name">
<label for="name_value2">No</label><br>
<input type="radio" id="name_value3" value="value3" name="name">
<label for="name_value3">Maybe</label><br>

» Available Hooks outside WCMS

Stylesheets and Projects

The stylesheet macro is used to put a stylesheet link URL in the current page, and is called in the Theme document head field if Themes are on (and the stylesheet has not been disabled), or by superHeaderDefault, a macro which runs automatically from the head of the document if Themes are off. The stylesheet URL uses the themeStylesheet or defaultStylesheet macros to actually serve the style sheet for a page as a separate dynamically-created page. By serving dynamic stylesheets, we can easily customize the look of the site for different users or locations.

In order to allow the browser to cache the various stylesheets that we serve, the stylesheet URLs are "standard" URLs without a user certificate, but including a stylesheet revision number to force stylesheet reloads if/when needed.

A stylesheet usually is provided with a theme, but sometimes components or extensions need support for custom classes. So we've provided some stylesheet hooks for other projects to drop their styles into the stylesheet.

This is how it works:

• If Themes are turned off, a macro called superHeaderDefault calls macro stylesheet. superHeaderDefault is run automatically in the head of the document when Themes are off.
• If Themes are turned on, macro stylesheet is called directly from the Theme machinery.
• Macro Stylesheet looks for the presence of the user calendar macros and returns without doing anything if it's called for a user calendar page. (The calendar has its own built-in style mechanism). Stylesheet inserts the meta tag for the correct site character set and then, if Themes are on it calls themeStylesheet, and if Themes are off it calls defaultStylesheet.
• Stylesheet constructs a link to the stylesheet using the "slash" WebX URL syntax, so the browser can cache it where appropriate.
• A variable called site.cssRev is incremented when the file cache is reset, the banner/footer page is edited, or any of the Theme settings are edited which could potentially change stylesheet information. Furthermore, another variable called user.cssRev is incremented when the user submits their user preferences. These variables are worked into the stylesheet URL so that the URL changes when any of these events occur so the browser is forced to fetch a fresh stylesheet. The folder location is also in the URL so a fresh stylesheet is fetched for each new folder a user visits. The "pseudo" filename "style.css" is added at the end so browsers treat it correctly.

  href="/WebX/.ee6b280/themeStylesheet/rev.26/sysRev.700/style.css"
  

  Translates to: /WebX/location/macroName/user.cssRev/site.cssRev/style.css, where location in this example is ". ee6b280", the macroName is "themeStylesheet", and either rev or sysRev are incremented when the stylesheet has changed.

Usually only a Theme would replace the stylesheet, but any of your projects can either replace the default or themeStylesheets or you can add your own custom style definitions at the bottom of either of them. If you have a need to replace macro stylesheet as well, that is also possible (although inadvisable unless you know exactly what you're doing and why.)

To replace the stylesheet that is run when Themes are turned on, just replace the stylesheet in the Theme settings > Global settings > default stylesheet textarea. The value of this field is held in path$wrap_stylesheet.

Here's an example of the theme stylesheet as it appears in the browser, after variable substitutions, and not including any additional classes provided by plugins:

/* basic WebX CSS */
a.none {background:transparent} /* for anchor links only */
a:link {font-weight: bold; text-decoration:none;}
a:visited{font-weight: bold; text-decoration:none; }
a:active {font-weight: bold; text-decoration:underline; }
a:hover {font-weight: bold; text-decoration:underline; }
small {font-size:.9em}
big {font-size: 1.1em}
address, b, big, blink, blockquote, body, center, cite, dir, Â
dl, div, em, h1, h2, h3, h4, h5, h6, i, legend, listing, menu, Â
object, ol, p, s, server, small, span, strike, strong, sub, sup, Â
table, td, th, u, ul, li, var, xmp { font-family: Arial;}
body,p,ul,li,td {font-size:12px; }
.2 {font-size:10px; }
.text {font-size:12px;font-family:Arial;}
code, kbd, pre, samp, tt,form,input,textarea {font-family: Courier, Â
"Courier New", Monaco, monospace;font-size:12px; }
h1 { font-size: 26px; }
h2 { font-size: 21px; }
h3 { font-size: 18px; }
h4 { font-size: 15px; }
.size1 { font-size:9px; }
.size2 { font-size:10px; }
.size3 { font-size:12px; }
.size4 { font-size:17px; }
.size5 { font-size:20px; }
.size6 { font-size:24px; }
.text { font-size:12px; }
h3.subtitle{ font-style:italic; color:#666666; }
.treeTitle { font-weight: bold; }
.pathTitle { font-size:28px; color: #444444; } 
.backpath {font-size:12px; font-weight:bold; }
.mlMsg { font-size:12px; }
div.mlMsg blockquote { font-style:italic; } 
.nonbold { font-size: .9em; }
.red { color: red; }
.alert { color: red; font-weight: bold; }
.preparedFor { background: white; }

For real-life examples of how to do this, see macro demoFdrItemStyleJS in wx_demoFdrItem.auto.

%% command myProjectStylesJS() { 
	wctlEval( 'use myProjectStyles' );
} %%

%% macro myProjectStyles %%
	%% set myStyles path$inner_myProject_stylesheet %%
	%% if myStyles && myStyles != "none" %%
		%% set body body & myStyles.fromSgml.evalTemplate & crlf & crlf   %%
	%% else %%
		%% set f "/* My Project Styles */" & crlf &
		".myProject{ color: %" & "% color %" & "%; font-family: Courier; font-size: 18px; }" %%
		%% set body body & f.evalTemplate & crlf & crlf  %%
		%% set curLoc location %%
		%% set x path$inner_myProject_stylesheet %%
		%% setPath( pathHierLocation ) // find the location where the stylesheet is defined %%
		%% set path.inner_myProject_stylesheet f %%
		%% setPath( curLoc ) %%
	%% endif %%
%% endmacro %%

Preferences

If your project needs access to the user preferences page, you can create a Javascript command or function which will be plugged into the editPreferences/editedPreferences macros. You can use the editPreferences page to display your form (keeping in mind that it needs to fit into an existing two-column table structure) and the editedPreferences page to process your form fields and display the results (again, keeping in mind that it has to fit into an existing two-column table).

Create your preferences form and processor and name them whatever you want - but do use the name of your proejct in the preferences command/function name to ensure the function name is unique. Then and add the name of your function to the proper location in the object definition in your init file. Example:

For editPreferences:

%% function demoFIEditPrefs() {
	var text='';
	text += '<tr><td colspan="2"><p><b>Your Demo Folder Item Color Preference</b></p></td></tr>';
	text += '<tr><td colspan="2"><p><input type="radio" value="red" name="demoFIColor"';
	if ( user.demoFIColor == "red" ) text += " selected";
	text += '> Red<br><input type="radio" value="blue" name="demoFIColor"';
	if ( user.demoFIColor == "blue" ) text += " selected";
	text += '> Blue</p></td></tr>';
	return text;
} %%

%% function demoFIEditedPrefs() {
	var retval='';
	if ( form.demoFIColor ) user.demoFIColor = form.demoFIColor;
	retval += '<tr><td><p><b>Your Demo Folder Item Color Preferences</b></p></td><td><p>';
	if ( user.demoFIColor == "red" ) retval += "Red";
	else retval += "Blue";
	reval += '</p></td></tr>';
	return retval;
} %%

Control Panel Links

If your project needs to provide one or more control panel links, you can do that in a similar way. Create your link, and add the name of your link function to the proper location in the object definition in your init file. As an example of this, see this example function demoExtControlPanelLink from the wx_demoExt.auto.

%% command demoExtControlPanelLink() {
	return '<br><br><a href="' + makeUrl( 'demoExtControlPanel' ) + '">Demo Extension Link</a>';
} %%

Theme Cells: top cell, nav cell, multi-purpose cell, bottom cell, content cell pre and post

You can have your project add links to, or call macros for, the various Theme cells. The Weblog sidebar macro and LiveX are examples of this. Your project can actually enable the functionality to appear in the desired cell, or it can merely place itself as an option in the menus for the area, for the sysop to select if the default positioning isn't what they want .

It takes two steps to do this:

• Add the calls to your object definition using the method plugSetThemeHooks(). Each call requires two parameters, the name of the WCTL macro (or WCJS command without any parameters) and a flag to tell whether it should be ignored ( "" ), placed in the menu, 0, or selected, 1.
• Add a couple of lines to your init statement to add your project to a palette of projects which appear at the end of the Theme Optional Item menus.

For an example of a macro which merely places a link on the page, see macro demoUserItemLink in wx_demoUserItem.auto, and for an example of a macro which places an entire block of HTML in the right or nav columns, see macro sidebar in wx_blog.auto. If you are placing a link to a user item or a folder item, you need to have your macro check to see if it should return anything or not, based on the location, the user, and the enabled status of the project. You can use the JS functions checkUIStatus( projectName ) and checkFIStatus( projectName ) to check to see if the user should have access to the function. checkUIStatus returns true or false for WCJS, and also sets the WCTL variable "toShow" to "yes" if true. checkFIStatus does this as well, and in addition sets the WCTL variable "toShow" to "guest" if the user is unknown.

» Filter Issues

If you have a filter enclosed in a folder macro, you probably will want to also make the filter from the parent level available (in case it's something like reporting, which need to always run.) You can do this by adding a line like this at the end of a section your filter which doesn't interrupt processing:

%% useParent messageAddFilterPost %%

%%  "authenticateFilter".filterRegister("authenticateFilter_myFilter" ) %%

This would run the extra authenticate filter "macro authenticateFilter_myFilter" after the normal one.

» Initing Your Project

Here's an example init for a user item, annotated: (the  indicates that there should be no hard line break in this location, but it is broken for display purposes here). More details about the various methods and arguments are below in the table.

 1 %% function init_demoUserItem() {
 2         if ( !libraryGlobal.userItemPalette ) libraryGlobal.userItemPalette = new Object();
 3         var ui = libraryGlobal.userItemPalette;
 4
 5         // replace demoUserItem 3 x with your project name in the next 2 lines
 6       if ( topLevelFolder.userItemPaletteBkp && topLevelFolder.userItemPaletteBkp.demoUserItem Â
 7         && topLevelFolder.userItemPaletteBkp.demoUserItem.plugIsEnabled ) {
 8            var isEnabled = topLevelFolder.userItemPaletteBkp.demoUserItem.plugIsEnabled;
 9         } else var isEnabled = 0;
10
11      // your project name
12      if ( !ui.demoUserItem ) {
13
14         /* use isEnabled (variable set just above), default enabled?, toolbar enabled?, 
15            url to open userItem, string for text toolbar, string for button alt tag,
16            open button filename
17            all required (replace this with the right constructor for your project type!) */
18          ui.demoUserItem = new ShortUserItem( isEnabled, 1, 1, "demoUserItemPage", Â
19            "openButtonAlt", "demoUserItem.gif" );
20                    
21         /* version, date
22            both required */
23         ui.demoUserItem.plugSetVersion( "1.0", "11/14/02" );
24
25         /* directory in WCMS, small screenshot filename, W in pixels, H in pixels,
26             large screenshot filename, W, H, full support URL, ReadMe file name
27            all required */
28         ui.demoUserItem.plugSetWcmsFiles( "demo", "demo.gif", 164, 109, "demoL.gif",Â
29            600, 400, "http://support.webcrossing.com", "readme.html" );
30
31         /* auto file name, (template file name), (envelope file name)
32            auto file name required (for some other projects, need all three arguments) */
33         ui.demoUserItem.plugSetTplFiles( "wx_demoUserItem.auto" );
34
35         /* strings object name, strings file name, string for "Friendly" name for UI,
36            string for short description for "choose" page
37            all are required */
38         ui.demoUserItem.plugSetStringProps( "demoUserItem", "wx_demoUserItem_s_en_US.auto", Â
39            "projName", "shortDescr" );
40
41         /* 1 if extension has editable parameters and 0 if not, name of edit WCTL macro,
42            string name for explanatory text on edit page
43            all required */
44         ui.demoUserItem.plugSetEditables( 0, "editDemoUserItem", "explanText" );
45
46         /* JS macro for prefs page, JS macro for edited prefs, JS macro to add to stylesheet,
47            JS macro to add to Control Panel Services, JS macro to add to Control Panel Customizing,
48            JS macro to add to Control Panel User, JS macro to add to Control Panel Site
49            all optional but if present must be in .auto file */
50         ui.demoUserItem.plugSetInterfaceHooks( demoUserItemEditPrefs, demoUserItemEditedPrefs,Â
51             demoUserItemStyleJS, "", "", "", "" );
52
53         /* WCTL macro to be inserted in theme top cell, 1 if enabled by default
54            and 0 if merely in menu, WCTL macro for bottom theme cell, enabled or not,
55            WCTL macro for nav theme cell, enabled or not, WCTL macro for multi-purpose theme cell,
56            enabled or not, , WCTL macro for content theme cell pre, enabled or not, WCTL macro
57            for content theme cell post, enabled or not
58            all optional */
59         ui.demoUserItem.plugSetThemeHooks( "", "", "", "", "demoUserItemLink", 1, "", "", Â
60            "", "" );
61
62         /* Flag to determine if the user can turn this off or not in their personal preferences;
63            1 if it should be shown as an option in prefs, 0 if not */
64         ui.demoUserItem.plugSetUserPrefsEditability( 1 );
65			
66         /* This provides an avenue for an extra level of access checks if
67		you need to check user group membership, etc. for access to buttons and user
68		item "add" screens.
69		Return 0 to prevent access to the button; return 1 to enable it. */
70         ui.demoUserItem.plugCheckButtonAccess = sayNodemoUserItem;
71
72         /* If present, this replaces the entire <a href tag in the toolbar link.
73		return the complete <a href tag */
74         ui.demoUserItem.plugToolbarLink = toolbarLinkdemoUserItem;
75
76         /* If present, this provides extra text or code which is placed
77		in the toolbar before the button
78		return the code you want placed in the toolbar */
79         ui.demoUserItem.plugButtonBeforeText = buttonBeforedemoUserItem;
80	}
81         /* for macros in other areas of the Theme wrapper
82         var demoUserItemArray;
83         demoUserItemArray = [ "demoUserItem", "userItem", "" ];
84
85         /* need one of these to correspond with each of the cells defined in plugSetThemeHooks, above
86         comment out the pairs of lines you don't need */
87	   //if ( !libraryGlobal.optionalItemsPalette.banner ) Â
89            libraryGlobal.optionalItemsPalette.banner = new Object();
90	   //libraryGlobal.optionalItemsPalette.banner.demoUserItem = demoUserItemArray;
91	   //if ( !libraryGlobal.optionalItemsPalette.footer ) Â
92            libraryGlobal.optionalItemsPalette.footer = new Object();
93	   //libraryGlobal.optionalItemsPalette.footer.demoUserItem = demoUserItemArray;
94	   if ( !libraryGlobal.optionalItemsPalette.nav ) Â
95            libraryGlobal.optionalItemsPalette.nav = new Object();
96	   libraryGlobal.optionalItemsPalette.nav.demoUserItem = demoUserItemArray;
97	   //if ( !libraryGlobal.optionalItemsPalette.right ) Â
98            libraryGlobal.optionalItemsPalette.right = new Object();
99	   //libraryGlobal.optionalItemsPalette.right.demoUserItem = demoUserItemArray;
100	   //if ( !libraryGlobal.optionalItemsPalette.contentpre )  Â
101            libraryGlobal.optionalItemsPalette.contentpre = new Object();
102	   //libraryGlobal.optionalItemsPalette.contentpre.demoUserItem = demoUserItemArray;
103	   //if ( !libraryGlobal.optionalItemsPalette.contentpost  Â
104            libraryGlobal.optionalItemsPalette.contentpost = new Object();
105	   //libraryGlobal.optionalItemsPalette.contentpost.demoUserItem = demoUserItemArray;
106
107 } %%

For a Theme, when the .set file is imported, if the navigation column is turned on, and the Login/Logout settings are turned on, the default "You have guest access..." (preparedFor) text is turned off. If you need to re-enable it for some reason, you can use:

%% userGuests.setUserShowPrepared( 1 ) %%

WCMS Constructor/Method Documentation

libraryGlobal.themePalette.projectName.parameterOrMethod
libraryGlobal.componentPalette.topLevel.projectName.parameterOrMethod
libraryGlobal.componentPalette.folderList.projectName.parameterOrMethod
libraryGlobal.componentPalette.messageList.projectName.parameterOrMethod
libraryGlobal.componentPalette.toolbar.projectName.parameterOrMethod
libraryGlobal.extensionPalette.projectName.parameterOrMethod
libraryGlobal.folderItemPalette.projectName.parameterOrMethod
libraryGlobal.userItemPalette.projectName.parameterOrMethod

At minimum, you need to define your object using the constructor for your project type, and then use all the required methods in the Init Methods section.

Constructors: Themes | Components | Extensions | Folder Items | User Items
Init Methods: Version | WCMS Files | Template Files | Language Strings | Editability | User Interface Hooks | Theme Hooks
Other methods for all projects
Other useful functions for all projects

At minimum, you need to define your object using the constructor for your project type, and then use all the required methods in the following section.

WCMS Init Methods

The following methods are also used to init your project:

Other WCMS Project Methods

Other useful methods and parameters:

Other Useful Functions and Variables

You may also use these other built-in functions and variables:

var toEnableOnInstall;
if ( !topLevelFolder.folderItemPaletteBkp Â
   || !topLevelFolder.folderItemPaletteBkp.demoFdrItem )
    toEnableOnInstall = 1;
else toEnableOnInstall = 0;

if ( toEnableOnInstall && toEnableOnInstall == 1 ) Â
	enableFdrItemOnInstall( 'demoFdrItem' );

» Creating an Edit Page

Since Themes are already editable via the Edit Theme Settings page, you only need supply an edit macro for Themes if you have special parameters to edit that are not included on the default Edit Theme Settings pages.

If you use our processor, the edit page itself must be set up correctly for everything to work. Moreover, the portion of the page you provide drops into an existing table provided by the Admin macros. Thus, the form fields and table structure are critical.

If you want to use your own edit macro and processor
To write your own edit macro and processor, simply provide the name of it in the object definition. Simply define your edit macro to show your custom form rather as in the examples above. Remember that you are responsible for checking security on the processor macros you write. An example:

%% command editBlog() {
	return wctlEval( 'use someOtherMacro' );
	// (or place the form directly in this command)
} %%

If your project has no editable parameters, or if you are using the built-in processor
Editing a project actually requires two macros:

Command 1: editTheme[projectName or component type] (this naming convention is not required, but is suggested to prevent conflicts in naming). This must be a Javascript command.

e.g. editdemoUserItem, editsimple, etc.

Macro 2: [Command 1 Name]Form (You can name Command 1 whatever you want, but Macro 2 must be named the same as Command 1, with the addition of the word "Form" at the end)

e.g. editdemoUserItemForm, editsimpleForm, etc. This must be a WCTL macro.

Command 1 has a prescribed format:

 1 %% command editDemoUserItem() {
 2    var obj=libraryGlobal.userItemPalette.demoUserItem;
 3    session.wrap_edit="demoUserItem";
 4    setWctlVar( "which", "demoUserItem" );
 5    setWctlVar( "formUrl", obj.plugEditHtml );
 6    setWctlVar( "abbrev", "userItems" );
 7    setWctlVar( "isEditable", obj.plugIsEditable + "" );
 8    setWctlVar( "objType", obj.plugType );
 9    var txt = obj.plugEditExplanatoryText();
10    setWctlVar( "explanatoryText", txt );
11    return wctlEval( "use editWrapperHelpSet" );
12 } %%

libraryGlobal.componentPalette.toolbar.demoToolbar;

• Theme: "theme"
• Extension: "Widgets"
• User Item: "userItems"
• Folder Item: "folderItems"
• Component - top level: "tl"
• Component - folderList: "fl"
• Component - messageList: "ml"
• Component - toolbar: "tb"

Tip: The simplest way to accomplish this is to retrieve an existing macro from one of the demo projects (the one which matches the object type of your project) and do a global search/replace for the demo project name, replacing with your project name. If your project is a component, you also need to edit the "abbrev" line manually - otherwise, you're done.

Macro 2:

<p>This top level view has no editable parameters. Â
However, you can choose another top level view using the link just above.</p>

Help references
The first thing required in Macro 2, if you have editable parameters, and you need to provide user help footnotes, are help string references. On the edit pages, following the form fields or labels, you can have anchor links leading to help footnotes on the page. These footnotes are inserted and available if they are included in the help string, which is a space-delimited list of help footnote numbers. For example, if you need help string 1 and 4, you would use this as the first line in your macro. If you don't need any help footnotes, you can omit the line altogether.

%% set helpString "1 4" %%

The second line required in Macro 2 is this:

%% set url "myMacro2Name" %%

Form fields
If you do have editable parameters, you will need to fit your form fields into an existing three-column table.

Tip: The simplest thing is to copy and paste the table row(s) for an existing form field type of the kind you want to use, and copy/paste change the variable and string names.

Here is a sample text field form and its associated one table row: Again, Â means the line has been broken here for clarity, but should not be broken in your code.

 1<tr>
 2  <td valign="top"><p>
 3    <label for="inner_fl_tableCellspacing">%% "lang( 'sortableFL', 'fl_tableCellspacing' )".jsEval Â
 4       // Folder List Table Cellspacing %%</label>
 5 </p></td>%% nop %%
 6 <td><p>
 7   <input type="hidden" name="inner_fl_tableCellspacing_conf" Â
 8      value="%% "lang( 'sortableFL', 'fl_tableCellspacing' )".jsEval %%">
 9   <input name="inner_fl_tableCellspacing" type="text" size="%% clipCols( 5 ) %%" Â
10     maxlength="4" %% if inh %%value="%% path$inner_fl_tableCellspacing %%" Â
12      %% use inheritCheck %%%% else %%value="%% path.inner_fl_tableCellspacing %%"%% endif %% Â
13       id="inner_fl_tableCellspacing"> <a href="#help12">*12</a>
14  </p></td>
15  <td valign="top" align="right" width="150"><p>
16  	%% use inheritance %% 
17  </p></td>
18</tr>%%nop%%

Textareas, checkboxes, and radio buttons are similarly constructed. Study the existing files for examples, including examples with popup color-choosers.

» Creating Set Files for Themes

Export will write a file (you can choose the name) with all the WCMS variables (everything beginning with "wrap_" or "inner_").

Importing/installing a Set file will not change image SIZES, however, unless you add two additional lines to the top of the Set file before you distribute it. Please also note that if you provide these two lines, and if a user installs your Theme in a folder, the sizes for all images on the site will change, not just the folder. Image sizes are now calculated automatically if a site is using the new button syntax, so this may not be necessary.

Some considerations:

• If you have buttons of a nonstandard size, you may want to do this so sites with old button code will get the correct button size automatically.
• If you have proportional buttons where not every button in a set is the same size, leave this out so you do set them all to the same size. The site will have to update their old button code before all their buttons will be the right sizes. You will want to note this in your ReadMe file!
• If your Theme is likely to be used in a subfolder, you may not want to set button sizes automatically because button sizes are currently set sitewide.
• If the button set you choose to go with your Theme is one of the standard button sets where all the buttons are the same size, and which is the "standard" size, setting sizes is probably unnecessary, because it is highly likely the site's previous size setting is already OK.
• Please note that not all the icon sets are exactly the same size and these same considerations apply to icons too.

IF you need to set image sizes, these two additional lines must go on line 3 of the Export file, immediately after the "pathBodyTag" line. These set the sizes for images and icons. You must set either both icons and button sizes, or neither.

For example: (all on one line, no spaces or linebreaks until after the final ~)

iconSet=16x14_18x14_10x16_16x14_19x16_35x15_16x14_11x11_12x20_19x14_18x14_8x16_16x16_16x14~
buttonSet=68x30_53x19~

i is for icons

The NnxNn values are icon sizes in a certain order, width x height. auction_discuss_indent_link_chat_new_node_outline_pathdiv_site_folder_topmsg_envelope_project

The NnxNn values are the button sizes in this order:
regularSize_smallSize

» Adding Buttons or Other Custom Images

<img src="/plugins/myProject/newCustom.jpg">

Or, you can place them in any of the standard image locations.

If you want to add an entire button set, the Plugin Server will place them in the usual /Images location for buttons. If your project is a Theme, you can have your Set file define the button set to be used with your Theme. Otherwise, you'll have to either tell your users in the ReadMe file to manually set their button directories, or set it automatically somehow when the project is enabled.

» Localization Manager

The options on that page are:

Option	site.stdLocalOn	site.stdLocalPerformOn	Files Loaded
Optimize for Localization	site.stdLocalOn == 1	site.stdLocalPerformOn is not set	webxStd-local.tpl webxStd_s_en_US.auto webxextn.tpl webxextn_s_en_US.auto
Optimize for Performance	site.stdLocalOn is not set	site.stdLocalPerform == 1	webxStd-perform.tpl webxextn.tpl webxextn_s_en_US.auto
Partial Localization	site.stdLocalOn == 1	site.stdLocalPerformOn == 1	webxStd-local.tpl webxStd_s_en_US.auto webxStd-perform.tpl webxextn.tpl webxextn_s_en_US.auto
Default Settings	site.stdLocalOn is not set	site.stdLocalPerformOn is not set	webxextn.tpl webxextn_s_en_US.auto

The purposes of these files:

File
webxextn.tpl	Always loaded. Provides extra functionality
webxextn_s_en_US.auto	Always loaded. Strings for webxextn.tpl
webxStd-local.tpl	Localized mirror of server code. Loaded when stdLocalOn == 1
webxStd_s_en_US.auto	Strings for webxStd-local.tpl. Loaded when stdLocalOn == 1 or "Enable 'std' strings" is turned on in the WCMS developer menu.
webxStd-perform.tpl	NONlocalized copy of selected performance-critical macros. Loaded when stdLocalPerformOn == 1

Localization takes place through WCJS calls to a lang() function, from which the correct language and string is retrieved. The lang() function can be found in webxLocal-lang.tpl. The user can choose a language at registration or in user preferences.

Language strings are initialized in the init_localizer() function, found in webxLocal-init.tpl. webxLocal-init.tpl can be overwritten upon upgrade, so any manual changes to that file should be made in an override file named webxLocal-init_o.tpl. Here's an example of a site supporting English and Japanese. English is the default, since it appears first in the list, so any guest, or any registered user coming to the site without a specific "user.language" property, would see English.

%% function init_localizer() {
if (!libraryGlobal.langStrs) libraryGlobal.langStrs = new Object();
// set the known languages for the current site here
langStrs.languages = [ "en_US", "jp_JP" ];
langStrs.languageNames = [ "English", "Japanese" ];
} %%

In WCJS, you would call a string like this:

lang( 'projectName', 'stringVariableName' ); // This is replacement text

%% "lang( 'projectName', 'stringVariableName' )".jsEval // This is replacement text %%

The strings for any given project are in a strings function in a separate strings file named, for example, "wx_propTB_s_en_US.auto". In this example, "en_US" is the code for US English, and "propTB" is the project name.

%%function init_propTB_s_en_US() {

if (!libraryGlobal.langStrs) langStrs = new Object();
if (!langStrs.propTB) langStrs.propTB = new Object();
if (!langStrs.propTB.en_US) langStrs.propTB.en_US = new Object();
langStrs.propTB.en_US.nameToolbar="Toolbar with Custom Button Colors";
langStrs.propTB.en_US.descrToolbar="Set your own exact button, rollover,  Â
and onclick colors.  Color settings extend to nontoolbar buttons as well.  Â
Large or small buttons.";
langStrs.propTB.en_US.editExplanatoryText="Choose button color and rollovers.";
langStrs.propTB.en_US.propToolbar="Toolbar with Proportional Buttons";
langStrs.propTB.en_US.textColor="Text Color";
langStrs.propTB.en_US.whiteText="White Text";
langStrs.propTB.en_US.blackText="Black Text";
langStrs.propTB.en_US.tb_buttonBG="Button Color";
langStrs.propTB.en_US.tb_rollover="Button Rollover Color";
langStrs.propTB.en_US.tb_onClick="Button OnClick Color";

} %%

%%function init_propTB_s_en_US_o() {

if (!libraryGlobal.langStrs) langStrs = new Object();
if (!langStrs.propTB) langStrs.propTB = new Object();
if (!langStrs.propTB.en_US) langStrs.propTB.en_US = new Object();
langStrs.propTB.en_US.propToolbar="Toolbar with Custom Buttons";

} %%

1  %% function init_propTB_s_jp_JP_o() {
2  if (!libraryGlobal.langStrs) libraryGlobal.langStrs = new Object();
3  if (!libraryGlobal.langStrs.propTB) libraryGlobal.langStrs.propTB = new Object();
4  if (!libraryGlobal.langStrs.propTB.jp_JP) libraryGlobal.langStrs.propTB.jp_JP = new Object();
5 langStrs.propTB.jp_JP.propToolbar="Toolbar with Proportional Buttons";
6 langStrs.propTB.jp_JP.textColor="Text Color";
7 langStrs.propTB.jp_JP.whiteText="White Text";
8 langStrs.propTB.jp_JP.blackText="Black Text";
9 langStrs.propTB.jp_JP.tb_buttonBG="Button Color";
10 langStrs.propTB.jp_JP.tb_rollover="Button Rollover Color";
11 langStrs.propTB.jp_JP.tb_onClick="Button OnClick Color ";
} %%

You can build this manually, or, use one of the Edit Strings pages in the Localization Manager. You can either translate using web forms or use a spreadsheet system.

If you use the Add/Edit/Delete Language page, it will edit the init_localizer() function to add the new language. You can then use the Edit Strings page to translate. If no strings file exists for the project and language, it will be created. If a strings file exists, an override file will be created. If an override file exists, the old file will be renamed before the new one is written.

Debugging Language Issues
In the WCMS developer menu is an option to enable language debugging. Doing so will place HTML comments into the source identifying which file and which string a particular bit of text was called from. We don't recommend leaving this on for production servers, as it can cause display errors and cosmetic problems due to comments inside form buttons, etc.

» Creating Reference Macros

A reference macro simply references another main macro and points to it. Rename the "real" macro with the project name prepended.

Reference macros are only required when you are editing a macro provided by the system (not a custom macro) which is not inside a folder envelope, or when you need to specifically prevent a custom macro from running outside its envelope.

An example, from LiveX:

In wx_livex_ext.tpl (which is loaded in each folder where LiveX is chosen from the menu of options):

%% macro send_message_process %%
	%% use livex_send_message_process %%	
%% endmacro %%

%% macro livex_send_message_process %%

%% set curLoc location %%
%% set loc location %%
<HTML><HEAD>

... approx 80 lines of code ...

%% endmacro %%

%% use livex_receive_message %%

» Files Needed for A Project

There is no absolutely required naming convention for any of the project files, since you can specify filenames in your project object definition, but we strongly suggest you follow our convention to avoid problems and issues with other developers' work. The filenames below are examples of our suggested convention.

Your files will generally be divided into three sets, one set which will go into the webxTemplates directory, one set which goes into the /webx/html/plugins directory, and images which go inside the various image directories. Inside /plugins, create a new directory with your project plugFileName, and put anything other than your templates and string files in there.

You will need a large and small screenshot for each project, and a readMe HTML file. Themes need at least one ".set" file. Beyond that, there are 4 basic template files for each project, not all of which are required for each type of project.

• wx_projName.auto file ("auto" file)
• wx_projName.tpl file ("template" file)
• wx_projName_projType.tpl file ("envelope" file)
• wx_projName_s_en_US.auto file ("strings" file)

Required files:

• At least one ".set" file: wx_myTheme_0.set, which goes in /webx/plugins/myTheme/
  Name any subsequent ".set" files as wx_myTheme_1.set, wx_myTheme_2.set, etc. The number of files and numeric order must match with the color definitions in the Theme init definition.
  This initial "0.set" file should match the larger life-size screenshot (not the smaller thumbnails at the right edge.)


• An Auto file: wx_myTheme.auto
  This should contain the init macro and the default strings function, plus any functions which contribute to preferences/editPreferences or styles or on the control panel, and your "default" strings function.


• A life-sized screenshot of the Theme in place, with any additional color choices lined up as smaller screenshots along the right margin. If there are any interesting or noteworthy features visible on the screenshot, you can highlight them and annotate the screenshot. See the existing examples (We did our annotations in Microsoft Powerpoint). For uniformity, we recommend taking the screenshots with the gray/blue version of the "Simple" Theme in place, but this is not required.


• A miniature thumbnail screenshot of the UNannotated larger screenshot, without the other color choices, shrunk down to 164 pixels wide.


• A "ReadMe" HTML file. Place it in the same directory as your screenshots.

• Any custom images can go in: /plugins/myTheme or in the normal image locations


• A Template file: wx_myTheme.tpl
  This should contain your edit macros, if your Theme is editable, along with any other special macros associated with your Theme.


• An Envelope file: wx_myTheme_thm.tpl
  This should contain only reference macros pointing to macros in your Template file. See the section on Reference Macros for more information.


• A Strings file: wx_myTheme_s_en_US.auto
  The full strings function for your Theme.

Required files:

• An Auto file: wx_myComponent.auto
  This should contain the init macro and the default strings function, plus any functions which contribute to preferences/editPreferences or styles or on the control panel, and your "default" strings function.


• A Template file: wx_myComponent.tpl
  This should contain your edit macros, along with any other macros associated with your Component.


• An Envelope file: wx_myComponent_compType.tpl
  (Where compType == "tb", "tl", "ml", or "fl".) This should contain only reference macros pointing to macros in your Template file. See the section on Reference Macros for more information.


• A Strings file: wx_myComponent_s_en_US.auto
  The full strings function for your Component.


• A life-sized screenshot of the Component in place. Annotate the screenshot with notations about important variable settings or color choices. See the existing examples (We did our annotations in Microsoft Powerpoint). For uniformity, we recommend taking the screenshots with the gray/blue version of the "Simple" Theme in place, but this is not required.


• A miniature thumbnail screenshot of the UNannotated larger screenshot shrunk down to 164 pixels wide.


• A "ReadMe" HTML file. Place it in the same directory as your screenshots.

• Any custom images can go in: /plugins/myComponent, or in the normal image locations

Required files:

• An Auto file: wx_myExtension.auto
  This should contain the init macro and the default strings function, plus any functions which contribute to preferences/editPreferences or styles or on the control panel, and your "default" strings function.


• A Template file: wx_myExtension.tpl
  This should contain your edit macros, along with any other macros associated with your Extension.


• A Strings file: wx_myExtension_s_en_US.auto
  The full strings function for your Extension.


• A life-sized screenshot of the Extension in place. Annotate the screenshot with notations about important variable settings or color choices. See the existing examples (We did our annotations in Microsoft Powerpoint). For uniformity, we recommend taking the screenshots with the gray/blue version of the "Simple" Theme in place, but this is not required.


• A miniature thumbnail screenshot of the UNannotated larger screenshot shrunk down to 164 pixels wide.


• A "ReadMe" HTML file. Place it in the same directory as your screenshots.

• An Envelope file: wx_myExtension_ext.tpl
  This should contain only reference macros pointing to macros in your Template file. See the section on Reference Macros for more information.


• Any custom images can go in: /plugins/myExtension, or in the normal image locations

Required files:

• An Auto file: wx_myFolderItem.auto
  This should contain all the macros for the project, except the main strings function.


• A Strings file: wx_myFolderItem_s_en_US.auto
  The full strings function for your Folder Item.


• A life-sized screenshot of the Folder Item in place. Annotate the screenshot with notations about important variable settings or color choices. See the existing examples (We did our annotations in Microsoft Powerpoint). For uniformity, we recommend taking the screenshots with the gray/blue version of the "Simple" Theme in place, but this is not required.


• A miniature thumbnail screenshot of the UNannotated larger screenshot shrunk down to 164 pixels wide.


• A "ReadMe" HTML file. Place it in the same directory as your screenshots.

• Any custom images can go in: /plugins/myFolderItem, or in the normal image locations

Required files:

• An Auto file: wx_myUserItem.auto
  This should contain all the macros for the project, except the main strings function.


• A Strings file: wx_myUserItem_s_en_US.auto
  The full strings function for your User Item.


• A life-sized screenshot of the User Item in place. Annotate the screenshot with notations about important variable settings or color choices. See the existing examples (We did our annotations in Microsoft Powerpoint). For uniformity, we recommend taking the screenshots with the gray/blue version of the "Simple" Theme in place, but this is not required.


• A miniature thumbnail screenshot of the UNannotated larger screenshot shrunk down to 164 pixels wide.


• A "ReadMe" HTML file. Place it in the same directory as your screenshots.

• Any custom images can go in: /plugins/myUserItem, or in the normal image locations

» Creating Your First Project - Step by Step

1. Create your project as you normally would, with macros in webx.tpl or a file included from there. Don't worry initially about WCMS-specific issues or localization, just get your project working as you want it to.
   
   Once you have a new working project, or an old project you want to adapt into a WCMS project, follow these easy steps to add the code to integrate it into the WCMS system. Once you've done this once or twice, it will all start to make a lot more sense to you and the next one(s) you do will go faster.


2. Or, you can start with one of the demo objects and edit it as you need to and build your project from there, that way.

Either way, reading these instructions before you start (perhaps adapting a small existing practice project first?) will show you the roadmap for where you're going before you start.

At the Developer Center are some simplified instructions for a "Quick Start" in creating your project.

Essentially it involves starting with a demo project of the same type as yours, renaming the files, and then doing a lot of search/replace to replace the project name everywhere it appears. Once you've done that, it's just a matter of turning the right options on and off in the init. Unless you're doing something unusual, most of the defaults are fine.

» Creating a Theme

1. Choose a name, something like myStuff. Filenames can get kind of long, so keeping the base name short is a good idea. Less than about 10 characters is ideal. In this example "myStuff" is the name of the theme.
2. When you create your Theme settings, be sure to turn on the tabular or sortable folder item and the tabular message view components and set matching colors for those as well so the colors will export. You can use any of the background images in /plugins/bgs, or create your own custom images.
3. Put any custom images into a folder called "myStuff" inside /plugins.
4. Create the screenshots myStuffL.gif and myStuff.gif, and the readme file readme.html. Place these in your "myStuff" folder.
5. When you have your theme settings the way you want, use the Export function on the Theme Settings page to export a Theme set file.
6. Name your set file: wx_myStuff_0.set. If you have other color variations on the same theme, name the other files wx_myStuff_1.set, wx_myStuff_2.set, etc. for as many variations as you have.
7. Open the file wx_zdemoTheme.tpl and rename it "wx_myStuff.tpl".
8. Use search and replace to replace all instances of the string "zdemoTheme" with "myStuff". Also replace all instances of the string "demoTheme" with "myStuff". (The Demo Theme object name is sometimes is prefixed with the "z" to make it alphabetize to the end of the selection list).
9. Open the example file wx_demoTheme_s_en_US.auto and rename it "wx_myStuff_s_en_US.auto". Do a search-and-replace for all instances of "demoTheme" and replace with "myStuff". Edit the "themeName", "explanText", and "shortDescr" strings as necessary to provide the actual name of the theme as you would like it to appear in the user interface, and a short description of what the theme does. The other strings go specifically with the Demo Theme and can be deleted unless you want to reuse them. (If you already have a strings file for your project you'll have to combine all the strings into one file, and make sure that file is the one named in plugSetWcmsFiles() below.)
10. Edit the init function for the new theme (first one in the wx_myStuff.auto file) as follows.
    1. If you already have an init_myStuff() function elsewhere, feel free to rename this to init_myStuff_wcms() or something similar.
    2. First, find the function ShortTheme().
    3. These two parameters are each arrays holding the list of set files you created in step 6. Parameter 1 is an array of the names of the color options for the user interface, and the second is an array of the actual names of the file.
    4. Next, find the method plugSetVersion().
    5. Replace the two parameters with the version number of the plugin and date of the current release, respectively. The date can be in whatever format you wish.
    6. Next, find the method plugSetWcmsFiles().
    7. Replace the 1st parameter "demo" with "myStuff".
    8. Replace the 2nd parameter "demo.gif" with "myStuff.gif.
    9. Replace the 3rd and 4th parameters with the width and height, respectively, of myStuff_sm.gif.
    10. Replace the 5th parameter "demoL.gif" with "myStuffL.gif.
    11. Replace the 6th and 7th parameters with the width and height, respectively, of myStuff_lg.gif.
    12. Replace, if necessary, the 8th parameter with the URL where users may obtain support for this project (required).
    13. Next, find the method plugsetTplfiles().
    14. The first parameter should already read "wx_myStuff.auto".
    15. The 2nd and 3rd parameters can be replaced with "" unless you have special functions above and beyond the theme settings, which need to be included with your project. The defaults are OK if you do have special functions.
    16. The next method, plugSetStringProps(), should be OK as is after your search/replace.
    17. Find the next method, plugSetEditables().
    18. Set the 1st parameter to 1 if you will have a special edit form for your theme, or 0 if the theme has no editable parameters.
    19. The 2nd and 3rd parameters are necessary only if the first parameter is set to 1. If so, the defaults are OK. If not, replace them with "".
    20. The next method is plugSetInterfaceHooks(). This method is optional if you don't have any arguments for it.
    21. If your theme needs to place HTML on the user preferences page in the misc section, put the names of your WCJS preferences functions or commands (one for edit prefs, one for edited prefs) in as the 1st and 2nd parameters, without quotes around the names. Place these functions/commands in the wx_myStuff.auto file. These functions/commands should only call another macro or function inside wx_myStuff.tpl, similar to the way the stylesheet functions/macros work in the next step. You can use demoFIEditPrefs() and demoFIEditedPrefs() functions from wx_demoFdrItem.auto file as examples of the function for wx_myStuff.tpl. If your theme has no need to do this, replace both arguments with "".
    22. If your theme needs to add a custom class to the stylesheet, put the name of your WCJS style command or function in as the 3rd parameter. You can copy/edit the command demoUIStyleJS and the macro demoUIStyle from wx_demoFdrItem.auto file if you wish. Place demoUIStyleJS in wx_myStuff.auto and demoUIStyle in wx_myStuff.tpl.tpl. Edit the names of them to myStuffStyleJS and myStuffStyle and include your own stylesheet code. myStuffStyle needs to set/return the WCTL variable "body". If not, replace with "".
    23. If your theme needs to add a link (or links) in the control panel, create a WCJS command or function with the link and add the name of the command/function (not quoted) as the 4th, 5th, 6th and/or 7th parameter, depending on where you want the link(s) to appear.
        4th: Services section.
        5th: Customizing section.
        6th: User section.
        7th: Site section.
        This command/function must live in wx_myStuff.auto file. You can copy/edit the demoExtControlPanelLink() in wx_demoExt.auto if you wish. The last two parameters allow you to put HTML in the sysop-only section of user preferences, in the same way as the others work.
    24. If your theme needs to add HTML on the user preferences page in the sysop section put the name of your WCJS style command or function in as the 8th and 9th parameters (edit prefs, edited prefs). If your theme needs to add a HTML on the user preferences page in the profile section put the name of your WCJS style command or function in as the 10th and 11th parameters (edit prefs, edited prefs). Both of these work the same as all the others in this function.
    25. The last method is plugSetThemeHooks(). This method is optional if you don't have any arguments for it. If your theme needs to place a link or call a macro in one of the Theme cells (top, bottom, nav, multi-purpose), create a WCTL macro (or WCJS command without any parameters) containing the link or the call. Your component can merely place itself in the optional items menu for the indicated cell to give the sysop an option of where to place the call or link, or it can select itself as the default location. These parameters work in pairs. Parameters 1 and 2 should contain, respectively, the name of the macro you want to be called in the theme top cell (in quotes), and 0 if it should merely appear in the menu, or 1 if it should enable itself. Parameters 3 and 4 contain the same thing for the bottom cell, parameters 5 and 6 contain the same thing for the nav cell, and parameters 7 and 8 contain the same thing for the multi-purpose cell. Parameters 9 and 10, and 11 and 12 are for the content cell top, and content cell bottom, respectively. Look at "macro whichLiveX" in wx_livex.tpl for an example of a macro which can be called in the top cell, bottom cell, nav cell or multi-purpose cell, and which is formatted differently depending on where it's called. This macro should go in your wx_myStuff.tpl file.
11. Look at the bottom of the init function. If you are using any of the arguments for plugSetThemeHooks, you will need two lines like this for each cell where you want your macro to appear in the menu of choices:

    For the nav cell:

    if ( !libraryGlobal.optionalItemsPalette.nav ) libraryGlobal.optionalItemsPalette.nav = new Object();
    libraryGlobal.optionalItemsPalette.nav.myStuff = myStuffArray;
    

    Comment out, or remove, the lines which are not needed. For an example of an extension using four positions, see the init function in wx_livex.auto
12. If you have no special Theme functions and no editable parameters, skip to step 18 and test, and if all is well, you're done.
13. If you have editable parameters, open the example file "wx_zdemoTheme.tpl" and copy the JavaScript command "editDemoTheme" and WCTL macro "editDemoThemeForm". Open your "wx_myStuff.tpl", and paste the copied command and macro into the top of the file.
14. Select the code you just pasted in, and use search-and-replace on the selected text to replace all instances of the string "demoTheme" with "myStuff". This will work as-is, for now. After you're sure everything is working you can go back later and create an edit form for your editable parameters.
15. If you have defined an envelope filename in parameter 3 of plugSetTplFiles, create a file named wx_myStuff_thm.tpl (or whatever filename matches what you defined). If defined in plugsetTplfiles, this file must exist (but is not required to contain any code - a simple "this file intentionally left empty" comment will suffice, although simply removing it from plugSetTplFiles is probably simpler). We'll deal with the contents of this file later.
16. Place the newly created folder "myStuff", containing the screenshots and the readme file and our set files, in the /plugins directory of your Web Crossing server.
17. Copy the files you need, depending on the options you've chosen (possibly up to four files: wx_myStuff.auto, wx_myStuff.tpl, wx_myStuff_thm.tpl, and wx_myStuff_s_en_US.auto) to the /webxTemplates directory of your Web Crossing server. Place any custom images where they need to go.
18. If you used any method to place any of your files except Web Crossing's built in FTP or web file editor, Resynch the server to the filesystem using the link in the Control Panel near the Reset Cache link. Reset the cache in the control panel and test. Make sure the Theme appears in the control panel > Choose a Theme page, and that you can choose it and it imports correctly and appears as it should. If you have no special Theme functions and no editable parameters, and all is well, you're done and can skip the rest of these instructions.
19. If everything works OK, you're ready to localize. Go to your macros, and select out the first text string in your wx_myStuff.tpl file (or your wx_myStuff.auto file, if there are any text strings in it). Add another line to your strings function for the string that needs replacing. The easiest thing to do is to copy an existing line and then edit it. If the text you want to localize is, "Link to My Stuff", the line would look something like this:

    langStrs.myStuff.en_US.linkToMyStuff="Link to My Stuff";

    You can call your string anything you want, but naming it something obvious makes it easier to keep track of later. Just be careful not to duplicate string names within a function.
20. Then, each place where "Link to My Stuff" appears in your macro, replace it with this for WCTL:

    %% "lang".jscall( "myStuff", "linkToMyStuff" ) // Link to My Stuff %%

    or this, for WCJS:

    lang( 'myStuff', 'linkToMyStuff' ); // Link to My Stuff

    The comments are not necessary but make your code a lot easier to keep track of later.
21. Do the same for each string in your project.
22. Reset the cache and test both your project itself, and the control panel "Choose a Theme" page to make sure the text appears properly there, too. Any missing strings will be replaced by "***" and reported in the logLangErrors.log file in your root Web Crossing directory, which is readable directly from the /server directory, or via the Read Logs command in the WCMS developer menu.
23. Next, to make sure that your Theme's special functions show up in the folders in which the Theme is selected, but not in other locations, you may need to create some reference macros. If you used any of the standard macros in webxStd-local or webxextn.tpl, you will need to use reference macros. Otherwise, you can probably try it without reference macros and see if it works OK without. If functions or macros are showing up in folders where they are not defined, you'll need to convert those to reference macros. The reference macro file will go inside the folder macro controlling the folder where the component is enabled. So you will put your "real" macro names on the reference macros in the wx_myStuff_thm.tpl file, and change the names on your macros in your wx_myStuff.tpl file.
    1. If you have these two macros in your wx_myStuff.tpl file - myStuffDisplay and myStuff Process - change the names in wx_myStuff.tpl to (respectively) "myStuff_myStuffDisplay" and "myStuff_myStuffProcess".
    2. Create three new reference macros, with the original short names, in wx_myStuff_[abbrev].tpl:

       %% macro myStuffDisplay %%
           %% use myStuff_myStuffDisplay %%
       %% endmacro %%
       
       %% macro myStuffProcess %%
           %% use myStuff_myStuffProcess %%
       %% endmacro %%
       

    3. Then, back in wx_myStuff.tpl, change all %% use ... %% statements and form tags or link URLs which call those three macros, to the longer names.

       %% use myStuff_myStuffDisplay %%
       <form action="myStuff_myStuffProcess" method="post">

24. Retest once more, and make sure that your Theme works in a subfolder when it is turned off at the top level, and doesn't appear where it's not supposed to.

» Creating a Component

1. Choose a name, something like myStuff. Filenames can get kind of long, so keeping the base name short is a good idea. Less than 10 characters is ideal. In this example "myStuff" is the name of the component.
2. Rename your existing template file, if any, to "wx_myStuff.tpl". Note that case matters.
3. Save the example file "wx_demoComp.auto" as "wx_myStuff.auto".
4. Use search and replace to replace all instances of the string "demoComp" in this file with "myStuff".
5. If your component is not a toolbar, find the init_myStuff function and edit all instances of "toolbar" to:

   Component Type
   Top Level	topLevel
   Folder List	folderList
   Message List	messageList
   Toolbar	(OK as is)

6. Create the screenshots myStuff_lg.gif and myStuff_sm.gif, and the readme file myStuff_readme.html. Place these in a folder called "myStuff".
7. Open the example file wx_demoComp_s_en_US.auto and rename it "wx_myStuff_s_en_US.auto". Do a search-and-replace for all instances of "demoComp" and replace with "myStuff". Edit the "nameComp", "editExplanatoryText", and "descrComp" strings as necessary to provide the actual name of the theme as you would like it to appear in the user interface, and a short description of what the theme does. The other strings go specifically with the Demo Component and can be deleted unless you want to reuse them. (If you already have a strings file for your project you'll have to combine all the strings into one file, and make sure that file is the one named in plugSetWcmsFiles() below.)
8. Edit the init function for the new component (first one in the wx_myStuff.auto file) as follows:
   1. If you already have an init_myStuff() function elsewhere, feel free to rename this to init_myStuff_wcms() or something similar.
   2. First, find the function ShortComponent(). There is only one parameter, the component type. Use "topLevel", "messageView", "folderView", or "toolbar", as you did just above in step 5.
   3. Next, find the method plugSetVersion().
   4. Replace the two parameters with the version number of the plugin and date of the current release, respectively. The date can be in whatever format you wish.
   5. Next, find the method plugSetWcmsFiles().
   6. Replace the 1st parameter "demo" with "myStuff".
   7. Replace the 2nd parameter "demo.gif" with "myStuff_sm.gif.
   8. Replace the 3rd and 4th parameters with the width and height, respectively, of myStuff_sm.gif.
   9. Replace the 5th parameter "demoL.gif" with "myStuff_lg.gif.
   10. Replace the 6th and 7th parameters with the width and height, respectively, of myStuff_lg.gif.
   11. Replace the 8th parameter with the URL where users may obtain support for this project (required).
   12. Replace the last parameter "readme.html" with myStuff_readme.html if you have a readme file for your project. Otherwise, replace with "".
   13. Next, find the method plugSetTplfiles().
   14. The first parameter should already read "wx_myStuff.auto".
   15. The 2nd parameter is the name of your template file, and should be OK as is after your search/replace.
   16. The default name for the 3rd parameter is OK.
   17. The next method, plugSetStringProps(), should be OK as is after your search/replace.
   18. Find the next method, plugSetEditables().
   19. Set the 1st parameter to 1 if you will have editable properties for your project.
   20. The 2nd and 3rd parameters are necessary only if the first parameter is set to 1. If so, the defaults are OK. If not, replace them with "".
   21. The next method is plugSetInterfaceHooks(). This method is optional if you don't have any arguments for it. If your theme needs to place HTML on the user preferences page in the misc section, put the names of your WCJS preferences functions or commands (one for edit prefs, one for edited prefs) in as the 1st and 2nd parameters, without quotes around the names. Place these functions/commands in the wx_myStuff.auto file. These functions/commands should only call another macro or function inside wx_myStuff.tpl, similar to the way the stylesheet functions/macros work in the next step. You can use demoFIEditPrefs() and demoFIEditedPrefs() functions from wx_demoFdrItem.auto file as examples of the function for wx_myStuff.tpl. If your theme has no need to do this, replace both arguments with "".
   22. If your theme needs to add a custom class to the stylesheet, put the name of your WCJS style command or function in as the 3rd parameter. You can copy/edit the command demoUIStyleJS and the macro demoUIStyle from wx_demoFdrItem.auto file if you wish. Place demoUIStyleJS in wx_myStuff.auto and demoUIStyle in wx_myStuff.tpl.tpl. Edit the names of them to myStuffStyleJS and myStuffStyle and include your own stylesheet code. myStuffStyle needs to set/return the WCTL variable "body". If not, replace with "".
   23. If your theme needs to add a link (or links) in the control panel, create a WCJS command or function with the link and add the name of the command/function (not quoted) as the 4th, 5th, 6th and/or 7th parameter, depending on where you want the link(s) to appear.
       4th: Services section.
       5th: Customizing section.
       6th: User section.
       7th: Site section.
       This command/function must live in wx_myStuff.auto file. You can copy/edit the demoExtControlPanelLink() in wx_demoExt.auto if you wish. The last two parameters allow you to put HTML in the sysop-only section of user preferences, in the same way as the others work.
   24. If your theme needs to add a HTML on the user preferences page in the sysop section put the name of your WCJS style command or function in as the 8th and 9th parameters (edit prefs, edited prefs). If your theme needs to add a HTML on the user preferences page in the profile section put the name of your WCJS style command or function in as the 10th and 11th parameters (edit prefs, edited prefs). Both of these work the same as all the others in this function.
   25. The last method is plugSetThemeHooks(). This method is optional if you don't have any arguments for it. If your project needs to place a link or call a macro in one of the Theme cells (top, bottom, nav, multi-purpose), create a WCTL macro (or WCJS command without any parameters) containing the link or the call. Your component can merely place itself in the optional items menu for the indicated cell to give the sysop an option of where to place the call or link, or it can select itself as the default location. These parameters work in pairs. Parameters 1 and 2 should contain, respectively, the name of the macro you want to be called in the theme top cell (in quotes), and 0 if it should merely appear in the menu, or 1 if it should enable itself. Parameters 3 and 4 contain the same thing for the bottom cell, parameters 5 and 6 contain the same thing for the nav cell, and parameters 7 and 8 contain the same thing for the multi-purpose cell. Parameters 9 and 10, and 11 and 12 are for the content cell top, and content cell bottom, respectively. Look at "macro whichLiveX" in wx_livex.tpl for an example of a macro which can be called in the top cell, bottom cell, nav cell or multi-purpose cell, and which is formatted differently depending on where it's called. This macro should go in your wx_myStuff.tpl file.


9. Look at the bottom of the init function. If you are using any of the arguments for plugSetThemeHooks, you will need two lines like this for each cell where you want your macro to appear in the menu of choices:

   For the nav cell:

   if ( !libraryGlobal.optionalItemsPalette.nav ) libraryGlobal.optionalItemsPalette.nav = new Object();
   libraryGlobal.optionalItemsPalette.nav.myStuff = myStuffArray;
   

   Comment out, or remove, the lines which are not needed. For an example of an extension using all four positions, see the init function in wx_livex.auto
10. In the init_myStuff_default_strings function edit the "nameComp", "descrComp", and "editExplanatoryText" strings as necessary to provide the actual name of the component as you would like it to appear in the user interface, a short description of what the component does, and additional text on operation for the edit page. The last two can be the same, if you like.
11. Open the example file "wx_demoComp.tpl" and copy the JavaScript command "editWrapperdemoComp" and WCTL macro "editWrapperdemoCompForm". Open your "wx_myStuff.tpl", which contains your existing code, and paste the copied command and macro into the top of the file.
12. Select the code you just pasted in, and use search-and-replace on the selected text to replace all instances of the string "demoExt" with "myStuff". Then in the line which sets the WCTL variable "abbrev," change "tb" to one of the following:

    Component Type
    Top Level	tl
    Folder List	fl
    Message List	ml
    Toolbar	(OK as is)

    This will work as-is, for a component without any editable parameters. After you're sure everything is working you can go back later and create an edit form if you have sysop-editable parameters.
13. Using the abbreviation code from the previous step, create files named wx_myStuff_[abbrev].tpl and wx_myStuff_s_en_US.auto. For example, wx_myStuff_tb.tpl, or wx_myStuff_fl.tpl. These files must exist but at present are not required to contain any code - a simple "this file intentionally left empty" comment will suffice. We'll create the contents for the strings file later, after we're sure everything works, and deal with the other file in step 22.
14. Place the newly created folder "myStuff", containing the screenshots and the readme file, in the /plugins directory of your Web Crossing server.
15. Copy the four files wx_myStuff.auto, wx_myStuff.tpl, wx_myStuff_[abbrev].tpl, and wx_myStuff_s_en_US.auto to the /webxTemplates directory of your Web Crossing server. Place any custom images where they need to go.
16. If you used any method to place any of your files except Web Crossing's built in FTP or web file editor, Resynch the server to the filesystem using the link in the Control Panel near the Reset Cache link. Reset the cache in the control panel and test. Make sure the component appears in the control panel > Choose a Component page, and that you can choose it and it appears as it should.
17. If everything works OK, you're ready to localize. Go to your macros, and select out the first text string in your wx_myStuff.tpl file (or your wx_myStuff.auto file, if there are any text strings in it). Add another line to your strings function in wx_myStuff_s_en_US.auto for each string that needs replacing. The easiest thing to do is to copy an existing line and then edit it. If the text you want to localize is, "Link to My Stuff", the line would look something like this:

    langStrs.myStuff.en_US.linkToMyStuff="Link to My Stuff";

    You can call your string anything you want, but naming it something obvious makes it easier to keep track of later. Just be careful not to duplicate string names within a function.
18. Then, each place where "Link to My Stuff" appears in your macro, replace it with this for WCTL:

    %% "lang".jscall( "myStuff", "linkToMyStuff" ) // Link to My Stuff %%

    or this, for WCJS:

    lang( 'myStuff', 'linkToMyStuff' ); // Link to My Stuff

    The comments are not necessary but make your code a lot easier to keep track of later.
19. Do the same for each string in your project.
20. Reset the cache and test both your project itself, and the control panel "Choose a Theme" page to make sure the text appears properly there, too. Any missing strings will be replaced by "***" and reported in the logLangErrors.log file in your Web Crossing root directory, which is readable directly from the /server directory, or via the Read Logs command in the WCMS developer menu.
21. Next, to make sure that your components show up in the folders in which they're selected, but not in other locations, you'll need to create some reference macros. The reference macro file will go inside the folder macro controlling the folder where the component is enabled. So you will put your "real" macro names on the reference macros in the wx_myStuff_[abbrev].tpl file, and change the names on your macros in your wx_myStuff.tpl file.
    1. If you have these three macros in your wx_myStuff.tpl file - myStuffDisplay, myStuff Process, and folderListItem - change the names in wx_myStuff.tpl to (respectively) "myStuff_myStuffDisplay", "myStuff_myStuffProcess" and "myStuff_folderListItem".
    2. Create three new reference macros, with the original short names, in wx_myStuff_[abbrev].tpl:

       %% macro myStuffDisplay %%
           %% use myStuff_myStuffDisplay %%
       %% endmacro %%
       
       %% macro myStuffProcess %%
           %% use myStuff_myStuffProcess %%
       %% endmacro %%
       
       %% macro folderListItem %%
           %% use myStuff_folderListItem %%
       %% endmacro %%
       

    3. Then, back in wx_myStuff.tpl, change all %% use ... %% statements and form tags or link URLs which call those three macros, to the longer names.

       %% use myStuff_myStuffDisplay %%
       <form action="myStuff_myStuffProcess" method="post">

22. Retest once more, and make sure that your project works in a subfolder when it is turned off at the top level, and doesn't appear where it's not supposed to.

» Creating an Extension

1. Choose a name, something like myStuff. Filenames can get kind of long, so keeping the base name short is a good idea. 10 characters or shorter is ideal. In this example "myStuff" is the name of the extension.
2. Rename the existing template file to "wx_myStuff.tpl". Note that case matters.
3. Copy the example file "wx_demoExt.auto" and save it as "wx_myStuff.auto".
4. Use search and replace to replace all instances of the string "demoExt" in this file with "myStuff".
5. Create the screenshots myStuff_lg.gif and myStuff_sm.gif, and the readme file myStuff_readme.html. Place these in a folder called "myStuff".
6. Open the example file wx_demoExt_s_en_US.auto and rename it "wx_myStuff_s_en_US.auto". Do a search-and-replace for all instances of "demoExt" and replace with "myStuff". Edit the "extensionName", "editExplanatoryText", and "shortDescr" strings as necessary to provide the actual name of the extension as you would like it to appear in the user interface, and a short description of what the extension does. (If you already have a strings file for your project you'll have to combine all the strings into one file, and make sure that file is the one named in plugSetWcmsFiles() below.)
7. Edit the init function for the new extension (first one in the wx_myStuff.auto file) as follows:
   1. If you already have an init_myStuff() function elsewhere, feel free to rename this to init_myStuff_wcms() or something similar.
   2. First, find the function ShortExtension(). If you want your extension only to be turned on and off at the top level, insert a single parameter: "1". Otherwise, leave it blank - no parameters.
   3. Next, find the method plugSetVersion().
   4. Replace the two parameters with the version number of the plugin and date of the current release, respectively. The date can be in whatever format you wish.
   5. Next, find the method plugSetWcmsFiles().
   6. Replace the 1st parameter "demo" with "myStuff".
   7. Replace the 2nd parameter "demo.gif" with "myStuff_sm.gif.
   8. Replace the 3rd and 4th parameters with the width and height, respectively, of myStuff_sm.gif.
   9. Replace the 5th parameter "demoL.gif" with "myStuff_lg.gif.
   10. Replace the 6th and 7th parameters with the width and height, respectively, of myStuff_lg.gif.
   11. Replace the 8th parameter with the URL where users may obtain support for this project (required).
   12. Replace the last parameter "readme.html" with myStuff_readme.html if you have a readme file for your project. Otherwise, replace with "".
   13. Next, find the method plugSetTplfiles().
   14. The first parameter should already read "wx_myStuff.auto".
   15. The 2nd parameter is the name of your template file, and should be OK as is after your search/replace.
   16. The 3rd parameter is optional if your project will run at the top level, like a sysop control panel extension. If your project needs to be run in a subfolder and will be on in some locations and off in others, you need to specify an envelope file - the third parameter. If you need this, the default name is OK. If not, remove it or use "".
   17. The next method, plugSetStringProps(), should be OK as is after your search/replace.
   18. Find the next method, plugSetEditables().
   19. Set the 1st parameter to 1 if you will have editable properties for your project.
   20. The 2nd and 3rd parameters are necessary whether or not the first parameter is set to 1, and the defaults should be OK.
   21. The next method is plugSetInterfaceHooks(). This method is optional if you don't have any arguments for it.
   22. If your extension needs to place HTML on the user preferences page in the misc section, put the names of your WCJS preferences functions or commands (one for edit prefs, one for edited prefs) in as the 1st and 2nd parameters, without quotes around the names. Place these functions/commands in the wx_myStuff.auto file. These functions/commands should only call another macro or function inside wx_myStuff.tpl, similar to the way the stylesheet functions/macros work in the next step. You can use demoFIEditPrefs() and demoFIEditedPrefs() functions from wx_demoFdrItem.auto file as examples of the function for wx_myStuff.tpl. If your theme has no need to do this, replace both arguments with "".
   23. If your extension needs to add a custom class to the stylesheet, put the name of your WCJS style command or function in as the 3rd parameter. You can copy/edit the command demoUIStyleJS and the macro demoUIStyle from wx_demoFdrItem.auto file if you wish. Place demoUIStyleJS in wx_myStuff.auto and demoUIStyle in wx_myStuff.tpl.tpl. Edit the names of them to myStuffStyleJS and myStuffStyle and include your own stylesheet code. myStuffStyle needs to set/return the WCTL variable "body". If not, replace with "".
   24. If your extension needs to add a link (or links) in the control panel, create a WCJS command or function with the link and add the name of the command/function (not quoted) as the 4th, 5th, 6th and/or 7th parameter, depending on where you want the link(s) to appear.
       4th: Services section.
       5th: Customizing section.
       6th: User section.
       7th: Site section.
       This command/function must live in wx_myStuff.auto file. You can copy/edit the demoExtControlPanelLink() in wx_demoExt.auto if you wish. The last two parameters allow you to put HTML in the sysop-only section of user preferences, in the same way as the others work.
   25. If your extension needs to add a HTML on the user preferences page in the sysop section put the name of your WCJS style command or function in as the 8th and 9th parameters (edit prefs, edited prefs). If your extension needs to add a HTML on the user preferences page in the profile section put the name of your WCJS style command or function in as the 10th and 11th parameters (edit prefs, edited prefs). Both of these work the same as all the others in this function.
   26. The last method is plugSetThemeHooks(). This method is optional if you don't have any arguments for it. If your project needs to place a link or call a macro in one of the Theme cells (top, bottom, nav, multi-purpose, content top, content bottom), create a WCTL macro (or WCJS command without any parameters) containing the link or the call. Your component can merely place itself in the optional items menu for the indicated cell to give the sysop an option of where to place the call or link, or it can select itself as the default location. These parameters work in pairs. Parameters 1 and 2 should contain, respectively, the name of the macro you want to be called in the theme top cell (in quotes), and 0 if it should merely appear in the menu, or 1 if it should enable itself. Parameters 3 and 4 contain the same thing for the bottom cell, parameters 5 and 6 contain the same thing for the nav cell, and parameters 7 and 8 contain the same thing for the multi-purpose cell. Parameters 9 and 10, and 11 and 12 are for the content cell top, and content cell bottom, respectively. Look at "macro whichLiveX" in wx_livex.tpl for an example of a macro which can be called in the top cell, bottom cell, nav cell or multi-purpose cell, and which is formatted differently depending on where it's called. This macro should go in your wx_myStuff.tpl file.


8. Look at the bottom of the init function. If you are using any of the arguments for plugSetThemeHooks, you will need two lines like this for each cell where you want your macro to appear in the menu of choices:

   For the nav cell:

   if ( !libraryGlobal.optionalItemsPalette.nav ) libraryGlobal.optionalItemsPalette.nav = new Object();
   libraryGlobal.optionalItemsPalette.nav.myStuff = myStuffArray;
   

   Comment out, or remove, the lines which are not needed. For an example of an extension using all four positions, see the init function in wx_livex.auto
9. In the init_myStuff_default_strings function edit the "extensionName", "shortDescr", and "editExplanatoryText" strings as necessary to provide the actual name of the extension as you would like it to appear in the user interface, a short description of what the extension does, and additional text on operation for the edit page. The last two can be the same, if you like.
10. Open the example file "wx_demoExt.tpl" and copy the JavaScript command "editWrapperdemoExt" and WCTL macro "editWrapperdemoExtForm". Open your "wx_myStuff.tpl", which contains your existing code, and paste the copied command and macro into the top of the file.
11. Select the code you just pasted in, and use search-and-replace on the selected text to replace all instances of the string "demoExt" with "myStuff". This will work as-is, for an extension without any editable parameters. After you're sure everything is working, you can go back later and create an edit form if you have sysop-editable parameters.
12. Create files named wx_myStuff_ext.tpl and wx_myStuff_s_en_US.auto. These files must exist but at present are not required to contain any code - a simple "this file intentionally left empty" comment will suffice. We'll create the contents for the strings file later, after we're sure everything works, and deal with the other file in step 21.
13. Place the newly created folder "myStuff", containing the screenshots and the readme file, in the /plugins directory of your Web Crossing server.
14. Copy the four files wx_myStuff.auto, wx_myStuff.tpl, wx_myStuff_ext.tpl, and wx_myStuff_s_en_US.auto to the /webxTemplates directory of your Web Crossing server. Place any custom images where they need to go.
15. If you used any method to place any of your files except Web Crossing's built in FTP or web file editor, Resynch the server to the filesystem using the link in the Control Panel near the Reset Cache link. Reset the cache in the control panel and test. Make sure the extension appears in the control panel > Choose an Extension page, and that you can choose it and it appears as it should, where it should.
16. If everything works OK, you're ready to localize. In the file wx_myStuff_s_en_US.auto, do a global search/replace for all instances of "demoExt" and replace with "myStuff" if you haven't already done so.
17. Then go to your macros, and select out the first text string in your wx_myStuff.tpl file (or your wx_myStuff.auto file, if there are any text strings in it). Add another line to your strings function for the string that needs replacing. The easiest thing to do is to copy an existing line and then edit it. If the text you want to localize is, "Link to My Stuff", the line would look something like this:

    langStrs.myStuff.en_US.linkToMyStuff="Link to My Stuff";

    You can call your string anything you want, but naming it something obvious makes it easier to keep track of later. Just be careful not to duplicate string names within a function.
18. Then, each place where "Link to My Stuff" appears in your macro, replace it with this for WCTL:

    %% "lang".jscall( "myStuff", "linkToMyStuff" ) // Link to My Stuff %%

    or this, for WCJS:

    lang( 'myStuff', 'linkToMyStuff' ); // Link to My Stuff

    The comments are not necessary but make your code a lot easier to keep track of later.
19. Do the same for each string in your project.
20. Reset the cache and test both your project itself, and the control panel "Choose an Extension" page to make sure the text appears properly there, too. Any missing strings will be replaced by "***" and reported in the logLangErrors.log file in your Web Crossing root directory, which is readable directly from the /server directory, or via the Read Logs command in the WCMS developer menu.
21. If your extension is something like a sysop utility, or something which is always available sitewide, you won't need a wx_myStuff_ext.tpl file. However, if your extension contains any macros distributed in webxextn.tpl or webxStd-local.tpl, and is something which might only be available in certain folders on your site, you'll need to create some reference macros. If you're not sure if you need reference macros or not, try it without and test. The reference macro file will go inside the folder macro controlling the folder where the extension is enabled. So you will put your "real" macro names on the reference macros in the wx_myStuff_ext.tpl file, and change the names on your macros in your wx_myStuff.tpl file.
    1. If you have these three macros in your wx_myStuff.tpl file - myStuffDisplay, myStuff Process, and folderListItem - change the names in wx_myStuff.tpl to (respectively) "myStuff_myStuffDisplay", "myStuff_myStuffProcess" and "myStuff_folderListItem".
    2. Create three new reference macros, with the original short names, in wx_myStuff_ext.tpl:

       %% macro myStuffDisplay %%
           %% use myStuff_myStuffDisplay %%
       %% endmacro %%
       
       %% macro myStuffProcess %%
           %% use myStuff_myStuffProcess %%
       %% endmacro %%
       
       %% macro folderListItem %%
           %% use myStuff_folderListItem %%
       %% endmacro %%
       

    3. Then, back in wx_myStuff.tpl, change all %% use ... %% statements and form tags or link URLs which call those three macros, to the longer names.

       %% use myStuff_myStuffDisplay %%
       <form action="myStuff_myStuffProcess" method="post">

22. Retest once more, and make sure that your project works in a subfolder when it is turned off at the top level, and doesn't appear where it's not supposed to.

» Creating a Folder Item

1. Choose a name, something like myStuff. Filenames can get kind of long, so keeping the base name short is a good idea. Ten characters or less is best. In this example "myStuff" is the name of the folder item.
2. Rename your existing template file "wx_myStuff.auto". Note that case matters.
3. Copy the function init_demoFdrItem() from the wx_demoFdrItem.auto file to the top of your wx_myStuff.auto file.
4. In the text you just pasted, use a case INsensitive search and replace to replace all instances of the string "demoFdrItem" with "myStuff".
5. Create the screenshots myStuff_lg.gif and myStuff_sm.gif, and the readme file myStuff_readme.html. Place these in a folder called "myStuff".
6. Open the example file wx_demoFdrItem_s_en_US.auto and rename it "wx_myStuff_s_en_US.auto". Do a search-and-replace for all instances of "demoFdrItem" and replace with "myStuff". Edit the "projName", "shortDescr", and "explanatoryText" strings as necessary to provide the actual name of the folder item as you would like it to appear in the user interface, a short description of what the folder item does, and additional text on operation for the edit page. The last two can be the same, if you like. Edit the "addmyStuff" string to return the name of your folder item as it should appear in the "Add: " row of the text toolbar, and edit the string "addmyStuffAlt" to return the name of your folder item as it should appear as an alt tag on your "Add ..." toolbar button. (If you already have a strings file for your project you'll have to combine all the strings into one file, and make sure that file is the one named in plugSetWcmsFiles() below.) The last two strings can be deleted unless you want to reuse them.
7. Create an icon for your project, called "myStuffIcon.gif", and button sets for each set you want to support - we can provide you with original button files if you need them. (If you don't support all the sets we ship with, be sure to note this in the ReadMe file!). Name your button "addmyStuff.gif". For now, place a copy of your icon in the icon directory you're using and a copy of the button in the button directory you're using. (If you wish, you can copy the icon to each of the icon directories and the button to each of the button directories. Note that the i4 directory is designed for use on a dark background, so your i4 icon should support that.)
8. In order for your icon to actually be used for your project, you need to add this line of WCTL to the "add" processing for your folder item:

   %% setPathIconFilename( "demoFdrItem.gif" ) %%

   , replacing demoFdrItem.gif with the actual name of your icon.
9. Open the example file "wx_demoFdrItem.auto" and copy the three JavaScript functions "sayNodemoFdrItem", "sayNoPagedemoFdrItem", and "folderListBeforedemoFdrItem" into your "wx_myStuff.auto" file, and do a search/replace to replace demoFdrItem with myStuff.
10. Edit the init function for the new folder item (first one in the wx_myStuff.auto file) as follows:
    1. If you already have an init_myStuff() function elsewhere, feel free to rename this to init_myStuff_wcms() or something similar.
    2. First, find call to the function ShortFolderItem().
    3. All the existing parameters should be OK after your search/replace.
    4. Next, find the method plugSetVersion().
    5. Replace the two parameters with the version number of the plugin and date of the current release, respectively. The date can be in whatever format you wish.
    6. Next, find the method plugSetWcmsFiles().
    7. Replace the 1st parameter "demo" with "myStuff".
    8. Replace the 2nd parameter "demo.gif" with "myStuff_sm.gif.
    9. Replace the 3rd and 4th parameters with the width and height, respectively, of myStuff_sm.gif.
    10. Replace the 5th parameter "demoL.gif" with "myStuff_lg.gif.
    11. Replace the 6th and 7th parameters with the width and height, respectively, of myStuff_lg.gif.
    12. Replace the 8th parameter with the URL where users may obtain support for this project (required).
    13. Replace the last parameter "readme.html" with myStuff_readme.html if you have a readme file for your project. Otherwise, replace with "".
    14. Next, find the method plugSetTplfiles().
    15. The first parameter, and only parameter should already read "wx_myStuff.auto".
    16. The next method, plugSetStringProps(), should be OK as is after your search/replace.
    17. Find the next method, plugSetEditables().
    18. Set the 1st parameter to 1 if you will have editable properties for your folder item or 0 if there are no editable properties. (Note: this only refers to editable properties for the folder item feature itself, not for individual folder items you create and for which you have your own edit UI.)
    19. The 2nd and 3rd parameters are necessary whether or not the first parameter is set to 1, and the defaults should be OK.
    20. The next method is plugSetInterfaceHooks(). This method is optional if you don't have any arguments for it. If your project needs to place HTML on the user preferences page in the misc section, put the names of your WCJS preferences functions or commands (one for edit prefs, one for edited prefs) in as the 1st and 2nd parameters, without quotes around the names. Place these functions/commands in the wx_myStuff.auto file. These functions/commands should only call another macro or function inside wx_myStuff.auto, similar to the way the stylesheet functions/macros work in the next step. You can use demoFIEditPrefs() and demoFIEditedPrefs() functions from wx_demoFdrItem.auto file as examples of the function for wx_myStuff.auto. If your theme has no need to do this, replace both arguments with "".
    21. If your project needs to add a custom class to the stylesheet, put the name of your WCJS style command or function in as the 3rd parameter. You can copy/edit the command demoUIStyleJS and the macro demoUIStyle from wx_demoFdrItem.auto file if you wish. Place demoUIStyleJS in wx_myStuff.auto and demoUIStyle in wx_myStuff.auto. Edit the names of them to myStuffStyleJS and myStuffStyle and include your own stylesheet code. myStuffStyle needs to set/return the WCTL variable "body". If not, replace with "".
    22. If your project needs to add a link (or links) in the control panel, create a WCJS command or function with the link and add the name of the command/function (not quoted) as the 4th, 5th, 6th and/or 7th parameter, depending on where you want the link(s) to appear.
        4th: Services section.
        5th: Customizing section.
        6th: User section.
        7th: Site section.
        This command/function must live in wx_myStuff.auto file. You can copy/edit the demoExtControlPanelLink() in wx_demoExt.auto if you wish. The last two parameters allow you to put HTML in the sysop-only section of user preferences, in the same way as the others work.
    23. If your project needs to add a HTML on the user preferences page in the sysop section put the name of your WCJS style command or function in as the 8th and 9th parameters (edit prefs, edited prefs). If your project needs to add a HTML on the user preferences page in the profile section put the name of your WCJS style command or function in as the 10th and 11th parameters (edit prefs, edited prefs). Both of these work the same as all the others in this function.
    24. The next method is plugSetThemeHooks(). This method is optional if you don't have any arguments for it. If your project needs to place a link or call a macro in one of the Theme cells (top, bottom, nav, multi-purpose), create a WCTL macro (or WCJS command without any parameters) containing the link or the call. Your component can merely place itself in the optional items menu for the indicated cell to give the sysop an option of where to place the call or link, or it can select itself as the default location. These parameters work in pairs. Parameters 1 and 2 should contain, respectively, the name of the macro you want to be called in the theme top cell (in quotes), and 0 if it should merely appear in the menu, or 1 if it should enable itself. Parameters 3 and 4 contain the same thing for the bottom cell, parameters 5 and 6 contain the same thing for the nav cell, and parameters 7 and 8 contain the same thing for the multi-purpose cell. Parameters 9 and 10, and 11 and 12 are for the content cell top, and content cell bottom, respectively. Look at "macro whichLiveX" in wx_livex.tpl for an example of a macro which can be called in the top cell, bottom cell, nav cell or multi-purpose cell, and which is formatted differently depending on where it's called. This macro should go in your wx_myStuff.tpl file.
    25. Next are plugCheckButtonAccess and plugCheckPageAccess. If you have no special need to do an extra level of access checks, do nothing. If you do want to restrict access to the "add" buttons and pages, edit the functions sayNomyStuff and sayNoPagemyStuff further down the page to return 1 or 0 for the type of access checks you need to do. You'll also need to edit the string "accessInfoString" definition to describe the type of user who can add your project, for the user interface.
    26. Find plugFolderListBeforeText. You may ignore this unless your project needs to place some HTML or text on the page above the entire folder listing.
    27. Next is plugHostOnly. If set to 1, this will not appear on the "enable for this folder" pages at the folder level. It can only be turned on or off at the top level, and thus it will be a host/sysop-only function.
    28. Last is enableFdrItemOnInstall. UNcomment this line (as well as a few additional marked lines at the top of the init function) to have your folder item automatically turn itself on when it is installed for the first time.


11. Look at the bottom of the init function. If you are using any of the arguments for plugSetThemeHooks, you will need two lines like this for each cell where you want your macro to appear in the menu of choices:

    For the nav cell:

    if ( !libraryGlobal.optionalItemsPalette.nav ) libraryGlobal.optionalItemsPalette.nav = new Object();
    libraryGlobal.optionalItemsPalette.nav.myStuff = myStuffArray;
    

    Comment out, or remove, the lines which are not needed. For an example of an extension using all four positions, see the init function in wx_livex.auto
12. Open the example file "wx_demoFdrItem.auto" and copy the JavaScript command "editWrapperdemoFdrItem" and WCTL macro "editWrapperdemoFdrItemForm". Open your "wx_myStuff.auto" file, which contains your existing code, and paste the copied command and macro into the top of the file just below the init function.
13. Select the code you just pasted in, and use search-and-replace on the selected text to replace all instances of the string "demoFdrItem" with "myStuff". This will work as-is, for a folder item without any editable parameters. After you're sure everything is working, you can go back later and create an edit form if you have sysop-editable parameters.
14. Place the newly created folder "myStuff", containing the screenshots and the readme file, in the webx/html/plugins directory of your Web Crossing server. If you are using the built-in FTP server, just go to the "plugins" directory and place the folder there.
15. Copy the two files wx_myStuff.auto and wx_myStuff_s_en_US.auto to the webxTemplates directory of your Web Crossing server. Place any custom images where they need to go.
16. If you used any method to place any of your files except Web Crossing's built in FTP or web file editor, Resynch the server to the filesystem using the link in the Control Panel near the Reset Cache link. Reset the cache in the control panel and test. Make sure the folder item appears in the control panel > Enable Folder Items page, and that you can choose it and it appears as it should, where it should.
17. If everything works OK, you're ready to localize. Go to your macros, and select out the first text string in your wx_myStuff.auto file. Add another line to your strings function for the string that needs replacing. The easiest thing to do is to copy an existing line and then edit it. If the text you want to localize is, "Link to My Stuff", the line would look something like this:

    langStrs.myStuff.en_US.linkToMyStuff="Link to My Stuff";

    You can call your string anything you want, but naming it something obvious makes it easier to keep track of later. Just be careful not to duplicate string names within a function.
18. Then, each place where "Link to My Stuff" appears in your macro, replace it with this for WCTL:

    %% "lang".jscall( "myStuff", "linkToMyStuff" ) // Link to My Stuff %%

    or this, for WCJS:

    lang( 'myStuff', 'linkToMyStuff' ); // Link to My Stuff

    The comments are not necessary but make your code a lot easier to keep track of later.
19. Do the same for each string in your project.
20. Reset the cache and test both your project itself, and the control panel "Choose a Folder Item" page to make sure the text appears properly there, too. Any missing strings will be replaced by "***" and reported in the logLangErrors.log file in your Web Crossing root directory, which is readable directly from the /server directory, or via the Read Logs command in the WCMS developer menu.

» Creating a User Item

1. Choose a name, something like myStuff. Filenames can get kind of long, so keeping the base name short is a good idea. Ten characters or less is best. In this example "myStuff" is the name of the user item.
2. Rename your existing template file "wx_myStuff.auto". Note that case matters.
3. Copy the function init_demoUserItem() from the wx_demoUserItem.auto file at the top of your wx_myStuff.auto file.
4. In the text you just pasted, use search and replace to replace all instances of the string "demoUserItem" with "myStuff".
5. Create the screenshots myStuff_lg.gif and myStuff_sm.gif, and the readme file myStuff_readme.html. Place these in a folder called "myStuff".
6. Open the example file wx_demoUserItem_s_en_US.auto and rename it "wx_myStuff_s_en_US.auto". Do a search-and-replace for all instances of "demoUserItem" and replace with "myStuff". Edit the "projName", "shortDescr", and "explanatoryText" strings as necessary to provide the actual name of the user item as you would like it to appear in the user interface, a short description of what the user item does, and additional text on operation for the edit page. The last two can be the same, if you like. Your user item can put a button in the toolbar if you'd like. If you're doing this, edit the "openText" string to return the name of your user item as it should appear in the text toolbar, and edit the string "openButtonAlt" to return an alt tag for your toolbar button. If you aren't using a toobar button, you can delete both of these lines. (If you already have a strings file for your project you'll have to combine all the strings into one file, and make sure that file is the one named in plugSetWcmsFiles() below.)
7. Edit the init function for the new user item (first one in the wx_myStuff.auto file) as follows:
   1. If you already have an init_myStuff() function elsewhere, feel free to rename this to init_myStuff_wcms() or something similar.
   2. First, find the function ShortUserItem().
   3. Leave the 1st parameter alone.
   4. Change the 2nd parameter to a 0 if your user item should't be enabled by default, before the user makes a choice.
   5. Change the 3rd paramter to a 0 if your user item is not contributing a button/link to the toolbar
   6. If the 3rd parameter == 1, the last 4 parameters are required, otherwise they can be set to "" or removed. The defaults are OK if you need them there. If you include the last 3 parameters, edit them so they have unique names, and also edit the three next lines to match, as well as the names of these functions further down in the file. If you remove the last three parameters or set them to "", comment out the next three lines.
   7. Next, find the method plugSetVersion().
   8. Replace the two parameters with the version number of the plugin and date of the current release, respectively. The date can be in whatever format you wish.
   9. Next, find the method plugSetWcmsFiles().
   10. Replace the 1st parameter "demo" with "myStuff".
   11. Replace the 2nd parameter "demo.gif" with "myStuff_sm.gif.
   12. Replace the 3rd and 4th parameters with the width and height, respectively, of myStuff_sm.gif.
   13. Replace the 5th parameter "demoL.gif" with "myStuff_lg.gif.
   14. Replace the 6th and 7th parameters with the width and height, respectively, of myStuff_lg.gif.
   15. Replace the 8th parameter with the URL where users may obtain support for this project (required).
   16. Replace the last parameter "readme.html" with myStuff_readme.html if you have a readme file for your project. Otherwise, replace with "".
   17. Next, find the method plugSetTplfiles().
   18. The first parameter should already read "wx_myStuff.auto".
   19. The 2nd and 3rd parameters should be "", or missing, for user items.
   20. The next method, plugSetStringProps(), should be OK as is after your search/replace.
   21. Find the next method, plugSetEditables().
   22. Set the 1st parameter to 1 if you will have editable properties for your user item.
   23. The 2nd and 3rd parameters are necessary whether or not the first parameter is set to 1, and the defaults should be OK.
   24. The next method is plugSetInterfaceHooks(). This method is optional if you don't have any arguments for it. If your project needs to place HTML on the user preferences page in the misc section, put the names of your WCJS preferences functions or commands (one for edit prefs, one for edited prefs) in as the 1st and 2nd parameters, without quotes around the names. Place these functions/commands in the wx_myStuff.auto file. These functions/commands should only call another macro or function inside wx_myStuff.auto, similar to the way the stylesheet functions/macros work in the next step. You can use demoFIEditPrefs() and demoFIEditedPrefs() functions from wx_demoFdrItem.auto file as examples of the function for wx_myStuff.auto. If your theme has no need to do this, replace both arguments with "".
   25. If your project needs to add a custom class to the stylesheet, put the name of your WCJS style command or function in as the 3rd parameter. You can copy/edit the command demoUIStyleJS and the macro demoUIStyle from wx_demoFdrItem.auto file if you wish. Place demoUIStyleJS in wx_myStuff.auto and demoUIStyle in wx_myStuff.auto. Edit the names of them to myStuffStyleJS and myStuffStyle and include your own stylesheet code. myStuffStyle needs to set/return the WCTL variable "body". If not, replace with "".
   26. If your project needs to add a link (or links) in the control panel, create a WCJS command or function with the link and add the name of the command/function (not quoted) as the 4th, 5th, 6th and/or 7th parameter, depending on where you want the link(s) to appear.
       4th: Services section.
       5th: Customizing section.
       6th: User section.
       7th: Site section.
       This command/function must live in wx_myStuff.auto file. You can copy/edit the demoExtControlPanelLink() in wx_demoExt.auto if you wish. The last two parameters allow you to put HTML in the sysop-only section of user preferences, in the same way as the others work.
   27. If your project needs to add a HTML on the user preferences page in the sysop section put the name of your WCJS style command or function in as the 8th and 9th parameters (edit prefs, edited prefs). If your project needs to add a HTML on the user preferences page in the profile section put the name of your WCJS style command or function in as the 10th and 11th parameters (edit prefs, edited prefs). Both of these work the same as all the others in this function.
   28. The last method is plugSetThemeHooks(). This method is optional if you don't have any arguments for it. If your project needs to place a link or call a macro in one of the Theme cells (top, bottom, nav, multi-purpose), create a WCTL macro (or WCJS command without any parameters) containing the link or the call. Your component can merely place itself in the optional items menu for the indicated cell to give the sysop an option of where to place the call or link, or it can select itself as the default location. These parameters work in pairs. Parameters 1 and 2 should contain, respectively, the name of the macro you want to be called in the theme top cell (in quotes), and 0 if it should merely appear in the menu, or 1 if it should enable itself. Parameters 3 and 4 contain the same thing for the bottom cell, parameters 5 and 6 contain the same thing for the nav cell, and parameters 7 and 8 contain the same thing for the multi-purpose cell. Parameters 9 and 10, and 11 and 12 are for the content cell top, and content cell bottom, respectively. Look at "macro whichLiveX" in wx_livex.tpl for an example of a macro which can be called in the top cell, bottom cell, nav cell or multi-purpose cell, and which is formatted differently depending on where it's called. This macro should go in your wx_myStuff.tpl file.
   29. Find plugSetUserPrefsEditability. Set this to 1 if you want the user to have the option to turn your project off in their user preferences. Set it to 0 if it doesn't show as an option (i.e. is always on.)
   30. Next is plugCheckButtonAccess. If you have no special need to do an extra level of access checks, do nothing. If you do want to restrict access rights to buttons and pages, edit the functions sayNomyStuff and sayNoPagemyStuff further down the page to return 1 or 0 for the type of access checks you need to do.
   31. Next is plugToolbarLink. If you need to replace the default a tag for the user item button or link in the toolbar, edit the function toolbarLinkmyStuff below to replace the entire "<a href=.....>" tag.
   32. Last is plugButtonBeforeText. This method allows you to place text or code before the toolbar button or link. Edit the function buttonBeforemyStuff below, to return the material you want to appear.


8. Look at the bottom of the init function. If you are using any of the arguments for plugSetThemeHooks, you will need two lines like this for each cell where you want your macro to appear in the menu of choices:

   For the nav cell:

   if ( !libraryGlobal.optionalItemsPalette.nav ) libraryGlobal.optionalItemsPalette.nav = new Object();
   libraryGlobal.optionalItemsPalette.nav.myStuff = myStuffArray;
   

   Comment out, or remove, the lines which are not needed. For an example of an extension using all four positions, see the init function in wx_livex.auto
9. Open the example file "wx_demoUserItem.auto" and copy the JavaScript command "editWrapperdemoUserItem" and WCTL macro "editWrapperdemoUserItemForm". Open your "wx_myStuff.auto" file, which contains your existing code, and paste the copied command and macro into the top of the file just below the init function.
10. Select the code you just pasted in, and use search-and-replace on the selected text to replace all instances of the string "demoUserItem" with "myStuff". This will work as-is, for a user item without any editable parameters. After you're sure everything is working, you can go back later and create an edit form if you have sysop-editable parameters.
11. Place the newly created folder "myStuff", containing the screenshots and the readme file, in the webx/html/plugins directory of your Web Crossing server. (If you're using the built-in FTP server, you can just put the folder in the plugins directory.)
12. Copy the two files wx_myStuff.auto and wx_myStuff_s_en_US.auto to the /webxTemplates directory of your Web Crossing server. Place any custom images where they need to go.
13. If you used any method to place any of your files except Web Crossing's built in FTP or web file editor, Resynch the server to the filesystem using the link in the Control Panel near the Reset Cache link. Reset the cache in the control panel and test. Make sure the user item appears in the control panel > Choose a User Item page, and that you can choose it and it appears as it should, where it should.
14. If everything works OK, you're ready to localize. Go to your macros, and select out the first text string in your wx_myStuff.auto file. Add another line to your strings function for the string that needs replacing. The easiest thing to do is to copy an existing line and then edit it. If the text you want to localize is, "Link to My Stuff", the line would look something like this:

    langStrs.myStuff.en_US.linkToMyStuff="Link to My Stuff";

    You can call your string anything you want, but naming it something obvious makes it easier to keep track of later. Just be careful not to duplicate string names within a function.
15. Then, each place where "Link to My Stuff" appears in your macro, replace it with this for WCTL:

    %% "lang".jscall( "myStuff", "linkToMyStuff" ) // Link to My Stuff %%

    or this, for WCJS:

    lang( 'myStuff', 'linkToMyStuff' ); // Link to My Stuff

    The comments are not necessary but make your code a lot easier to keep track of later.
16. Do the same for each string in your project.
17. Reset the cache and test both your project itself, and the control panel "Choose a User Item" page to make sure the text appears properly there, too. Any missing strings will be replaced by "***" and reported in the logLangErrors.log file in your Web Crossing root directory, which is readable directly from the /server directory, or via the Read Logs command in the WCMS developer menu.