Class AuthorExternalObjectInsertionHandler

java.lang.Object
ro.sync.ecss.extensions.api.AuthorExternalObjectInsertionHandler
All Implemented Interfaces:
Extension, ExternalObjectInsertionSources
Direct Known Subclasses:
DITAExternalObjectInsertionHandler, Docbook4ExternalObjectInsertionHandler, Docbook5ExternalObjectInsertionHandler, TEI_jteiExternalObjectInsertionHandler, TEIP5ExternalObjectInsertionHandler, XHTMLExternalObjectInsertionHandler

@API(type=EXTENDABLE, src=PUBLIC) public abstract class AuthorExternalObjectInsertionHandler extends 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
  • Constructor Details

    • AuthorExternalObjectInsertionHandler

      public AuthorExternalObjectInsertionHandler()
  • Method Details

    • insertURLs

      public void insertURLs(AuthorAccess authorAccess, List<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
    • insertURLs

      public void insertURLs(AuthorAccess authorAccess, List<URL> urls, List<ReferenceType> types, 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.
      types - The type of the URL reference - if null, the type will be inferred.
      source - The source of the URLs, one of the AuthorExternalObjectInsertionHandler constants.
      Throws:
      AuthorOperationException
      Since:
      18.0
    • acceptURLs

      public boolean acceptURLs(AuthorAccess authorAccess, List<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 or binary files and all URLs from paste events and drops from the Oxygen Project and DITA Maps Manager. It calls the "acceptSource" method to check if a certain source of the operation is accepted.
      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, List<URL> urlList)
      Verify if the provided URLs are only images.
      Parameters:
      urlList - The list of URLs
      Returns:
      true if the URLs are only images.
    • containOnlyBinaryResources

      protected static boolean containOnlyBinaryResources(AuthorAccess authorAccess, List<URL> urlList)
      Verify if the provided URLs are only binary rsources.
      Parameters:
      urlList - The list of URLs
      Returns:
      true if the URLs are only binary resources.
    • insertXHTMLFragment

      public void insertXHTMLFragment(AuthorAccess authorAccess, Reader xhtmlContentReader) throws AuthorOperationException
      Insert an XHTML fragment
      Parameters:
      authorAccess - The author access
      xhtmlContentReader - The XTHML content reader
      Throws:
      AuthorOperationException
      Since:
      12.1
    • insertImportedContent

      protected void insertImportedContent(AuthorAccess authorAccess, String importedContent) throws AuthorOperationException
      Insert the content imported by applying the XSLT stylesheet directly in the document. The insertion is done schema aware.
      Parameters:
      authorAccess - The author access.
      importedContent - The imported content.
      Throws:
      AuthorOperationException
    • getOnlyTextContentStylesheet

      protected StreamSource 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.
    • getClassStylesheetResource

      protected StreamSource getClassStylesheetResource(Class clazz, String resourcePath)
      Find the stylesheet resource in the class package with the given file name.
      Parameters:
      clazz - The class where to search for the stylesheet resource
      resourcePath - The resource to find.
      Returns:
      The stylesheet resource or a default stylesheet (that ignores everything) if it cannot be found.
    • getFilterContentOfOutputStylesheet

      protected StreamSource getFilterContentOfOutputStylesheet()
      Gets an XSLT stylesheet that can filter non text content from the output XML.
      Returns:
      The XSLT stylesheet that can filter non text content from the output XML.
    • simpleTransform

      public static String simpleTransform(AuthorAccess authorAccess, String xml, String xsl) throws TransformerException, 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:
      TransformerException - thrown during transformation
      IOException - thrown during writing the transform result to the output string
    • simpleTransform

      public static String simpleTransform(AuthorAccess authorAccess, String xml, StreamSource xsl) throws TransformerException, 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:
      TransformerException - thrown during transformation
      IOException - thrown during writing the transform result to the output string
    • setParametersToTransform

      protected static void setParametersToTransform(Transformer transformer, AuthorAccess authorAccess, boolean copyWordImageResources)
      Set the parameters on the XSLT transform engine.
      Parameters:
      transformer - The XSLT transformer.
      authorAccess - The author access.
      copyWordImageResources - true to copy image resources from word document
    • getContextPathNamesAndUris

      protected static 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 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
    • getImporterStylesheetFileName

      protected 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 static 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 String getDescription()
      Specified by:
      getDescription in interface Extension
      Returns:
      The description of the extension.
      See Also: