ro.sync.ecss.extensions.api
Class AuthorExternalObjectInsertionHandler

java.lang.Object
  ro.sync.ecss.extensions.api.AuthorExternalObjectInsertionHandler

All Implemented Interfaces:

Extension, ExternalObjectInsertionSources

Direct Known Subclasses:

DITAExternalObjectInsertionHandler, DITAMapExternalObjectInsertionHandler, Docbook4ExternalObjectInsertionHandler, Docbook5ExternalObjectInsertionHandler, TEIP4ExternalObjectInsertionHandler, TEIP5ExternalObjectInsertionHandler, XHTMLExternalObjectInsertionHandler

@API(type=EXTENDABLE,
     src=PUBLIC)
public abstract class AuthorExternalObjectInsertionHandler
extends java.lang.Object
implements ExternalObjectInsertionSources, Extension

This class is notified when URLs are dropped or pasted to an Author Editor page or when XHTML fragments are pasted or dropped from external applications (like web browsers or office applications) to the Author page.
If you want to use a stylesheet to convert the pasted XHTML to your own XML vocabulary you can just overwrite the method: "ro.sync.ecss.extensions.api.AuthorExternalObjectInsertionHandler.getImporterStylesheetFileName(AuthorAccess)" and return the file name of the stylesheet which will be applied. The path to the importer stylesheet must be added in the Classpath tab in the Document Type Association edit dialog (as an example you can see the DITA and Docbook document types).

Since:

12

Field Summary

static java.lang.String

ONLY_TEXT_CONTENT_STYLESHEET An XSLT stylesheet for extracting the entire text content (and only the text content) from any input XML, except the text from elements: xhtml:span[contains(@style, 'mso-list:Ignore')]

Fields inherited from interface ro.sync.ecss.extensions.api.ExternalObjectInsertionSources

DND_DB_TREE, DND_DITA_MAPS_MANAGER, DND_EXTERNAL, DND_IMAGE_PREVIEW, DND_PROJECT_TREE, PASTE

Constructor Summary

AuthorExternalObjectInsertionHandler()

Method Summary

boolean	acceptSource(AuthorAccess authorAccess, int source) Confirm that the source of URLs is interesting to this handler.
boolean	acceptURLs(AuthorAccess authorAccess, java.util.List<java.net.URL> urls, int source) Confirm that the list of URLs is interesting to this handler.
protected boolean	checkImportedXHTMLContentIsPreservedEntirely() Overwrite this method if you want to check the text data is preserved on paste after applying the conversion XSL stylesheet.
protected static boolean	containOnlyImages(AuthorAccess authorAccess, java.util.List<java.net.URL> urlList) Verify if the provided URLs are only images.
protected javax.xml.transform.stream.StreamSource	createImporterStylesheetSource(AuthorAccess authorAccess) Create the StreamSource for the main XSLT stylesheet which will do the importing (transforming from the XHTML content to content valid in the current framework).
protected javax.xml.transform.stream.StreamSource	createListsPreprocessingStylesheet(AuthorAccess authorAccess) Create the StreamSource for the XSLT stylesheet which creates nested lists from a list of para elements in the input XHTML.
protected javax.xml.transform.stream.StreamSource	createSectionsPreprocessingStylesheet(AuthorAccess authorAccess) Create the StreamSource for the XSLT stylesheet which creates nested sections from a list of para elements in the input XHTML.
protected java.net.URL	getBaseURLAtCaretPosition(AuthorAccess authorAccess) Get the base URL for the node located at caret position.
protected static java.lang.String[]	getContextPathNamesAndUris(AuthorAccess authorAccess) Get the list of parent elements of insertion point in Author document.
java.lang.String	getDescription()
protected java.lang.String	getImporterStylesheetFileName(AuthorAccess authorAccess) Get the file name of the main Author paste stylesheet.
protected java.lang.String	getListsPreprocessingStylesheetFileName(AuthorAccess authorAccess) Get the file name of the stylesheet for lists pre-processing.
protected java.lang.String	getOnlyTextContentStylesheet(AuthorAccess authorAccess) Gets an XSLT stylesheet that can extract the entire text content (and only the text content) from any input XML.
protected java.lang.String	getSectionsPreprocessingStylesheetFileName(AuthorAccess authorAccess) Get the file name of the stylesheet for sections pre-processing.
void	insertURLs(AuthorAccess authorAccess, java.util.List<java.net.URL> urls, int source) A list of URLs need to be inserted at the caret position, probably as links.
void	insertXHTMLFragment(AuthorAccess authorAccess, java.io.Reader xhtmlContentReader) Insert an XHTML fragment
static java.lang.String	simpleTransform(AuthorAccess authorAccess, java.lang.String xml, javax.xml.transform.stream.StreamSource xsl) Transform the specified XML input with the specified XSLT stylesheet using Saxon HE processor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ONLY_TEXT_CONTENT_STYLESHEET

public static final java.lang.String ONLY_TEXT_CONTENT_STYLESHEET

An XSLT stylesheet for extracting the entire text content (and only the text content) from any input XML, except the text from elements: xhtml:span[contains(@style, 'mso-list:Ignore')]

Since:

14.2

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.

See Also:

Constant Field Values

Constructor Detail

AuthorExternalObjectInsertionHandler

public AuthorExternalObjectInsertionHandler()

Method Detail

insertURLs

public void insertURLs(AuthorAccess authorAccess,
                       java.util.List<java.net.URL> urls,
                       int source)
                throws AuthorOperationException

A list of URLs need to be inserted at the caret position, probably as links.
The source of the insertion can be a paste event or a drag and drop event.
This call back is received if acceptURLs(AuthorAccess, List, int) returned true for the same source and urls list.
You can use it to link to those specific files/URLs.

Parameters:

authorAccess - The author access

urls - The list of URLs.

source - The source of the URLs, one of the AuthorExternalObjectInsertionHandler constants.

Throws:

AuthorOperationException

acceptURLs

public boolean acceptURLs(AuthorAccess authorAccess,
                          java.util.List<java.net.URL> urls,
                          int source)

Confirm that the list of URLs is interesting to this handler.
The source of the insertion can be a paste event or a drag and drop event. If the source is of drag and drop type and it is accepted, the caret will be moved to the drop position.
By default accepts the URLs from external sources if the URLs are only images and all URLs from paste events and drops from the Oxygen Project and DITA Maps Manager.

Parameters:

authorAccess - The author access.

urls - The list of URLs.

source - The source of the URLs, one of the AuthorExternalObjectInsertionHandler constants.

Returns:

true if the provided URLs are interesting.

acceptSource

public boolean acceptSource(AuthorAccess authorAccess,
                            int source)

Confirm that the source of URLs is interesting to this handler.
The source of the insertion can be a paste event or a drag and drop event. If the source is of drag and drop type and it is accepted, the caret will be moved to the drag position.
By default accepts paste sources and drags from the Oxygen Project and DITA Maps Manager.

Parameters:

authorAccess - The author access.

source - The source of the URLs, one of the AuthorExternalObjectInsertionHandler constants (that represents a paste or a drag and drop event)

Returns:

true if the insert URLs are interesting.

containOnlyImages

protected static boolean containOnlyImages(AuthorAccess authorAccess,
                                           java.util.List<java.net.URL> urlList)

Verify if the provided URLs are only images.

Parameters:

urlList - The list of URLs

Returns:

true if the URLs are only images.

insertXHTMLFragment

public void insertXHTMLFragment(AuthorAccess authorAccess,
                                java.io.Reader xhtmlContentReader)
                         throws AuthorOperationException

Insert an XHTML fragment

Parameters:

authorAccess - The author access

xhtmlContentReader - The XTHML content reader

Throws:

AuthorOperationException

Since:

12.1

getOnlyTextContentStylesheet

protected java.lang.String getOnlyTextContentStylesheet(AuthorAccess authorAccess)

Gets an XSLT stylesheet that can extract the entire text content (and only the text content) from any input XML.

Parameters:

authorAccess - The author access

Returns:

The XSLT stylesheet that keeps only the text content of input.

simpleTransform

public static java.lang.String simpleTransform(AuthorAccess authorAccess,
                                               java.lang.String xml,
                                               javax.xml.transform.stream.StreamSource xsl)
                                        throws javax.xml.transform.TransformerException,
                                               java.io.IOException

Transform the specified XML input with the specified XSLT stylesheet using Saxon HE processor.

Parameters:

authorAccess - helper object for creating the transformer

xml - the input XML of the transformation

xsl - the input XSLT of the transformation

Returns:

the result of the transformation

Throws:

javax.xml.transform.TransformerException - thrown during transformation

java.io.IOException - thrown during writing the transform result to the output string

getContextPathNamesAndUris

protected static java.lang.String[] getContextPathNamesAndUris(AuthorAccess authorAccess)

Get the list of parent elements of insertion point in Author document.

Parameters:

authorAccess - The author access

Returns:

comma-separated list of parent elements of insertion point.

createImporterStylesheetSource

protected javax.xml.transform.stream.StreamSource createImporterStylesheetSource(AuthorAccess authorAccess)

Create the StreamSource for the main XSLT stylesheet which will do the importing (transforming from the XHTML content to content valid in the current framework). The main stylesheet will be applied in a pipeline after the preprocessing stylesheets and generates the markup of the current framework (DITA, DocBook, etc).

Parameters:

authorAccess - The Author access API.

Returns:

the stylesheet which will import from XHTML to this framework. If the main stylesheet of the current framework cannot be loaded from resources a default one will be returned which keeps only the text from the input.

Since:

12.1

createSectionsPreprocessingStylesheet

protected javax.xml.transform.stream.StreamSource createSectionsPreprocessingStylesheet(AuthorAccess authorAccess)

Create the StreamSource for the XSLT stylesheet which creates nested sections from a list of para elements in the input XHTML.

Parameters:

authorAccess - The Author access API.

Returns:

the stylesheet for creating nested sections from list of para elements.

Since:

14.2

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.

createListsPreprocessingStylesheet

protected javax.xml.transform.stream.StreamSource createListsPreprocessingStylesheet(AuthorAccess authorAccess)

Create the StreamSource for the XSLT stylesheet which creates nested lists from a list of para elements in the input XHTML.

Parameters:

authorAccess - The Author access API.

Returns:

the stylesheet for creating nested lists from list of para elements.

Since:

14.2

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.

getSectionsPreprocessingStylesheetFileName

protected java.lang.String getSectionsPreprocessingStylesheetFileName(AuthorAccess authorAccess)

Get the file name of the stylesheet for sections pre-processing. It will be resolved in the context of the current class loader.

Parameters:

authorAccess - The author access API.

Returns:

the file name of the stylesheet for sections pre-processing. It will be resolved in the context of the current class loader.

Since:

14.2

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.

getListsPreprocessingStylesheetFileName

protected java.lang.String getListsPreprocessingStylesheetFileName(AuthorAccess authorAccess)

Get the file name of the stylesheet for lists pre-processing. It will be resolved in the context of the current class loader.

Parameters:

authorAccess - The author access API.

Returns:

the file name of the stylesheet for lists pre-processing. It will be resolved in the context of the current class loader.

Since:

14.2

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.

getImporterStylesheetFileName

protected java.lang.String getImporterStylesheetFileName(AuthorAccess authorAccess)

Get the file name of the main Author paste stylesheet. It will be resolved in the context of the current class loader.

Parameters:

authorAccess - The author access API.

Returns:

the file name of the main Author paste stylesheet. It will be resolved in the context of the current class loader.

Since:

12.1

getBaseURLAtCaretPosition

protected java.net.URL getBaseURLAtCaretPosition(AuthorAccess authorAccess)

Get the base URL for the node located at caret position. Usually this is the URL of the opened editor but it can vary if nodes have xml:base defined on them.

Parameters:

authorAccess - The author access

Returns:

the base URL for the node located at caret position.

checkImportedXHTMLContentIsPreservedEntirely

protected boolean checkImportedXHTMLContentIsPreservedEntirely()

Overwrite this method if you want to check the text data is preserved on paste after applying the conversion XSL stylesheet. If the data is not preserved the content will be copied without any styling and a warning will appear in the console.

Returns:

false by default.

getDescription

public java.lang.String getDescription()

Specified by:

getDescription in interface Extension

Returns:

The description of the extension.

See Also:

Extension.getDescription()