Oxygen webhelp folder structure

urbanrobots
Posts: 79
Location: San Francisco

Oxygen webhelp folder structure

Mon Oct 09, 2017 11:39 pm

Hi,

We're using the Oxygen Webhelp plugin (classic, for now). Is it possible to control the output folder structure? For example, we'd like for everything to render in a folder and for the output to show just one file, index.html, (and a folder of everything else) when they open the HTML output.

Thanks,
- Nick
ionela
Posts: 141

Re: Oxygen webhelp folder structure

Tue Oct 10, 2017 2:16 pm

Hello,

Unfortunately, currently it is not possible to control or modify the structure of the WebHelp output folder.

Regards,
Ionela
Ionela Istodor
oXygen XML Editor and Author Support
urbanrobots
Posts: 79
Location: San Francisco

Re: Oxygen webhelp folder structure

Tue Oct 10, 2017 6:01 pm

Hi lonela,
Can you give me a hint as to where this might be controlled?

Take care,
-Nick
ionela
Posts: 141

Re: Oxygen webhelp folder structure

Wed Oct 11, 2017 2:59 pm

Hi Nick,

The WebHelp output structure is controlled also by the DITA-OT engine not only by oXygen XML Webhelp plugin.
However, you could achieve this using an additional HTML file (e.g. index.html) placed outside the generated webhelp output folder (e.g. webhelp). This HTML file should contain only a JavaScript that redirects the client browser to the WebHelp "index.html" file:

Code: Select all

<html>
 <head>
  <script>
   var newLocation = window.location.href.replace('index.html', 'webhelp/index.html');
   window.location.href = newLocation;
  </script>
 </head>
</html>

This could be automated using a custom build file that moves all WebHelp generated files into a new directory and creates this "index.html" file that will be placed on the same level with the new directory. You can find more information about using the custom build file here:
https://www.oxygenxml.com/doc/versions/19.1/ug-editor/topics/dita-map-use-your-own-build-file.html

Regards,
Ionela
Ionela Istodor
oXygen XML Editor and Author Support
urbanrobots
Posts: 79
Location: San Francisco

Re: Oxygen webhelp folder structure

Thu Oct 12, 2017 2:54 am

Hi lonela,
Thanks a lot!
We're using the standalone Oxygen Webhelp plugin to generate this output, not Oxygen XML Editor.

Where do I create the extension point for com.oxygenxml.webhelp?

As an experiment, I created a custom plugin with this project element:

Code: Select all

<project basedir="." name="Cleanup output">

        <move todir="${output.dir}${file.separator}XXXXXXXX" includeEmptyDirs="yes" verbose="true">
            <fileset dir="${output.dir}">
                <include name="**/*.*"/>
            </fileset>
        </move>
</project>


(XXXXXXXX is the new folder name used for testing)

However, this runs the logic many times, and even at the beginning of the publish... If I include a target element to control the order then the move command never gets initiated. I think it's because the "cleanup-final-output" target is not properly called from the Oxygen webhelp.

Code: Select all

  <target name="cleanup-final-output">
        <echo>It worked!</echo>
        <move todir="${output.dir}${file.separator}XXXXXXXX" includeEmptyDirs="yes" verbose="true">
            <fileset dir="${output.dir}">
                <include name="**/*.*"/>
            </fileset>
        </move>
    </target>


I'm sure the issue is something quite simple! I'm just unfamiliar with extension points.

Thanks for your time.

Take care,
- Nick
ionela
Posts: 141

Re: Oxygen webhelp folder structure

Tue Oct 17, 2017 10:12 am

Hi,

As far as we know it is not possible to create an extension point for oXygen XML WebHelp plugin in order to change the WebHelp output structure.

Regards,
Ionela
Ionela Istodor
oXygen XML Editor and Author Support
urbanrobots
Posts: 79
Location: San Francisco

Re: Oxygen webhelp folder structure

Thu Oct 26, 2017 2:46 am

Hi Ionela,

Thanks for your help.

I modified two files in the Oxygen Webhelp plugin and generated a folder structure that looks like this:

- resources (this is a folder)
- documentation.html (this is a redirect to resources/index.html)

This way, the customer opens the html folder and quickly knows how to access the documentation.

The changes are:

1. Update com.oxygenxml.webhelp/build.xml so that <target name = "create-main-files">, change the OUTPUTDIR parameter to a value of: "${output.dir}/resources".

Code: Select all

  <target name="create-main-files">
    <property name="args.create.main.files.xsl" value="${base.dir}/xsl/createMainFiles_dita.xsl"/>
    <xslt processor="trax"
            in="${input.dir}/toc.xml"
            out="${output.dir}/dummy.html"
            style="${args.create.main.files.xsl}"
            force="yes">
      <factory name="net.sf.saxon.TransformerFactoryImpl"/>
      <param name="TOC_XML_FILEPATH" expression="${input.dir}/toc.xml"/>
      <param name="INDEX_XML_FILEPATH" expression="${input.dir}/index.xml"/>
      <param name="XHTML_FOLDER" expression="${input.dir}"/>
     
      <!-- this change -->
      <param name="OUTPUTDIR" expression="${output.dir}/resources/"/>
     
      <param name="BASEDIR" expression="${base.dir}"/>
      <param name="DEFAULTLANG" expression="${args.default.language}" if="args.default.language"/>
    </xslt>
    .
    .
    .
    </target>
 


2. Update com.oxygenxml.webhelp/xsl/createMainFiles.xsl :

a) Add a new template called "create-starthere-file". (I decided to use metadata instead of JavaScript for the redirect.)

Code: Select all

<xsl:template name="create-starthere-file">
  <xsl:result-document href="../{concat('documentation', $OUTEXT)}" method="xhtml" indent="no"
    encoding="UTF-8" doctype-system="about:legacy-compat" omit-xml-declaration="yes"
    exclude-result-prefixes="#all">
   
      <html lang="en">
        <meta HTTP-EQUIV="REFRESH" content="0; url=resources/index.html"/>
      </html>
   
  </xsl:result-document>
</xsl:template>


Note: The @href attribute includes a ../ to push the result document up one level above the output directory of everything else.


b) Call the "create-starthere-file" template from the "create-main-files" template.

Code: Select all

  <xsl:template name="create-main-files">
    <xsl:param name="toc"/>
    <xsl:param name="title"/>
    <xsl:call-template name="create-toc-frames-file">
      <xsl:with-param name="toc" select="$toc"/>
      <xsl:with-param name="title" select="$title"/>
    </xsl:call-template>
    <xsl:call-template name="create-toc-noframes-file">
      <xsl:with-param name="toc" select="$toc"/>
      <xsl:with-param name="title" select="$title"/>
    </xsl:call-template>
    <xsl:call-template name="create-index-file">
      <xsl:with-param name="toc" select="$toc"/>
      <xsl:with-param name="title" select="$title"/>
    </xsl:call-template>
   
    <!-- this change -->
   <xsl:call-template name="create-starthere-file"/>
     
   
  </xsl:template>




That's it! I'm sure you know a more "correct" way to accomplish this output structure, but these modifications seems to work okay for now. I still want to flatten the file hierarchy so that all topics appear in just a topics folder instead of the nested structure of the input, but that's a later project.

Thanks for your time.

Take care,
- Nick

Return to “DITA (Editing and Publishing DITA Content)”

Who is online

Users browsing this forum: Bing [Bot] and 0 guests