Page 1 of 2

Integrate jquery

Posted: Fri Sep 05, 2014 7:42 am
by tomjohnson1492
How could I integrate this jquery stylesheet switcher functionality into my webhelp output? http://hibbard.eu/using-cookies-with-jq ... -switcher/

I tried playing around with inserting scripts into the header file, but it seems a bit problematic. I'm not sure exactly why I have to surround the script with p or br tags to make it valid. Can you provide a working demo of a webhelp output that integrates this stylesheet switcher?

Re: Integrate jquery

Posted: Fri Sep 05, 2014 11:37 am
by sorin_ristache
Hi Tom,

We will add an XSLT extension point for this type of Webhelp customization in a future version of Oxygen (probably in version 17). That means you will insert your custom JavaScript code with a custom XSLT file imported in the Oxygen Webhelp transformation.

In versions 16.0 and 16.1 (and of course in previous versions) please add a custom JavaScript file or some custom CSS code in the <head> section of the Webhelp pages by adding a <script> XHTML element or a <style> XHTML element at the end of the XSLT template with attribute name="create-js-scripts" in file OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl, something like:

Code: Select all

    <style>
             // your custom CSS style here
             .  .  .
          </style>
  </xsl:template>


For the style switcher implemented with jQuery I udnerstand that you need to add also JavaScript code in the <body> section of the pages, which you can do by inserting it inline in a <script> element in the template name="create-toc-common-file" in the same file createMainFiles.xsl, before the element <div id="header"> at line 350, something like:

Code: Select all

    <script>
      // your custom jQuery code here
      $(document).ready(function() {
      .  .  .
    </script>
               
    <div id="header">
      <div id="lHeader">
      .  .  .


The cookies plugin for jQuery is already included in the Oxygen Webhelp pages (as jquery.cookie.js), so you don't have to worry about that.


Regards,
Sorin

Re: Integrate jquery

Posted: Mon Sep 08, 2014 10:37 am
by tomjohnson1492
Thanks, I was able to get this to work. I put this in a header.xhtml file that I included in the args.hdf parameter:

`
<select id="selector">
<option value="blue">Blue</option>
<option value="green">Green</option>
<option value="red">Red</option>
</select>
`

Then I put the CSS into the file here: DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/css/webhelp_topic.css

And I put the JS into the file here: DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/js/webhelp_topic.js

I had to upload the content to a web server to see the result. Running it locally (outside of any web server) didn't show the results.

I know this question might extend beyond the scope of this forum, but how would I go about putting these changes into a plugin? Couldn't I just duplicate the css and js files, rename them, and package them into a plugin of some sorts? Is there documentation anywhere on doing that?

Thanks,

Tom

Re: Integrate jquery

Posted: Mon Sep 08, 2014 12:25 pm
by sorin_ristache
tomjohnson1492 wrote:I know this question might extend beyond the scope of this forum, but how would I go about putting these changes into a plugin? Couldn't I just duplicate the css and js files, rename them, and package them into a plugin of some sorts? Is there documentation anywhere on doing that?


The Webhelp transformation can't be extended with a plugin yet. We plan to add some extension points in a future version that will allow you to add a custom plugin that adds your custom code in the extension points.


Regards,
Sorin

Re: Integrate jquery

Posted: Mon Sep 08, 2014 10:27 pm
by tomjohnson1492
Great -- that would be an awesome update. I am pretty excited at how easy it is to integrate jquery functionality into the webhelp.

Re: Integrate jquery

Posted: Fri Sep 12, 2014 12:12 am
by tomjohnson1492
Are there any downsides to simply putting my js scripts into the webhelp_topic.js file, and my global css into the webhelp_topic.css file? Is seems to simply work that way and is easy.

Re: Integrate jquery

Posted: Fri Sep 12, 2014 9:45 am
by sorin_ristache
I suggest adding the JavaScript code to oxygen-webhelp/resources/js/toc.js and the CSS code to oxygen-webhelp/resources/css/toc.css instead of webhelp_topic.js and webhelp_topic.css if you use the internal frames version (the index.html main file). If you use the frameset version (the index_frames.html file) you can add your code to webhelp_topic.js and webhelp_topic.css.

Re: Integrate jquery

Posted: Fri Sep 12, 2014 10:08 am
by tomjohnson1492
I tried adding my script to toc.js, but it doesn't work. That's okay b/c I actually play to use index_frames.html instead anyway (due to a salesforce integration).

Check out the jquery scripts in action here: http://idratherbewriting.com/ditaqrg. Look in the demos folder. The content selector one is here:

Code: Select all

http://idratherbewriting.com/ditaqrg/#demo_content_selector.html


It works by hiding or showing content tagged with certain attributes. The only problem is that a toc item that also is tagged with an attribute doesn't get hidden or shown.

2 questions:

1. How can I allow attributes tagged in a ditamap toc to carry over to the oxygen webhelp output? The tweak I made (described here: http://idratherbewriting.com/ditaqrg/#jquery_content_selector.html) to the dita2htmllmpl.xsl file didn't have any effect on the ditamap toc in the webhelp output. I actually added a tag to one of the toc items, but none of the attributes come through.

2. Even if the attribute were to carry over into the output with the ditamap toc items, isn't that content in another frame and therefore immune to scripts integrated into the main frame (webhelp_topic)?

Basically, the problem is that some whole topics may pertain only to php, and I want to hide that item in the toc when a user selects php in the content selector menu.

Re: Integrate jquery

Posted: Fri Sep 12, 2014 3:52 pm
by sorin_ristache
tomjohnson1492 wrote:I tried adding my script to toc.js, but it doesn't work. That's okay b/c I actually play to use index_frames.html instead anyway (due to a salesforce integration).


oxygen-webhelp/resources/js/toc.js holds the JavaScript code for processing the Table of Contents tree and is loaded both by index.html and by the left-side frame of index_frames.html where the Table of Contents tree is displayed (the frame with id="tocwin" in index_frames.html). This is why I recommended you to add your JavaScript code to oxygen-webhelp/resources/js/toc.js.

Can you tell us a little more how far you could trace into the issue? Does the TOC item that you want to hide or show has the required attribute which you query and process in your jQuery code? Is your jQuery code called at all?

tomjohnson1492 wrote:It works by hiding or showing content tagged with certain attributes. The only problem is that a toc item that also is tagged with an attribute doesn't get hidden or shown.


Please make sure first that the attribute(s) that you need to process in the jQuery code are there on the TOC items that need to be hidden/displayed.

tomjohnson1492 wrote:1. How can I allow attributes tagged in a ditamap toc to carry over to the oxygen webhelp output? The tweak I made (described here: http://idratherbewriting.com/ditaqrg/#jquery_content_selector.html) to the dita2htmllmpl.xsl file didn't have any effect on the ditamap toc in the webhelp output. I actually added a tag to one of the toc items, but none of the attributes come through.


To carry over a custom attribute from a <topicref> in the DITA map to a TOC item in the output Webhelp page, I suggest using the outputclass attribute: just set an outputclass attribute on the <topicref> elements that you need to process in your jQuery code, and the Webhelp transformation carries it over as the class attribute set on the corresponding TOC item in the output Webhelp page. The outputclass attribute can have any custom value you want in the DITA map. It will be exported as a class attribute on the TOC item corresponding to that <topicref> element.

An alternative would be to add your own attribute to <topicref> elements instead of outputclass but in this case you need to pass it through by modifying the stylesheets OXYGEN_DIR\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\dita\tocDita.xsl and OXYGEN_DIR\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\dita\map2webhelptoc.xsl. I can give you more details if you want to go this route but I suggest the first alternative (the outputclass attribute).

tomjohnson1492 wrote:2. Even if the attribute were to carry over into the output with the ditamap toc items, isn't that content in another frame and therefore immune to scripts integrated into the main frame (webhelp_topic)?


If you use index_frames.html then the TOC items are all located in the same frame where toc.js is included, which is the frame with id="tocwin" in index_frames.html. If you decide to use index.html then the TOC items are located directly in the index.html page (not in a frame, and not in the right-side <iframe> with the DITA topic content). So I think toc.js would be an appropriate place for the custom jQuery code.

Re: Integrate jquery

Posted: Wed Sep 17, 2014 2:50 am
by tomjohnson1492
Adding the script in toc.js, as well as adding outputclass attributes on the TOC items, doesn't seem to work. The TOC items don't get hidden when they should.

I have tried quite a few things without success.

Here's what I need to happen.

1. I need this script to appear on the page:

`<script>
function removeAddBodyClass(){
$("body").removeClass();
$("body").addClass($.cookie('body_colour'));
}

removeAddBodyClass();

$("#selector").change(function(){
$.cookie('body_colour', $("#selector").val());
removeAddBodyClass();
});

$("#selector > option").each(function() {
if($(this).val() == $.cookie('body_colour')){
$(this).attr("selected","selected");
}
});
</script>
`
2. I need these classes to be included:

`
/*styles needed for content selector*/

/* by default, java is shown because on initial page load, we don't want blank spaces with no code.*/

/*hide other languages*/
body [data-platform *= "cpp"]{
display:none;
}

body [data-platform *= "dotnet"]{
display:none;
}

body [data-platform *= "php"]{
display:none;
}

/*when java is selected...*/

body.java [data-platform *= "java"]{
display:block;
}

body.java .ph[data-platform *= "java"]{
display:inline;
}


body.java #tree li.cpp {display:none;}
body.java #tree li.php {display:none;}
body.java #tree li.dotnet {display:none;}

/*when cpp is selected...*/
body.cpp [data-platform *= "cpp"]{
display:block;
}

body.cpp .ph[data-platform *= "cpp"]{
display:inline;
}

body.cpp [data-platform *= "java"]{
display:none;
}

body.cpp #tree li.dotnet {display:none;}
body.cpp #tree li.php {display:none;}
body.cpp #tree li.java {display:none;}

/*when dotnet is selected...*/

body.dotnet [data-platform *= "dotnet"]{
display:block;
}

body.dotnet .ph[data-platform *= "dotnet"]{
display:inline;
}

body.dotnet [data-platform *= "java"]{
display:none;
}

body.dotnet #tree li.cpp {display:none;}
body.dotnet #tree li.php {display:none;}
body.dotnet #tree li.java {display:none;}

/*when php is selected...*/
body.php [data-platform *= "php"]{
display:block;
}

body.php .ph[data-platform *= "php"]{
display:inline;
}

body.php [data-platform *= "java"]{
display:none;
}


body.php #tree li.cpp {display:none;}
body.php #tree li.dotnet {display:none;}
body.php #tree li.java {display:none;}
`

3. I need this selector to be included:

`<p id="progSelector">Select your programming language: <select id="selector">
<option value="java">Java</option>
<option value="dotnet">.NET</option>
<option value="cpp">C++</option>
<option value="php">PHP</option>
</select></p>
`

4. When a user selects one of the options in the selector, such as dotnet, here's what should happen:

dotnet should be added as a class to body.
the styles under the dotnet section in the stylesheet should kick in
and here's the part that's not working: items in the table of contents with certain classes should be hidden.

Everything works find in the main body window, but nothing is happening in the TOC pane.

Can you help me get this working? I have come to the end of my technical prowess here and can't solve this without your help. Thanks so much.

Re: Integrate jquery

Posted: Thu Sep 18, 2014 1:23 am
by tomjohnson1492
I am thinking of throwing in the towel on this one. Can you solve it? There doesn't seem to be a way to hide topics from both the main content window and the TOC.

Re: Integrate jquery

Posted: Thu Sep 18, 2014 8:59 am
by sorin_ristache
tomjohnson1492 wrote:Adding the script in toc.js, as well as adding outputclass attributes on the TOC items, doesn't seem to work. The TOC items don't get hidden when they should.


Please note that the attribute in the output WebHelp page is class, and the value is the same as the value of outputclass in the source XML file.

tomjohnson1492 wrote:1. I need this script to appear on the page:


Could you add this JavaScript code in the WebHelp pages successfully?

tomjohnson1492 wrote:2. I need these classes to be included:


Could you add this CSS code in the WebHelp pages successfully?

tomjohnson1492 wrote:Everything works find in the main body window, but nothing is happening in the TOC pane.


Do you mean that you added successfully the jQuery code and the CSS code in the WebHelp pages but the custom code added in the WebHelp page does not have the intended effect?

Re: Integrate jquery

Posted: Thu Sep 18, 2014 9:58 am
by tomjohnson1492
Yes, I understand that output class converts to class on rendering to html.

I put together a demo of the content selector here: http://idratherbewriting.com/ditaqrg/#d ... ector.html

That section also details the script and classes I'm using.

A few items in the TOC (in that same content selector folder) have classes as their attributes but they aren't affected by the language toggle when I make a selection.

Try following the instructions in that section on how to set up the content selector and see if you can make the TOC items get hidden.

If you can't figure this out, I'll probably have to revert to separate files for everything, which I really don't want to do. Thanks.

Tom

Re: Integrate jquery

Posted: Wed Nov 26, 2014 11:01 am
by Radu
Hi,

About this remark:

That's okay b/c I actually play to use index_frames.html instead anyway (due to a salesforce integration).


We made some changes to the WebHelp output which will be distributed with Oxygen 17.0 (spring of 2015) and it's index.html will be embeddable in iframes. So you will not have to use the index_frames.html to embed it in an external iframe. If you want just contact us and we'll try to provide some changes for you to test on your side.

Regards,
Radu

Re: Integrate jquery

Posted: Wed Nov 26, 2014 7:53 pm
by tomjohnson1492
Cool. Yes, I'd like to try it out. Feel free to reach out to me with details. http://idratherbewriting.com/contact/

Re: Integrate jquery

Posted: Thu Nov 27, 2014 10:52 am
by sorin_ristache
Hi,

I just sent you by email the modifications for Oxygen 16.1.

Re: Integrate jQuery

Posted: Tue Jun 23, 2015 5:35 pm
by Frank Ralf
Hi Sorin,

I tried to add my custom JavaScript to com.oxygenxml.webhelp/xsl/createMainFiles.xsl as you recommended above. However, this adds the JavaScript to the <head> section of the main HTML output of the WebHelp but not the one for each topic inside the <iframe> element. For this I had to add my custom JavaScript to com.oxygenxml.webhelp/xsl/dita/desktop/common.xsl instead (<xsl:template name="jsAndCSS">), using the syntax found in that file:

Code: Select all

<xsl:element name="script" namespace="{$namespace}">
    <xsl:attribute name="type">text/javascript</xsl:attribute>
    <xsl:attribute name="src">
        <xsl:value-of select="concat($PATH2PROJ, 'oxygen-webhelp/resources/js/my-custom-javascript.js')" />
    </xsl:attribute>
    <xsl:comment/>
</xsl:element>


Is this the correct approach? Or am I missing something? (This is oXygen 16.1.)

Kind regards,
Frank

Re: Integrate jquery

Posted: Wed Jun 24, 2015 10:33 am
by Frank Ralf
Just another thought. Could it be that my jQuery was just missing the $(document).ready(function () {...}); function so my JavaScript wasn't loaded?

Frank

Re: Integrate jquery

Posted: Wed Jun 24, 2015 3:06 pm
by bogdan_cercelaru
Hi Frank,

If you add it to createMainFiles.xsl, your custom JavaScript will be added only to the main files (index.html, index_frames.html and toc.html).
If you want to add it to the topics, you can do that in common.xsl, in the template you mentioned (jsAndCSS).
Note that common.xsl does not cover the main files.

Frank Ralf wrote:Just another thought. Could it be that my jQuery was just missing the $(document).ready(function () {...}); function so my JavaScript wasn't loaded?

What was the problem and what is the desired result?

Regards,
Bogdan

Re: Integrate jquery

Posted: Thu Jun 25, 2015 12:08 pm
by Frank Ralf
Hi Bogdan,

Thanks for your quick reply and for confirming my findings. The jQuery thing has nothing to do with this question, my bad. But I have a follow-up question:

Instead of putting my custom JavaScript in the WebHelp plugin folder I'd prefer to use a separate folder. However, looking at the code in the XSL it seems as if the JavaScript path is dynamically build for each topic so this might not be so easy:

Code: Select all

<xsl:value-of select="concat($PATH2PROJ, 'oxygen-webhelp/resources/js/my-custom-javascript.js')" />


Is there a way to separate my custom code from oXygen's one?

Kind regards,
Frank

Re: Integrate jquery

Posted: Thu Jun 25, 2015 3:27 pm
by bogdan_cercelaru
You can use a custom build file to copy your resources to the output folder. You can find below an example of this file:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="dist">
    <!--The DITA OT default build file-->
    <import file="build.xml"/>
   
    <target name="dist">
        <!--Call the DITA OT default target-->
        <antcall target="init"/>
       
        <!-- Copy my-custom-javascript.js from Dita Map folder to output folder -->
        <copy file="${basedir}/my-custom-javascript.js" tofile="${output.dir}/oxygen-webhelp/resources/js/my-custom-javascript.js" />
    </target>
</project>

This example assumes that your custom JavaScript file is located in the same folder as your ditamap (source) file.
You can specify a custom build file to be used in DITA-OT transformations by editing the transformation scenario that you are using. In the Advanced tab you should change the Custom build file path to point to the custom build file.
from Author for DITA / DITA-OT Customization / Using Your Custom Build File

Regards,
Bogdan

Re: Integrate jquery

Posted: Thu Jun 25, 2015 6:24 pm
by Frank Ralf
Hi Bogdan,

Thanks for this pointer. I will give it a try and report back :-)

Frank

Re: Integrate jquery

Posted: Fri Jul 17, 2015 5:50 pm
by Frank Ralf
Hi,

In com.oxygenxml.webhelp/xsl/dita/desktop/common.xsl I found the following code. Can I make use of this via the args.hdf parameter in the WebHelp transformation scenario? If so, how?

Code: Select all

<!-- Custom JavaScript code set by param webhelp.head.script -->
<xsl:if test="string-length($WEBHELP_HEAD_SCRIPT) > 0">
  <xsl:value-of select="unparsed-text($WEBHELP_HEAD_SCRIPT)" disable-output-escaping="yes" />
</xsl:if>


Kind regards,
Frank

Re: Integrate jquery

Posted: Mon Jul 20, 2015 2:53 pm
by bogdan_cercelaru
Hi,

You can use webhelp.head.script parameter to add your custom JavaScript in the generated WebHelp pages. Note that your code (content of the file passed to this parameter) will be copied to every generated pages, in the <head> element, right before the <body> element.
The file must contain valid XHTML. A common practice is to place all content into a <script> element.

To use the webhelp.head.script parameter you should edit the DITA Map WebHelp transformation scenario and add this by pressing the New button from the Parameters tab. The value of this parameter must be an URL (e.g.: file:///path/to/file.js).

Regards,
Bogdan

Re: Integrate jquery

Posted: Tue Jul 21, 2015 11:38 am
by Frank Ralf
Hi Bogdan,

Many thanks for these pointers.

Kind regards,
Frank

Re: Integrate jquery

Posted: Wed Jul 22, 2015 1:52 pm
by Frank Ralf
Hi Bogdan,

I've tried your approach (oXygen 16.1) but I get the following error message:

Code: Select all

Invalid relative URI:
Illegal character in opaque part at index 2:
\DITA-OT\plugins\com.oxygenxml.webhelp\oxygen-webhelp\resources\js\my_webhelp.js


The HTML file passed to the webhelp.head.script parameter contains the following code:

Code: Select all

<script src="my_webhelp.js" type="text/javascript"><!-- My JavaScript --></script>


I tried both with putting the JavaScript and HTML file within the oXygen WebHelp plugin folder (DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/js/) and outside.

For comparison, I also tried the same with the args.hdf parameter of the WebHelp transformation. In this case, the transformation runs through and inserts the reference to my JavaScript file in the <head> section directly after the <title> element. However, the JavaScript file itself doesn't get copied over to the output.

Do you have any idea what I am missing?

Kind regards,
Frank

Re: Integrate jquery

Posted: Wed Jul 22, 2015 1:54 pm
by Frank Ralf
Just found http://stackoverflow.com/questions/2856 ... xexception

Basically "C:\Documents and Settings\All Users\.SF\config\sd.xml" is a pathname, and not a valid URI.


Will try that and report back.

Frank

Re: Integrate jquery

Posted: Wed Jul 22, 2015 2:21 pm
by Frank Ralf
That did the trick: Changing the parameter value to a real URL works:

Code: Select all

file:/path/to/webhelp_head_script.html
.

I made the following observations:

- My custom JS file has to be placed in the webhelp plugin folder (DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/js/) to be copied over to the output.
- I had to manually adapt the relative path to the JS file in the <script> element to make it work:

Code: Select all

<script src="../oxygen-webhelp/resources/js/my_other_webhelp.js" type="text/javascript"></script>
.
- I'm not sure this approach will work with topics in different subfolders because the inserted <script> element seems to be static.

Frank

Re: Integrate jquery

Posted: Wed Jul 22, 2015 4:55 pm
by bogdan_cercelaru
Hello,

Probably I was not clear enough. Your custom JavaScript file should contain only the JavaScript code between <script> tags (you don't need to specify a "src" attribute for the "script" element). Your custom JavaScript file that will be referenced by the "webhelp.head.script" parameter should look like:

Code: Select all

<script>
/**
 * JavaScript content - the content of "my_webhelp.js" from your example
 */
</script>


Regards,
Bogdan

Re: Integrate jquery

Posted: Wed Jul 22, 2015 6:56 pm
by Frank Ralf
Thanks for the pointer, Bogdan. And sorry for my misunderstanding. I will try that and report back.

Kind regards,
Frank