Difference between revisions of "Documentation/DevGuide/OfficeDev/Properties of a Filter"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (1 revision(s))
(32 intermediate revisions by 6 users not shown)
Line 4: Line 4:
 
|OfficeDevDocFilter=block
 
|OfficeDevDocFilter=block
 
|ShowPrevNext=block
 
|ShowPrevNext=block
−
|PrevPage=Documentation/DevGuide/OfficeDev/Properties of an ExtendedTypeDetection Service
+
|PrevPage=Documentation/DevGuide/OfficeDev/Properties of a Type
−
|NextPage=Documentation/DevGuide/OfficeDev/Properties of a FrameLoader
+
|NextPage=Documentation/DevGuide/OfficeDev/Filter Options
 
}}
 
}}
−
{{DISPLAYTITLE:Properties of a Filter}}
+
{{Documentation/DevGuideLanguages|Documentation/DevGuide/OfficeDev/{{SUBPAGENAME}}}}
−
Every filter is registered for only one type . Multiple registrations are to be done by multiple configuration entries. One type is handled by more than one filter. Flags also regulate the use of the preferred filter. A filter is described by the following properties:
+
{{DISPLAYTITLE:Properties of a Filter}}
 +
 
 +
Every filter inside {{PRODUCTNAME}} is specified by the properties shown in the table below. These values are accessible at the previously mentioned service <idl>com.sun.star.document.FilterFactory</idl> using the interface <idl>com.sun.star.container.XNameAccess</idl>. Write access is not available here. All types are addressed by their internal names. The property names are identical to the configuration property names.
 +
 
 +
{{Warn|The documentation of the FilterFactory service currently is outdated. In case of conflicting information about the properties this page is right. An update will follow soon. }}
 +
 
 +
A filter always is registered for only one type. A single filter implementation can handle several types but then must be registered multiple times. One type may handled by more than one filter.  
  
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
Line 16: Line 22:
 
|-
 
|-
 
|<code>Name</code>
 
|<code>Name</code>
−
|string. The internal name of a filter must be unique and is also used as list entry. It contains special characters, but they must be encoded.  
+
|string. The internal name of the filter. This is only an API property, not a configuration property. In the configuration this is the name of the configuration node containing all the other properties. To avoid name clashes with other node names it should follow the rules outlined for [[Documentation/DevGuide/Extensions/Extension_Identifiers | extension identifiers]].
 
|-
 
|-
 
|<code>UIName</code>  
 
|<code>UIName</code>  
−
|string. A filter should be able to show a localized name in selection dialogs. You must assign a value for a language, thus supporting CJK versions. All Unicode characters are permitted here.  
+
|string. User friendly name of the type. It may be localized using the localization support of the configuration. All Unicode characters are permitted here. The UI names of filters are used in the various file dialog.
−
|-
+
−
|<code>Installed</code>
+
−
|boolean. This flag indicates the installation status of a filter. A filter is generally registered equally for all users. In a network installation you should deactivate this for certain groups or single users.
+
−
 
+
−
Note: A filter works only if the component library has already been registered in {{PRODUCTNAME}}.
+
−
|-
+
−
|<code>Order</code>
+
−
|int. This number shows filters in a user defined order. Valid values are greater then 0. If the number is set to 0, sorting is done alphabetically by the <code>UIName</code> property of the filter. The same applies to filters that have the same <code>Order</code> value.  
+
 
|-
 
|-
 
|<code>Type</code>  
 
|<code>Type</code>  
−
|string. A filter must register itself for the type it can handle. Multiple assignments are not allowed. Multiple configuration entries must be created, one for every supported type.  
+
|string. A filter is registered for the type it can handle. Multiple assignments are not allowed. Use multiple configuration entries to support more than one type with a single filter implementation.
 
|-
 
|-
 
|<code>DocumentService</code>  
 
|<code>DocumentService</code>  
−
|string. Describes the component for which the filter operates,For example, "<code>com.sun.star.text.TextDocument</code>", depending upon the use., This is considered the output or goal of the filter process. A UNO service name is expected.
+
|string. UNO service name describing the component on which the filter can operate. As an example, "<code>com.sun.star.text.TextDocument</code>" specifies the filter as working with text documents. An object of this type will be passed to the filter in its <code>setTargetDocument()</code> or <code>setSourceDocument()</code> methods.
−
 
+
−
Note: The implementation name cannot be used here, the generic type of the document is needed.  
+
 
|-
 
|-
 
|<code>FilterService</code>  
 
|<code>FilterService</code>  
−
|string. This is the UNO implementation name of the filter. It should be clear that this field can not contain the service name of a filter, otherwise {{PRODUCTNAME}} could not distinguish more then one registered filter.  
+
|string. This is the UNO service or implementation name of the filter. Of course a service name can be used only if it is not the generic <idl>com.sun.star.document.ImportFilter</idl> or <idl>com.sun.star.document.ExportFilter</idl>. In case of XML based filters the service name always must be <code>com.sun.star.comp.Writer.XMLFilterAdaptor</code>. This filter will use the "UserData" property to find the XMLImporter or XMLExporter service it shall instantiate.  
 
|-
 
|-
 
|<code>UIComponent</code>  
 
|<code>UIComponent</code>  
−
|string. Describes an implementation of a UI dialog used by the filter to let the user modify certain properties for filtering. For example, the "<code>Text - txt - csv (StarCalc)</code>" needs information about the used column separators to load data. To distinguish between different implementations, it must be the real UNO implementation name, not a service name.  
+
|string. UNO service or implementation name of a UI component (usually a dialog) where users can parameterize the filtering process. As an example, the "<code>Text - txt - csv (StarCalc)</code>" filter needs information about the used column separators to load data. More about that in the chapter about [[Documentation/DevGuide/OfficeDev/Filter_Options|filter options]].
 
|-
 
|-
 
|<code>Flags</code>  
 
|<code>Flags</code>  
−
|int. Describes the filter, as shown in the table below. This is where, the organization into import and export filters takes place. Note that external filters must set the <code>ThirdParty</code> flag to be detected.
+
|  
−
|-
+
−
|<code>UserData</code>
+
−
|sequence<string>. Some filters need to store more configuration data than usual. This is realized through this entry. The format of the string list is not restricted.
+
−
|-
+
−
|<code>FileFormatVersion</code>
+
−
|int. Indicates a version number of a document that can be edited by this filter.
+
−
|-
+
−
|<code>TemplateName</code>
+
−
|string. The name of a template file for importing styles. It is a special feature for importing documents only and not useable for export. Every {{PRODUCTNAME}} document service knows default styles. If this <code>TemplateName</code> is set, it merges these default styles with the styles of the template, and the template styles are merged with all styles of a document that is imported by this filter.
+
−
|}
+
  
−
Most functionality of a Filter is listed by its flags. They are necessary to prevent a filter from being displayed in a UI, and to classify import and export, or internal a nd external filters, and prefer some filters to others. Currently supported flags are:
+
* XML : string list. Some boolean attributes of a filter.
 +
 
 +
* FilterFactory service, see <idl>com.sun.star.document.FilterFactory:XNameAccess</idl> : <code>int</code>. Contains a set of boolean values.
  
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
 
|-bgcolor=#EDEDED
 
|-bgcolor=#EDEDED
−
!Name
+
!colspan="2"|Filter flags
−
!Value
+
−
!Description
+
 
|-
 
|-
−
|<code>Import</code> 
+
| ''3RDPARTYFILTER''
−
|<code>0x00000001 h</code>
+
<code>0x00080000 h</code>
−
|This filter supports the specification of a <idl>com.sun.star.document.ImportFilter</idl> and is used for loading content.  
+
 
 +
| The filter is a UNO component filter, as opposed to the internal C++ filters. This is an artefact that will vanish over time.
 
|-
 
|-
−
|<code>Export</code> 
+
| ''ALIEN''
−
|<code>0x00000002 h</code>
+
<code>0x00000040 h</code>
−
|This filter supports the specification of a <idl>com.sun.star.document.ExportFilter</idl> and is used for saving content.  
+
| The filter may lose some information upon saving.
 
|-
 
|-
−
|<code>Template</code> 
+
| ''DEFAULT''
−
|<code>0x00000004 h</code>
+
<code>0x00000100 h</code>
−
|These filters are specialized to handle template formats. By default, a filtered document is used as a template to create a new document .  
+
| This is the "best" filter for the document type it works on that is guaranteed not so lose any data on export. By default this filter will be used or suggested for every storing process unless the user has chosen a different default filter in the options dialog.
 
|-
 
|-
−
|<code>Internal</code> 
+
| ''EXPORT''
−
|<code>0x00000008 h</code>
+
<code>0x00000002 h</code>  
−
|This filter should never be shown on any UI and not be available.  
+
| The filter supports the service com.sun.star.document.ExportFilter. It will be shown in the dialog "File-Export". If the filter also has the "IMPORT" flag set, it will be shown in the dialog "File-Save". This makes sure that a format that a user chooses in the save dialog can be loaded again. The same is not guaranteed for a format chosen in "File-Export".
 
|-
 
|-
−
|<code>OwnTemplate</code> 
+
| ''IMPORT''
−
|<code>0x00000010 h</code>
+
<code>0x00000001 h</code>
−
|Templates used with the template API of {{PRODUCTNAME}} and it supports the internal template features. For older versions, it is usable for internal content formats only.  
+
| The filter supports service com.sun.star.document.ImportFilter. The filter will be shown in the dialog "File-Open".
 
|-
 
|-
−
|<code>Own</code> 
+
| ''INTERNAL''
−
|<code>0x00000020 h</code>
+
<code>0x00000008 h</code>
−
|Tag the intrinsic content formats of {{PRODUCTNAME}} based on OLE storage or zip packages.  
+
| This filter is used only for internal purposes and so can be used only in API calls. Users won't see it ever.
 
|-
 
|-
−
|<code>Alien</code> 
+
| ''NOTINCHOOSER''
−
|<code>0x00000040 h</code>
+
<code>0x00002000 h</code>
−
|A filter with this flag is not fully compatible with the current document format. It is unclear what document features will be lost during saving. This flag decides if a warning box on saving has to be shown.
+
| This filter will not be shown in the dialog box for chosing a filter in case OOo was not able to detect one
 
|-
 
|-
−
|<code>UsesOptions</code> (deprecated) 
+
| ''NOTINFILEDIALOG''
−
|<code>0x00000080 h</code>
+
<code>0x00001000 h</code>  
−
|This filter could be customized during processing. Older versions of {{PRODUCTNAME}} used it to customize the "SaveAs" dialog. Newer versions uses the filter property "UIComponent" to tell if a filter provides filter options.
+
| This filter will not be shown in the file dialog's filter list
 
|-
 
|-
−
|<code>Default</code> 
+
| ''OWN''
−
|<code>0x00000100 h</code>
+
<code>0x00000020 h</code>
−
|Mark a filter as the default filter for saving. Only one filter in an application module, distinguished through the <code>DocumentService</code> property, has this flag set.  
+
| The filter is a native OO.o format (ODF or otherwise).
 
|-
 
|-
−
|<code>NotInFileDialog</code> 
+
| ''PREFERRED''
−
|<code>0x00001000 h</code>
+
<code>0x10000000 h</code>
−
|Suppress display of a filter in file open and save dialogs.
+
| The filter is preferred in case of multiple filters for the same file type exist in the configuration
 
|-
 
|-
−
|<code>NotInChooser</code> 
+
| ''READONLY''
−
|<code>0x00002000 h</code>
+
<code>0x00010000 h</code>  
−
|Suppress display of a filter in UI elements for choosing filters.
+
| All documents imported by this filter will automatically be in read-only state
 
|-
 
|-
−
|<code>ThirdParty</code> 
+
| ''SUPPORTSSELECTION''
−
|<code>0x00080000 h</code>
+
<code>0x00000400 h</code>  
−
|These filters are developed by external parties. For historical reasons, the filter detection of {{PRODUCTNAME}} differentiates between old internal and new external ones, because the former are not UNO based and are used differently.  
+
| Filter can export only the selected part of a document. This information enables {{PRODUCTNAME}} to enable a corresponding check box in the "File-Export" dialog.
 
|-
 
|-
−
|<code>Preferred</code>
+
| ''TEMPLATE''
−
|<code>0x10000000 h</code>
+
<code>0x00000004 h</code>
−
|If more than one filter is registered for the same type, this flag prefers one of them at loading time if the user does not select a specific filter. In contrast to the Default flag, it does not depend on the application module, but there can only be one preferred filter for a type.  
+
| Filter denotes a template filter (means, by default all documents opened by it become an "untitled" one)
 +
|-
 +
| ''TEMPLATEPATH''
 +
<code>0x00000010 h</code>
 +
| Must always be set together with "TEMPLATE" to make this feature flag work; soon becoming deprecated
 +
|}
 +
|-
 +
|<code>UserData</code>
 +
|sequence<string>. Some filters need to store more configuration to work properly. The format of the string list is not restricted. An important example is the filter that implements the XMLFilterAdaptor service. It will get the service name of the XML based filter it must instantiate from the user data. In case this XML based filter is one of the XML adaptors for xslt files, the user data also must contain at least an absolute or relative file path point to the xslt file carrying out the transformation.
 +
|-
 +
|<code>FileFormatVersion</code>
 +
|int. Indicates that a filter handles only a particular format version of the content type. If a filter implementation can handle several versions of a filter, several configuration entries have to be created. This is not necessary if the filter handles all possible versions and the different versions don't need to appear in the user interface.
 +
|-
 +
|<code>TemplateName</code>
 +
|string. The name of a template file for styles the target document of an import filter shall use. If this property is set, the document merges the styles of this template with its default styles before the import starts.
 
|}
 
|}
  
 +
{{Warn|Besides these filter flags there are other flags existing that are used currently, but are not documented here. Use documented flags only.
 +
}}
  
−
{{Documentation/Caution|Besides these filter flags there are other flags existing that are used currently, but are not documented here. Use documented flags only.
+
===Sample configuration for an API based filter===
−
|}
+
  
−
The service <idl>com.sun.star.document.FilterFactory</idl> provides these data. It supports read access by using the interface <idl>com.sun.star.container.XNameAccess</idl>. All items are addressed by their internal names. The return value is represented as a list of type <idl>com.sun.star.beans.PropertyValue</idl> structures. It uses the filter properties shown above.
+
<source lang="xml">
 +
<!-- Filter section -->
 +
<node oor:name="Text (encoded)" oor:op="replace">
 +
    <prop oor:name="UIName">
 +
        <value>Text (encoded)</value>
 +
    </prop>
 +
    <prop oor:name="Flags"><value>IMPORT EXPORT ALIEN</value></prop>
 +
    <prop oor:name="UIComponent"><value>com.sun.star.comp.Writer.FilterOptionsDialog</value></prop>
 +
    <prop oor:name="FilterService"/>
 +
    <prop oor:name="UserData"><value>TEXT_DLG</value></prop>
 +
    <prop oor:name="FileFormatVersion"><value>0</value></prop>
 +
    <prop oor:name="Type"><value>writer_Text_encoded</value></prop>
 +
    <prop oor:name="TemplateName"/>
 +
    <prop oor:name="DocumentService"><value>com.sun.star.text.TextDocument</value></prop>
 +
</node>
 +
</source>
  
−
Another aspect of this service is the factory interface <idl>com.sun.star.lang.XMultiServiceFactory</idl>. It creates filter instances using an internal type, or an internal filter name directly. Using a type name searches for a suitable filter and creates, initializes and returns it. Using a filter name directly follows the algorithm shown in the box below. Note that creation of filters is possible for external ones only that have set the <code>FilterService</code> property. Most of the current filters of {{PRODUCTNAME}} are internal filters, implemented as local code, but not as a UNO service. They can not be created by this <code>FilterFactory</code>. It is possible to ask only for their properties.
+
{{Note|This filter has a UIComponent that shows that this filter needs additional information to load a file properly (the encoding of it in case it can't be detected). It does not have a "FilterService" property because it is an internal, C++ based filter.}}
  
−
{{Documentation/Caution|Direct creation of a filter instance is only possible using a special argument in the <tt>createInstanceWithArguments()</tt> call of the interface <tt>XMultiServiceFactory</tt>. To do so, a <idl>com.sun.star.beans.PropertyValue</idl> FilterName with the internal name of the requested filter as value must be used. Otherwise, the service specifier, that is, the first argument of the create call, is interpreted as an internal type name. It will be used to search a suitable, preferred filter that will be created. It is a combination of searching and creation. Future implementations will split that to make it clearer. In future implementations, a registered filter must be searched through the provided query mechanism and created by using this factory interface.}}
+
===Sample configuration for an XML based filter===
 +
 
 +
<source lang="xml">
 +
  <!-- Filter section -->
 +
  <node oor:name="PocketWord File" oor:op="replace">
 +
      <prop oor:name="UIName">
 +
          <value>Pocket Word</value>
 +
      </prop>
 +
      <prop oor:name="Type"><value>writer_PocketWord_File</value></prop>
 +
      <prop oor:name="FileFormatVersion"><value>0</value></prop>
 +
      <prop oor:name="DocumentService"><value>com.sun.star.text.TextDocument</value></prop>
 +
      <prop oor:name="FilterService"><value>com.sun.star.comp.Writer.XmlFilterAdaptor</value></prop>
 +
      <prop oor:name="UIComponent"/>
 +
      <prop oor:name="UserData"><value>com.sun.star.documentconversion.XMergeBridge classes/pocketword.jar com.sun.star.comp.Writer.XMLImporter com.sun.star.comp.Writer.XMLExporter staroffice/sxw application/x-pocket-word</value></prop>
 +
      <prop oor:name="TemplateName"/>
 +
      <prop oor:name="Flags"><value>IMPORT EXPORT ALIEN 3RDPARTYFILTER</value></prop>
 +
  </node>
 +
</source>
 +
 
 +
{{Note|This filter uses the XMLFilterAdaptor service. The "UserData" property is a space-separated list where the first list element denotes the XMLImportFilter to be instantiated and the third one and fourth one are service names of DocumentHandlers for import and export. Further parameters depend on the XMLImportFilter used.}}
 +
 
 +
===Sample configuration for an xslt based filter===
 +
 
 +
<source lang="xml">
 +
  <!-- Filter section -->
 +
  <node oor:name="MediaWiki" oor:op="replace">
 +
      <prop oor:name="FileFormatVersion"><value>0</value></prop>
 +
          <prop oor:name="Type"><value>MediaWiki</value></prop>
 +
          <prop oor:name="DocumentService"><value>com.sun.star.text.TextDocument</value></prop>
 +
          <prop oor:name="UIComponent"/>
 +
          <prop oor:name="UserData"><value oor:separator=",">com.sun.star.documentconversion.XSLTFilter,,,com.sun.star.comp.Writer.XMLOasisExporter,,../share/xslt/wiki/odt2mediawiki.xsl</value></prop>
 +
          <prop oor:name="FilterService"><value>com.sun.star.comp.Writer.XmlFilterAdaptor</value></prop>
 +
          <prop oor:name="UIName">
 +
              <value xml:lang="x-default">MediaWiki</value>
 +
          </prop>
 +
          <prop oor:name="Flags"><value>EXPORT ALIEN 3RDPARTYFILTER</value></prop>
 +
        </node>
 +
</source>
 +
 
 +
{{Note|This filter uses the XMLFilterAdaptor service. The "UserData" property is a space-separated list where the first list element denotes the XMLImportFilter to be instantiated and the third one and fourth one are service names of DocumentHandlers for import and export. Further parameters depend on the XMLImportFilter used. }}
 +
 
 +
Here the XMLFilter used is the <idl>com.sun.star.documentconversion.XSLTFilter</idl> that bridges to xslt files and basically can import and export if a suitable xslt is provided. It expects the following parameters in the user data ($(APP) stands for Writer,Calc,Draw,Impress,Chart,Math):
 +
 
 +
(1) service name of the XSLTFilter
 +
(3) implementation/service name of an importer class (com.sun.star.comp.$(APP).XMLOasisImporter)
 +
(4) implementation/service name of an exporter class (com.sun.star.comp.$(APP).XMLOasisExporter)
 +
(5) relative or absolute path name to an importing style sheet
 +
(6) relative or absolute path name to an importing style sheet
 +
 
 +
{{Note|Older xslt based filters might have used the pre-ODF file format of {{PRODUCTNAME}}. They used importer and exporter class without "Oasis" in their names.}}
  
 
{{PDL1}}
 
{{PDL1}}
−
[[Category: Office Development]]
+
 
 +
[[Category:Documentation/Developer's Guide/Office Development]]

Revision as of 07:39, 12 July 2018



Every filter inside OpenOffice.org is specified by the properties shown in the table below. These values are accessible at the previously mentioned service com.sun.star.document.FilterFactory using the interface com.sun.star.container.XNameAccess. Write access is not available here. All types are addressed by their internal names. The property names are identical to the configuration property names.

Documentation caution.png The documentation of the FilterFactory service currently is outdated. In case of conflicting information about the properties this page is right. An update will follow soon.

A filter always is registered for only one type. A single filter implementation can handle several types but then must be registered multiple times. One type may handled by more than one filter.

Property Name Description
Name string. The internal name of the filter. This is only an API property, not a configuration property. In the configuration this is the name of the configuration node containing all the other properties. To avoid name clashes with other node names it should follow the rules outlined for extension identifiers.
UIName string. User friendly name of the type. It may be localized using the localization support of the configuration. All Unicode characters are permitted here. The UI names of filters are used in the various file dialog.
Type string. A filter is registered for the type it can handle. Multiple assignments are not allowed. Use multiple configuration entries to support more than one type with a single filter implementation.
DocumentService string. UNO service name describing the component on which the filter can operate. As an example, "com.sun.star.text.TextDocument" specifies the filter as working with text documents. An object of this type will be passed to the filter in its setTargetDocument() or setSourceDocument() methods.
FilterService string. This is the UNO service or implementation name of the filter. Of course a service name can be used only if it is not the generic com.sun.star.document.ImportFilter or com.sun.star.document.ExportFilter. In case of XML based filters the service name always must be com.sun.star.comp.Writer.XMLFilterAdaptor. This filter will use the "UserData" property to find the XMLImporter or XMLExporter service it shall instantiate.
UIComponent string. UNO service or implementation name of a UI component (usually a dialog) where users can parameterize the filtering process. As an example, the "Text - txt - csv (StarCalc)" filter needs information about the used column separators to load data. More about that in the chapter about filter options.
Flags
  • XML : string list. Some boolean attributes of a filter.
Filter flags
3RDPARTYFILTER

0x00080000 h

The filter is a UNO component filter, as opposed to the internal C++ filters. This is an artefact that will vanish over time.
ALIEN

0x00000040 h

The filter may lose some information upon saving.
DEFAULT

0x00000100 h

This is the "best" filter for the document type it works on that is guaranteed not so lose any data on export. By default this filter will be used or suggested for every storing process unless the user has chosen a different default filter in the options dialog.
EXPORT

0x00000002 h

The filter supports the service com.sun.star.document.ExportFilter. It will be shown in the dialog "File-Export". If the filter also has the "IMPORT" flag set, it will be shown in the dialog "File-Save". This makes sure that a format that a user chooses in the save dialog can be loaded again. The same is not guaranteed for a format chosen in "File-Export".
IMPORT

0x00000001 h

The filter supports service com.sun.star.document.ImportFilter. The filter will be shown in the dialog "File-Open".
INTERNAL

0x00000008 h

This filter is used only for internal purposes and so can be used only in API calls. Users won't see it ever.
NOTINCHOOSER

0x00002000 h

This filter will not be shown in the dialog box for chosing a filter in case OOo was not able to detect one
NOTINFILEDIALOG

0x00001000 h

This filter will not be shown in the file dialog's filter list
OWN

0x00000020 h

The filter is a native OO.o format (ODF or otherwise).
PREFERRED

0x10000000 h

The filter is preferred in case of multiple filters for the same file type exist in the configuration
READONLY

0x00010000 h

All documents imported by this filter will automatically be in read-only state
SUPPORTSSELECTION

0x00000400 h

Filter can export only the selected part of a document. This information enables OpenOffice.org to enable a corresponding check box in the "File-Export" dialog.
TEMPLATE

0x00000004 h

Filter denotes a template filter (means, by default all documents opened by it become an "untitled" one)
TEMPLATEPATH

0x00000010 h

Must always be set together with "TEMPLATE" to make this feature flag work; soon becoming deprecated
UserData sequence<string>. Some filters need to store more configuration to work properly. The format of the string list is not restricted. An important example is the filter that implements the XMLFilterAdaptor service. It will get the service name of the XML based filter it must instantiate from the user data. In case this XML based filter is one of the XML adaptors for xslt files, the user data also must contain at least an absolute or relative file path point to the xslt file carrying out the transformation.
FileFormatVersion int. Indicates that a filter handles only a particular format version of the content type. If a filter implementation can handle several versions of a filter, several configuration entries have to be created. This is not necessary if the filter handles all possible versions and the different versions don't need to appear in the user interface.
TemplateName string. The name of a template file for styles the target document of an import filter shall use. If this property is set, the document merges the styles of this template with its default styles before the import starts.
Documentation caution.png Besides these filter flags there are other flags existing that are used currently, but are not documented here. Use documented flags only.

Sample configuration for an API based filter

 <!-- Filter section -->
 <node oor:name="Text (encoded)" oor:op="replace">
     <prop oor:name="UIName">
         <value>Text (encoded)</value>
     </prop>
     <prop oor:name="Flags"><value>IMPORT EXPORT ALIEN</value></prop>
     <prop oor:name="UIComponent"><value>com.sun.star.comp.Writer.FilterOptionsDialog</value></prop>
     <prop oor:name="FilterService"/>
     <prop oor:name="UserData"><value>TEXT_DLG</value></prop>
     <prop oor:name="FileFormatVersion"><value>0</value></prop>
     <prop oor:name="Type"><value>writer_Text_encoded</value></prop>
     <prop oor:name="TemplateName"/>
     <prop oor:name="DocumentService"><value>com.sun.star.text.TextDocument</value></prop>
 </node>
Documentation note.png This filter has a UIComponent that shows that this filter needs additional information to load a file properly (the encoding of it in case it can't be detected). It does not have a "FilterService" property because it is an internal, C++ based filter.

Sample configuration for an XML based filter

  <!-- Filter section -->
  <node oor:name="PocketWord File" oor:op="replace">
      <prop oor:name="UIName">
          <value>Pocket Word</value>
      </prop>
      <prop oor:name="Type"><value>writer_PocketWord_File</value></prop>
      <prop oor:name="FileFormatVersion"><value>0</value></prop>
      <prop oor:name="DocumentService"><value>com.sun.star.text.TextDocument</value></prop>
      <prop oor:name="FilterService"><value>com.sun.star.comp.Writer.XmlFilterAdaptor</value></prop>
      <prop oor:name="UIComponent"/>
      <prop oor:name="UserData"><value>com.sun.star.documentconversion.XMergeBridge classes/pocketword.jar com.sun.star.comp.Writer.XMLImporter com.sun.star.comp.Writer.XMLExporter staroffice/sxw application/x-pocket-word</value></prop>
      <prop oor:name="TemplateName"/>
      <prop oor:name="Flags"><value>IMPORT EXPORT ALIEN 3RDPARTYFILTER</value></prop>
   </node>
Documentation note.png This filter uses the XMLFilterAdaptor service. The "UserData" property is a space-separated list where the first list element denotes the XMLImportFilter to be instantiated and the third one and fourth one are service names of DocumentHandlers for import and export. Further parameters depend on the XMLImportFilter used.

Sample configuration for an xslt based filter

  <!-- Filter section -->
  <node oor:name="MediaWiki" oor:op="replace">
      <prop oor:name="FileFormatVersion"><value>0</value></prop>
          <prop oor:name="Type"><value>MediaWiki</value></prop>
          <prop oor:name="DocumentService"><value>com.sun.star.text.TextDocument</value></prop>
          <prop oor:name="UIComponent"/>
          <prop oor:name="UserData"><value oor:separator=",">com.sun.star.documentconversion.XSLTFilter,,,com.sun.star.comp.Writer.XMLOasisExporter,,../share/xslt/wiki/odt2mediawiki.xsl</value></prop>
          <prop oor:name="FilterService"><value>com.sun.star.comp.Writer.XmlFilterAdaptor</value></prop>
          <prop oor:name="UIName">
              <value xml:lang="x-default">MediaWiki</value>
          </prop>
          <prop oor:name="Flags"><value>EXPORT ALIEN 3RDPARTYFILTER</value></prop>
        </node>
Documentation note.png This filter uses the XMLFilterAdaptor service. The "UserData" property is a space-separated list where the first list element denotes the XMLImportFilter to be instantiated and the third one and fourth one are service names of DocumentHandlers for import and export. Further parameters depend on the XMLImportFilter used.

Here the XMLFilter used is the com.sun.star.documentconversion.XSLTFilter that bridges to xslt files and basically can import and export if a suitable xslt is provided. It expects the following parameters in the user data ($(APP) stands for Writer,Calc,Draw,Impress,Chart,Math): 

(1) service name of the XSLTFilter
(3) implementation/service name of an importer class (com.sun.star.comp.$(APP).XMLOasisImporter)
(4) implementation/service name of an exporter class (com.sun.star.comp.$(APP).XMLOasisExporter)
(5) relative or absolute path name to an importing style sheet
(6) relative or absolute path name to an importing style sheet
Documentation note.png Older xslt based filters might have used the pre-ODF file format of OpenOffice.org. They used importer and exporter class without "Oasis" in their names.
Content on this page is licensed under the Public Documentation License (PDL).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/DevGuide/OfficeDev/Properties_of_a_Filter&oldid=241950"
Personal tools
In other languages