Update: 1/22/08 This tutorial has been improved with features from our newest release. All edits and improvements are highlighted below. If you have created scripts using the old version of this page, all your code should still work.

Modifying Text

by Josh and Mauvis

Many of you have asked whether there's a way to change the text of items on your KickApps-powered pages. In response to your requests, we've begun developing full text customization functionality that will let you create branded and multilingual interfaces directly in the Affiliate Center. Until that functionality is ready, you can use JavaScript to modify the text of any HTML element on your pages.

The general strategy will be to locate the element whose text you want to change in the DOM, then find its nearest containing element that has an ID, and then use the getElementsByTagName method to find your element within this containing element. Once you've located your element in the DOM, you'll simply set its .innerHTML property to whatever you'd like it to say. To makes things easier, we have a shortcut to document.getElementById called $. Feel free to use them interchangeably.

For example, an affiliate recently asked how to change the text of the "Comments" header on media play pages. Here's how:

  1. Use Firebug to locate the Comments element in the DOM.
  2. Firebug reveals that the "Comments" text is located within an <h3> that has no ID, however its parent <div>, #ka_leftColumn, does. So the first part of our JS will be:
    3. $('ka_leftColumn').getElementsByTagName('h3')
  3. Now we're going to use the $ method to find our Comment element's <h3> within #ka_leftColumn. The getElementsByTagName method grabs all of the <h3>s that live in #ka_leftColumn and loads them into an array, so we need to tell it which <h3> to look at. To do that, all we need to do is count <h3>s until we hit the Comments <h3>. The only trick is to begin counting at "0". Lucky for us, we hit it right away: the Comments <h3> is the first <h3> within #ka_leftColumn. We tell getElementsByTagName to look at the 0th <h3> like this:
    4. $('ka_leftColumn').getElementsByTagName('h3')[0]
  4. Now all that's left is to change the word "Comments" to whatever we like--say, "Shouts". We use the innerHTML property:
    5. $('ka_leftColumn').getElementsByTagName('h3')[0].innerHTML = "Shouts";
  5. Lastly, we have to do two things before we're done with our code: make sure this code only runs on the specified page(s) using an if-statement and queing this function up using Ka.addDOMLoadEvent so that our edits only run after all the content has loaded (but before the page displays.)

    For the first isse, we can solve it in two ways: detect whether the element we want exists or detect whether we are on a certain page that we know the element is on before running our code. Both are good ways but which ones you use depends on what you want. If the element you want to modify is on more than one page and you want to modify all references, filter your logic by checking for the id first (See Using Element Detection below). Otherwise use Ka.Info.PAGE or Ka.Info.PAGETYPE to detect the current page (see Using Page Detection below and the Ka.Info tutorial for more on this method).

    6. Using Element Detection

    <script type="text/javascript">
    //check if elements container exists
    if($('ka_shoutBoxContainer')){
           // Run custom code
           $('ka_leftColumn').getElementsByTagName('h3')[0].innerHTML = "Shouts";
    }
    </script>

    Using Page Detection

    <script type="text/javascript">
    //check if we are on a play page
    if(Ka.Info.PAGETYPE == 'play'){
           //wrap our above logic in a function
           $('ka_leftColumn').getElementsByTagName('h3')[0].innerHTML = "Shouts";
    }
    </script>
  6. Lastly, we need to make sure this code only runs after the content is ready. Previously, we used timers to check for this but now we have a "DOM Ready" function that we use to que up any functions we want to run once the DOM is ready. See the example below:

    7. Using Ka.addDOMLoadEvent

    <script type="text/javascript">
    //wrap our logic in a function
    function editShoutboxContents(){
           if($('ka_shoutBoxContainer')){
                   //wrap our above logic in a function
                  $('ka_leftColumn').getElementsByTagName('h3')[0].innerHTML = "Shouts";
           }
    }
    //que the function up by using the addDOMLoadEvent method Ka.addDOMLoadEvent(editShoutboxContents);
    </script>
  7. Now all you have to do is copy this code into the <head></head> section of your Global Page Template in the Affiliate Center (under Configure > Pages).

That's all there is to it. The "Comments" heading will now read "Shouts". You should be able to use the same basic process to modify the text of any HTML element on your KickApps-powered pages. If you find some exceptions to this rule, please tell us about them in the Tutorials forum.

Update: Including double quotes in your text

canthony86 raised a great question over on the KickDeveloper Message Boards: if you add text that includes double quotes, it breaks the code. The problem is that .innerHTML uses double quotes to tell where your text starts and ends, so it gets confused if you have some extra quotes inserted along the way.

To fix this problem, you "escape" your quotes by adding a backslash before any inner double quotes (any double quotes other than the first and the last).

For example, imagine you want to add this HTML link to your page:

<a href="http://www.nytimes.com">nytimes</a>

You'd put this inside your JavaScript code:

.innerHTML="<a href=\"http://www.nytimes.com\">nytimes</a>"

Those backslashes tell the code "hey, ignore this quote for now, just add it to the page". If you're new to JavaScript, it can seem confusing, but it works!

Did you enjoy this tutorial? Have questions, comments, or want to submit one of your own? Contact us at support@kickapps.com.