<<TableOfContents>>

= FTI: Format DNA =

The purpose of this article is to provide education on how
to extend ePublisher Formats and the ePublisher User Interface  
through the use of FTI, and to generate excitement about using 
FTI in your own custom ePublisher Formats.

== Introduction ==

FTI  is Format Trait Info.  However, this hardly distinguishes 
its context or its meaning.  What's it tied to?  What's the larger
context? What does it do?  Why should I care?  

You should care because everything is FTI.  From the time you pop open ePublisher 
Pro to the time you generate and close, you are rubbing right up 
against FTI.

Maybe we should have called it DNA. In fact this is a pretty 
decent metaphor for FTI's purpose in the ePublisher view of the 
universe.  All formatting information related to a given 
ePublisher target format exists as a result of FTI.

This is an important distinction in that, just as I cannot 
call my ear or nose or fingers or knees or receding hairline, 
DNA;  I cannot call the formatting panels which exist in the 
ePublisher Pro User Interface, FTI.  FTI is not the user
interface itself.  Rather, it is the XML configuration files which
define the way the User Interface will appear to the end user; 
which options will be available to them. 

And just as DNA define the traits of an organism, so FTI defines
the traits of your ePublisher Format.  That is to say, FTI is 
the: 

 <!FormatTraitInfo />

In this article, we examine FTI by dividing it into three main parts:

 * Getting FTI into ePublisher.
 * Writing FTI, in the sense of making the options available for end
 users to affect.
 * Reading FTI, in the sense of examining facilities available in
 ePublisher for retrieving information the end user enters.

== Getting FTI Into ePublisher ==

Getting FTI into ePublisher consists of 3 Main Components:

 * Format File (format.wwfmt)
 * XSL File (*.xsl)
 * FTI File (*.fti)

A format file mainly consists of a Pipelines container with one or 
more Pipeline elements within.  Each Pipeline container contains one
or more Stage elements.  Each Stage element defines an action,
which is a URI to an XSL file.  

{{{
<Pipelines>
 <Pipeline name="foo">
  <Stage type="xsl" action="wwformat:Transforms/do-foo.xsl">
...
}}}

When ePublisher processes a format file, it compiles each XSL
transform in preparation for executing each Pipeline's Stage(s). As
a corollary to this activity, for each XSL transform defined in the
format file, ePublisher checks for the existence of a file which has
the XSL file's basename combined with a *.fti extension.

If the ePublisher runtime finds this file, it loads the FTI file and
makes the information defined within, available in the ePublisher
User Interface.

In the attached [[attachment:FTI-Example-Project.zip]], we define a simple
format which includes each of the three elements we've identified:

 * Format file (<Project-Location>\Formats\FTI-Example\format.wwfmt)
 * XSL file (<Project-Location>\Formats\FTI-Example\Transforms\example.xsl)
 * FTI file (<Project-Location>\Formats\FTI-Example\Transforms\example.fti)

The FTI file defines a Format Setting called "Hello Message". 
Clicking generate executes the simple Pipeline which writes the 
contents of the "Hello Message" setting to the log.

== Writing FTI ==

In this section we will deconstruct '''example.fti''' and add new
information to demonstrate how this information is reflected in
the ePublisher User Interface.  You may wish to modify '''example.fti'''
as you read through this section to try it yourself.

  '''NOTE:''' FTI settings are loaded when an ePublisher project loads.
  You need to close and reopen the project when you change the FTI file
  to see those changes reflected in the ePublisher User Interface.

An FTI file contains 4 Top Level Containers:

 * Classes
 * Groups
 * Settings
 * !RuleTraitsSet

{{{
<?xml version="1.0" encoding="utf-8"?>
<FormatTraitInfo>

 <Classes />

 <Groups />

 <Settings />

 <RuleTraitsSet />
</FormatTraitInfo>
}}}

=== Classes ===

Classes refer to what type of thing the Information defines. 
ePublisher includes a number of default classes for items such as
'''string''', '''boolean''', '''percent''', '''pixels''', and 
others.  These default classes are defined in the following 
location, relative to your ePublisher install:

{{{<ePublisher-Home>\Formats\Shared\classes.fti}}}

When writing an FTI file, you have the flexibility to create your
own classes.  Consider the following FTI:

'''Excerpt from ''example.fti'''''

{{attachment:p-example-fti-classes.jpg}}

This FTI produces the following result in the ePublisher User
Interface.

'''''Class'' information reflected in ePublisher'''

{{attachment:p-fti-classes-epub.jpg}}

=== Groups ===

The Groups element allows you to define organizational containers
for grouping FTI elements.  Consider the following FTI:

'''Excerpt from ''example.fti'''''

{{attachment:p-example-fti-groups.jpg}}


This FTI produces the following result in the ePublisher User
Interface.

'''''Group'' information reflected in ePublisher'''

{{attachment:p-fti-groups-epub.jpg}}

  '''NOTE:''' In ''Format Settings'' and in the Style Designer's ''Options'' view, 
  ePublisher indicates that a user has customized an item by bolding the
  text of the custom item.  Default settings, which come from the FTI's "default"
  attribute appear as text which is not bold.  For example, notice the screen
  capture above.  The default value "Monday" appears with normal emphasis.  The
  customized value "Thursday" appears with bold emphasis.

=== Settings ===

The Settings element is for Format Settings.  Fomat Settings is the dialog which is 
displayed by navigating to '''Format > Format Settings''' or by clicking the 
{{attachment:fs-icon.jpg}} icon on the toolbar.  ''The Settings'' container and the ''Format Settings'' dialog is pictured below.

'''Excerpt from ''example.fti'''''

{{attachment:p-example-fti-settings.jpg}}

'''''Setting'' information reflected in ePublisher'''

{{attachment:p-fs-dialog.jpg}}

=== RuleTraitsSet ===

The !RuleTraitsSet element is for Properties and Options for those categories of 
things which appear in the Style Designer pane.  Consider the following:

'''Excerpt from ''pages.fti'' in ''<ePublisher-Home>\Formats\Dynamic HTML\Transforms'''''

{{attachment:p-pages-fti-rts-options.jpg}}

This FTI produces the following result in the ePublisher User Interface:

'''''Option'' information reflected in ePublisher'''

{{attachment:p-rts-options-epub.jpg}}

The same is true for Properties.  Consider the following:

'''Excerpt from ''css.fti'' in ''<ePublisher-Home>\Formats\Shared\html'''''

{{attachment:p-css-fti-rts-properties.jpg}}

This FTI produces the following result in the ePublisher User Interface:

'''''Property'' information reflected in ePublisher'''

{{attachment:p-rts-properties-epub.jpg}}

== Reading FTI ==

Anytime a user customizes a ''Format Setting'', in the ''Format Settings'' dialog, or a
''Property'' or ''Option'' in the Style Designer, that information is written to the project
file (*.wep). Just as we have looked at the facilities available for extending the ePublisher
User Interface (FTI), ePublisher also provides a number of facilities for reading the value 
of FTI once a user has customized them.  These can be organized in two main parts: Settings 
and Rules.

=== Settings ===

Settings refers to ''Format Settings''. ePublisher defines a number of XSL Extension 
objects (see [[DevCenter/Documentation/ExtensionObjects|Extension Objects]]) for simplifying certain tasks.  
In the case of ''Format Settings'', a method for retrieving a setting is located in the 
urn:!WebWorks-XSLT-Extension-Project namespace (usually wwprojext).  The following lines 
demonstrate some custom Format Settings and how to retrieve the value of the 
''company-email'' setting using the [[DevCenter/Documentation/ExtensionObjects#project|wwprojext]]:!GetFormatSetting extension method.  
Consider the following settings defined in ePublisher for a project called "foo":

'''''Format Settings'' for ePublisher Project ''foo'''''

{{attachment:p-fs-epub.jpg}}

These settings are written to the '''foo''' project file as demonstrated
in the following excerpt:

'''Excerpt from ''foo.wep'''''

{{attachment:p-fs-wep.jpg}}

The settings may be retrieved in XSL as follows:

'''!GetFormatSetting'''

{{attachment:p-getformatsettings.jpg}}

=== Rules ===

Rules refers to the ''Properties'' and ''Options'' which may be defined for the categories 
of things which appear in the ePublisher System Designer.  These include: Paragraph, 
Character, Table, Graphic, Page, and Marker Styles.  Consider the following Rule information
for an ePublisher project called "foo":

'''Paragraph ''Properties'' for ''Section'' in ePublisher Project ''foo'''''

{{attachment:p-props-epub.jpg}}

'''Paragraph ''Options'' for ''Section'' in ePublisher Project ''foo'''''

{{attachment:p-options-epub.jpg}}

These settings are written to the '''foo''' project file as demonstrated
in the following excerpt:

'''Excerpt from ''foo.wep'''''

{{attachment:p-props-options-wep.jpg}}

The settings may be retrieved in XSL as follows:

'''!GetRule'''

{{attachment:p-getrule.jpg}}

== Wiki Example ==

[[attachment:Wiki.Publish.zip]]

The attached zip file includes three top level folders:

 * Comparison
 * Wiki.Publish.Base
 * Wiki.Publish.FTI

The folder named ''Comparison'' contains an HTML diff of
the changes between the base format and the format with
the FTI extensions.  

The folder named ''Wiki.Publish.Base'' contains the base
Wiki format which only handles hard-coded paragraphs and
wiki "section" or "heading" markup.

The folder named ''Wiki.Publish.FTI'' extends the base format
and provides '''wiki-prefix''' and '''wiki-suffix''' FTI 
options on Paragraph Styles.  This eliminates the need to 
alleviates the limitation of hard-coding heading paragraphs
in the XSL.