Integrate jquery

<oXygen/> general issues.
tomjohnson1492
Posts: 132

Integrate jquery

Fri Sep 05, 2014 7:42 am

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?
sorin_ristache
Posts: 4144

Re: Integrate jquery

Fri Sep 05, 2014 11:37 am

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
tomjohnson1492
Posts: 132

Re: Integrate jquery

Mon Sep 08, 2014 10:37 am

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
sorin_ristache
Posts: 4144

Re: Integrate jquery

Mon Sep 08, 2014 12:25 pm

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
tomjohnson1492
Posts: 132

Re: Integrate jquery

Mon Sep 08, 2014 10:27 pm

Great -- that would be an awesome update. I am pretty excited at how easy it is to integrate jquery functionality into the webhelp.
tomjohnson1492
Posts: 132

Re: Integrate jquery

Fri Sep 12, 2014 12:12 am

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.
sorin_ristache
Posts: 4144

Re: Integrate jquery

Fri Sep 12, 2014 9:45 am

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.
Regards,
Sorin

<oXygen/> XML Editor Support
tomjohnson1492
Posts: 132

Re: Integrate jquery

Fri Sep 12, 2014 10:08 am

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.
sorin_ristache
Posts: 4144

Re: Integrate jquery

Fri Sep 12, 2014 3:52 pm

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.
Regards,
Sorin

<oXygen/> XML Editor Support
tomjohnson1492
Posts: 132

Re: Integrate jquery

Wed Sep 17, 2014 2:50 am

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.
tomjohnson1492
Posts: 132

Re: Integrate jquery

Thu Sep 18, 2014 1:23 am

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.
sorin_ristache
Posts: 4144

Re: Integrate jquery

Thu Sep 18, 2014 8:59 am

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?
Regards,
Sorin

<oXygen/> XML Editor Support
tomjohnson1492
Posts: 132

Re: Integrate jquery

Thu Sep 18, 2014 9:58 am

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
Radu
Posts: 5749

Re: Integrate jquery

Wed Nov 26, 2014 11:01 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
tomjohnson1492
Posts: 132

Re: Integrate jquery

Wed Nov 26, 2014 7:53 pm

Cool. Yes, I'd like to try it out. Feel free to reach out to me with details. http://idratherbewriting.com/contact/
sorin_ristache
Posts: 4144

Re: Integrate jquery

Thu Nov 27, 2014 10:52 am

Hi,

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

<oXygen/> XML Editor Support
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jQuery

Tue Jun 23, 2015 5:35 pm

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
Frank Ralf
parson AG
www.parson-europe.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Wed Jun 24, 2015 10:33 am

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

Frank
Frank Ralf
parson AG
www.parson-europe.com
bogdan_cercelaru
Posts: 205

Re: Integrate jquery

Wed Jun 24, 2015 3:06 pm

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
Bogdan Cercelaru
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Thu Jun 25, 2015 12:08 pm

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
Frank Ralf
parson AG
www.parson-europe.com
bogdan_cercelaru
Posts: 205

Re: Integrate jquery

Thu Jun 25, 2015 3:27 pm

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
Bogdan Cercelaru
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Thu Jun 25, 2015 6:24 pm

Hi Bogdan,

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

Frank
Frank Ralf
parson AG
www.parson-europe.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Fri Jul 17, 2015 5:50 pm

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
Frank Ralf
parson AG
www.parson-europe.com
bogdan_cercelaru
Posts: 205

Re: Integrate jquery

Mon Jul 20, 2015 2:53 pm

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
Bogdan Cercelaru
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Tue Jul 21, 2015 11:38 am

Hi Bogdan,

Many thanks for these pointers.

Kind regards,
Frank
Frank Ralf
parson AG
www.parson-europe.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Wed Jul 22, 2015 1:52 pm

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
Frank Ralf
parson AG
www.parson-europe.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Wed Jul 22, 2015 1:54 pm

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
Frank Ralf
parson AG
www.parson-europe.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Wed Jul 22, 2015 2:21 pm

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
Frank Ralf
parson AG
www.parson-europe.com
bogdan_cercelaru
Posts: 205

Re: Integrate jquery

Wed Jul 22, 2015 4:55 pm

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
Bogdan Cercelaru
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
Frank Ralf
Posts: 367
Location: Hamburg

Re: Integrate jquery

Wed Jul 22, 2015 6:56 pm

Thanks for the pointer, Bogdan. And sorry for my misunderstanding. I will try that and report back.

Kind regards,
Frank
Frank Ralf
parson AG
www.parson-europe.com

Return to “Other Issues”

Who is online

Users browsing this forum: No registered users and 0 guests