Continuing from part 1 of this series, the next few methods in WinJS to look at are WinJS.Utilities.data and WinJS.Utilities.convertToPixels.
WinJS.Utilities.data is documented as “gets a data value associated with the specific element.” The data value is always an object and is attached to the element using a property name of _msDataKey. So WinJS.Utilities.data(<element>) always just gives you back that object, or creates one if one doesn’t yet exist. You can then add properties to that object, or retrieve them. Basically this is a tidy way to attach extra data to an arbitrary element knowing that you won’t interfere with the element otherwise. WinJS uses this internally in various places.
WinJS.Utilities.convertToPixels sounds fancier than it is. It’s just a helper to convert a CSS positioning string for an element to a real number. That is, in CSS you often use values suffixes like “px” and “em” and so on that, of course, aren’t values that are meaningful in any computations. This function converts those values to a meaningful number of pixels. With “px” values, or something without suffixes, it’s easy–just pass it to parseInt which will strip “px” automatically if it’s there. For other CSS values–basically anything that starts with a numerical value, what this function does it just assign the value to the elements left property (saving the prior value so nothing gets altered), then reads back the elements pixelLeft property. In other words, it lets the DOM engine handle the conversion which will produce 0 if the value isn’t convertible.
Along these same lines are the following WinJS.Utilities methods:
- getRelativeLeft: gets the left coordinate of an element relative to a specified parent. Note that the parent doesn’t have to be the immediate parent, but can be any other node in the element’s tree. This function then basically takes the offsetLeft property of the element and keeps subtracting off the offsetLeft of the next element up until the designated ancestor is reached.
- getRelativeTop: does the same thing as getRelativeLeft except with offsetTop.
- getContentWidth: returns the offsetWIdth of an element minus the values of borderLeftWidth, borderRightWidth, paddingLeft, and paddingRight, which results in the actual width of the area where content is shown.
- getTotalWidth: returns the offsetWIdth of the element plus the marginLeft and marginRight values.
- getContentHeight: returns the offsetHeight of an element minus the values of borderTopWidth, borderBottomWidth, paddingTop, and paddingBottom, which results in the actual height of the area where content is shown.
- getTotalHeight: returns the offsetHeight of the element plus the marginTop and marginBottom values.
- getPosition: returns an object with properties of left, top, width, and height properties of an element relative to the topmost element in the tree (up to document or body), taking scroll postions into account.
Again, it’s helpful to take a look in base.js for the implementation of these functions so you can see what they’re doing, and appreciate the work they’ll save you!