When ExSite builds a page, it may encounter numerous types of special tags in the HTML that it "expands" into real content (HTML) or references (URLs) that are substituted in place of the tags. Different types of tags refer to different things, such as:
When a dynamic content plug-in tag is encountered, ExSite invokes the plug-in, passes it a text string of parameters, and receives back a text string of HTML content. The content is substituted back into the page in place of the dynamic content plug-in tag.
A plug-in tag looks like this:
<!--&Plugger(parameters)-->
This says to invoke the plug-in "Plugger", and pass it the parameter string "parameters". "Plugger" will return a block of HTML that will replace the above tag. Note that the HTML code returned by Plugger can include more tags that require further expansion.
Technical details on how to program plug-ins are available in the ExSite Developers Guide.
The "parameters" string that gets passed to the plug-in is an arbitrary text string. The only text you should avoid in this string is )-->, since that is used to detect the end of the plug-in tag. You should also be wary of using codes that have meaningful HTML translations (eg. &) since browsers and the HTML editor may choose to convert these to equivalent characters, thereby changing your parameter string unexpectedly.
Following are several examples of parameter strings:
<!--&PrintFriendly()-->
<!--&MailTo(info@exsitewebware.com)-->
<!--&SimpleMenu(vertical,submenu-only)-->
<!--&Zine(zine=show&aid=432&archive=1)-->This uses a common convention of using URL-encoding to separate multiple parameters in a single string. Because this tag gets placed into regular HTML, the ampersand characters can sometimes be ambiguous (since ampersands are used as HTML escape codes). ExSite may convert them to & to disambiguate them -- this will not break your parameters, but it may look ugly or cause confusion. If you don't like that treatment, then consider using semi-colons in place of ampersands, eg.:
<!--&Zine(zine=show;aid=432;archive=1)-->
You may code plug-in tags into your HTML templates, or your page-specific content. If working with raw HTML, just type them in the above format. If editing existing plug-in tags, simply modify them as appropriate. Note that ampersand characters may be converted to & to disambiguate the characters from HTML escape codes, but they will work fine in either case.
When working from the HTML editor, plug-in tags get special treatment. Since they resemble HTML comments, they are normally invisible if viewed directly as HTML. The ExSite HTML editor converts them to an appropriate icon so that the plug-in tag is visible in WYSIWYG mode. To remove the plug-in from the page, simply click on the icon and hit the delete key.
You cannot edit the parameter field in WYSIWYG mode. To modify the plug-in, delete the old icon, and re-insert the plug-in using the dynamic content tool. In some cases, the plug-in will customize the parameters input to make it easier to select from the available options. In other cases, only a simple text input box for parameters will be given. In the latter case, type your parameter string exactly as it should appear in the final tag. You can always leave the parameter field blank, or select the default to get the default plug-in behaviour.
A "Service" is a plug-in whose links all direct to a particular page. This is different from the default behaviour, which is to link back to the same page.
Example: Take a Search plug-in, which outputs a small search form, and generates lists of search results. By default, the plug-in will display a search form, and when a term is entered, will replace the form with a list of results. This is often NOT the desired behaviour, because search forms can be embedded in compact parts of the template (sidebars, footers) that cannot expand to hold all of the search results. The preferred action is for the plug-in to redirect its output somewhere else so that the results can be displayed in the main body of the page, which is large and flexible enough to hold them all. This is what a Service does.
Services are useful any time a plug-in can generate compact or summary views that are useful for sidebars, headers, or footers, but those views link to expanded views that no longer fit in those confined spaces. Typical examples include:
In each of these cases, the summary view consists of a small amount of teaser content or a simple form, but it will link through to a more exhaustive view if the user chooses to go there.
When configuring a service, you set one specific page to handle all requests from a particular plug-in. (For instance, all search requests go to search.html.) On that page, you move the plug-in from the sidebar/header/footer/confined space to the main body of the page where it will have room to place as much content as it wants to.
To run a plug-in as a service on a particular website, go to that Website in the ExSite Security Manager tool. Click on "Add new website service" to create a new service (or select a service to modify). Then you can select both the plug-in and the service page on the next form. Note that you must already have created the service page, since it will only allow you to choose from the available pages on the site.
Ensure that the service page includes the plug-in in its main body. If the plug-in is not smart enough to figure out that it is running multiple times on the page, you may also have to modify the template to remove the other references to it.
ExSite can automatically run any plug-in in AJAX mode, with some minor changes to the tag format. AJAX mode executes the plug-in asynchronously using Javascript. Reasons to do this are:
Placing dynamic content on an otherwise static page. For example, you can make part of a static index.html page contain live dynamic plug-in content. Only the plug-in content is rendered dynamically; the remainder of the page is more efficient static content. Without AJAX, the plug-in is executed at the time the static page is created; it will show the state of the plug-in at that time, but not refresh itself as the plug-in continues to get updated.
Refresh the plug-in content without refreshing the entire page. This gives the impression of a smoother page reload, since you do not wipe and redraw the entire page, which is a slow operation.
When you run your plug-ins in AJAX mode, the plug-in tag is NOT substituted with plug-in content. Instead, it is substituted with a small Javascript that calls the plug-in separately. The javascript call obtains the plug-in content, and then makes the substitution *after* the page is already loaded into the viewer's browser.
The client browser must have Javascript enabled in order to benefit from AJAX mode. If Javascript is disabled, the plug-in will return something like this: "You must have Javascript enabled to view Plugger."
ExSite actually supports two AJAX modes, which we'll call half-AJAX and full-AJAX.
In half-AJAX mode, the first substitution of the plug-in content happens using AJAX methods. If the plug-in contains recursive links (self-referential links back to the plug-in to regenerate different views of the plug-in content), then those links are not AJAX. Clicking on links in the plug-in content will cause a full page re-load.
Reasons why you might want to do this:
To invoke a plug-in in half-AJAX mode, add a second ampersand in front of the module name, eg.:
<!--&&Plugger(parameters)-->
In full-AJAX mode, recursive links back to the plug-in will also use AJAX methods. This causes the plug-in to refresh itself in place without causing a full page reload.
Reasons why you might want to do this:
To run a plug-in in full-AJAX mode, add a third ampersand in front of the module name, eg.:
<!--&&&Plugger(parameters)-->
The SlideShow tool makes for a good AJAX-enabled plug-in. Add a tag to invoke the SlideShow in full-AJAX mode:
<!--&&&SlideShow(name=ALBUM_NAME;button=black)-->
where "ALBUM_NAME" is the publication folder of an image library on your web site.
This will set up the default view of the album, consisting of the first image, with some SlideShow controls at the bottom of the image. Clicking on the controls will update the slideshow image without redrawing the page, and without taking the hit of preloading all of the images.
Note that if your images are of widely varying sizes, the AJAX updates may cause your page to reflow in unexpected ways, and the position of your controls to jump around. To keep things consistently positioned, use a library with similarly-sized images.