1a. Getting to the object

Update: February 11th, 2010

This article the first of The Power of Content Editor WebPart series. Other parts:

Getting the tools

OK. Our DOM is loaded and ready to be manipulated. Now what? The first order of business is to identify the element we wish to work with (read: manipulate). By "work with" I mean change it in any way (hide, move, change size, appearance, add content or behavior to it,…)

A very handy tool for visually selecting the element comes with Internet Explorer 8. They’re called Developer tools. If you don’t have the option of updating IE to 8 or higher, with IE7 you can use Developer Toolbar for Internet Explorer. If you don’t have option to use IE, FireFox’s has a FireBug alternative. Or you can use the MODI v2 bookmarklet. We’ll be using Developer tools in this series.

To activate developer tools in IE, press F12 or use the "Tools" – "Developer tools" menu.

image image

The problem

Now we’re ready to get our object. For our first demo we’ll change the list description to be able to use HTML tags. Let’s review the problem first:

If we use HTML in a list description, we can see that SharePoint supports partial HTML in list descriptions. What do I mean by that? If we enter HTML in list description as follows:

HTML in list description

The HTML will be partially rendered in some places (like in list settings and "All site content" page. But in the List View the HTML will be completely unparsed.

Partial HTML rendering in list description image

Now it’s time to apply JavaScript to change this. The reason that HTML is "unparsed" is because the HTML tags get HTML "escaped" ("<" changes to "&lt;" and ">" changes to "&gt;"). To fix this we will apply the simple script to change this back:

function deHTML(inputString) {
   inputString = inputString.replace(/</gi,'<');
   inputString = inputString.replace(/>/gi,'>');
   return inputString;
}

Getting to the element

Now we need to get the object. Here’s where the IE developer tools come in handy. A lot of SharePoint HTML DOM elements (tables, cells, layers, spans) have a unique ID. This ID is written in the id attribute If they have the unique ID we can select them by using the following code

document.getElementById('[element-id]');

Note that the code IS case-sensitive. So how to get to know if the element has unique ID and which is it? We can discover this either by searching through document’s source code or better use the IE developer tools. Once the page is loaded, we open the developer tools, click the selector icon:

Select element by click tool

Next we click on the part of the page we want selected.

image

We can see the HTML DOM element highlighted with a blue border. Now we can check the corresponding HTML in the lower part of IE Developer Toolbar:

image

Sometimes the selected element isn’t the one we want to manipulate. We can browse the DOM elements also by expanding, collapsing and clicking the nodes in the lower-left part of IE Developer Toolbar.

image

Expanding the <div> element we discover that this is the element we wish to manipulate because it contains text we want to change. (It doesn’t contain any child elements).

Unfortunately this element doesn’t have a unique ID. If it did the HTML would show (and IE developer toolbar would also display" <div id="ms-listdescription" class="ms-listdescription">

So in a lot of cases the element also has a unique CSS class (ms-listdescription) in our case. Because native in JavaScript we can’t select elements by its class name, and we don’t use jQuery (jQuery can select elements by its css class name), we’ll add an additional function to help us select the elements. This function uses

document.getElementsByTagName('[tag-name]')

which returns an array of all elements with specified tag name. From that array we have to filter out only the ones with CSS class that we desire. So we use the following function:

function getElementsByCssClass(sTagName, sClassName) {
    var results = new Array();
    var allTagElements = document.getElementsByTagName(sTagName);
    for (i = 0; i < allTagElements.length; i++) {
        if(allTagElements[i].className == sClassName) results.push(allTagElements[i]);
    }
    return results;
}

Now let’s insert the CEWP into the page and add the code we prepared untill now – function getElementsByCssClass and function deHTML.

CEWP inserted image

Now let’s test how many elements are there with the CSS class "ms-listdescription". Just before the </script> at the end of the code add the following command:

alert(getElementsByCssClass("div", "ms-listdescription").length);

and we should get the following alert:

image

Great so there is only one HTML DOM element with CSS class "ms-listdescription".

So we have successfully selected our DOM element. Now let’s change its inner HTML using the following code:

getElementsByCssClass("div", "ms-listdescription")[0].innerHTML = deHTML(getElementsByCssClass("div", "ms-listdescription")[0].innerHTML);

and we get the result:

image

You may notice some space between the list description and the list view. We can remove this by pure CSS. Let’s select the element that is making this space and discover its CSS class name.

image

Now we will adapt the CSS rule for that class using the following:

to hide the space created by new webpart.

To sum it all up

There are multiple ways of getting an element we want to work with from SharePoint’s enormous HTML DOM. First we get its ID, CSS class name or tag name with IE Developer Tools and then we get it with JavaScript. There are certain native functions that do this job, like

  • document.getElementById – which returns the object with given unique ID
  • document.getElementsByName – which returns an array of objects with given name in its attribute.
  • document.getElementsByTagName – which returns an array with all the elements that have the specified tag name.

And if the element we are trying to reach doesn’t have a unique ID or name or there are too many elements with the same tag name, we can create our own support function, like getElementByCssClass, which returns an array of elements with the specified tag AND css class name. We’ll get to know another function later in the series, which returns object by its title, but let’s not get ahead of ourselves.

An important thing to note is also that when the function returns an array of elements, even if that array contains only one element, we always have to use index with the results for example (getElementsByCssClass("div", "ms-listdescription")[0]).

If getting to the object is still quite tough, because it doesn’t have any ID, Name or  Class Name, there are more ways of getting to the object by traversing the DOM. We’ll get to know this in next parts of this series.

The complete code we used in this demo is as follows:



Other articles from this series:

TOP