Merge 1.7.0 into v2.x (#162)

* Add setExpand() documentation

* Add macros RANDOM/TIMESTAMP/ASSETURI

* Remove empty #text/ #comments from parsed extensions

* Add unit test for #text extension

* rework resolveURLTemplates()

* leftpad cachebusting macro

* Bundle last changes

* 1.6.0

* Add Common-tasks.md (#148)

* Added NonLinear AdParameter Parsing with adequate test in sample.xml #152 (#153)

* changes to parse altText fixes #154 (#155)

* Wrapper limit handling (#157)

* Added wrapperLimit to options
* Fixed error forwarding inside wrappers

* VAST parser returns creative id, adId, sequence and apiFramework attributes

* Parse VAST Duration tag with number instead of HH:MM:SS

* Parse all nonlinear attributes

* Parse nonlinear click tracking urls

* Parser - handle click/clickthrough event for nonlinear/companion ads

* Bundle last changes

* 1.7.0

.gitignore

@@ -2,4 +2,4 @@
 dist/*
 node_modules/*
 bower_components/*
-npm-debug.log
+npm-debug.log

common-tasks.md

@@ -0,0 +1,42 @@
+# Common tasks
+
+This document describes common tasks used during the project life-cycle (mostly release-related).
+We might want to automate some of them in a near future (e.g via Travis).
+For now, let's use this document to make sure everyone is on the same page.
+
+## Release a new version
+
+``` bash
+git checkout master
+npm run test
+npm run bundle
+git add . && git commit -m "Bundle last changes"
+npm version <major|minor|patch> # depending on the changes
+npm publish
+git push --tags origin master
+```
+
+## Release a new alpha version :
+
+``` bash
+git checkout v2.x
+npm run test
+npm run bundle
+git add . && git commit -m "Bundle last changes"
+npm version prerelease
+npm publish --tag alpha
+git push --tags origin v2.x
+```
+
+## Merge the latest version back into the v2.x branch
+
+``` bash
+# assuming 1.6.0 tag exists and is the latest
+git checkout -b merge-1.6.0-into-v2.x
+git merge 1.6.0
+# fix conflicts then git add conflicting files
+npm run test
+git commit
+git push origin merge-1.6.0-into-v2.x
+# Create PR on Github (based on `v2.x` branch)
+```

docs/api.md

@@ -53,6 +53,7 @@ Fetch a URL and parse the response into a valid VAST object.
   * `String` *response* – A VAST XML document. When *response* is provided, no Ajax request is made and thus the *url* parameter is ignored.
   * `Object` *urlhandler* – A URL handler module, used to fetch the VAST document instead of the [default ones](/~https://github.com/dailymotion/vast-client-js/tree/master/src/urlhandlers).
   * `Boolean` *withCredentials* – A boolean to enable the *withCredentials* options for the XHR and FLASH URLHandlers.
+  * `Number` *wrapperLimit* – A number of available *Wrapper* responses that can be received with no InLine response.
 
 * `Function` *done* – Method to be called once the VAST document is parsed. The VAST JS object is passed as the 1st parameter. If null, an error is provided as a 2nd parameter.
 
@@ -65,14 +66,18 @@ DMVAST.client.get('http://example.dailymotion.com/vast.xml', function(response,
 
 # VASTTracker
 
-The VAST tracker constructor will process the tracking URLs of the selected ad/creative and returns an instance of `VASTTracker`. You can create an instance with `new DMVAST.tracker( ad , creative )`.
+The VAST tracker constructor will process the tracking URLs of the selected ad/creative and returns an instance of `VASTTracker`. You can create an instance with `new DMVAST.tracker( ad , creative [, variation] )`.
 
-- `Object` *ad* – Reference to the `<Ad>` element of the selected `mediaFile`
-- `Object` *creative* – Reference to the `<Creative>` element of the selected `mediaFile`
+- `Object` *ad* – Reference to the `<Ad>` element of the selected creative.
+- `Object` *creative* – Reference to the `<Creative>` element of the selected creative.
+- `Object` *variation* - An optional reference to the selected `<NonLinear>`/`<Companion>` element for non-linear ads.
 
 ``` javascript
-// Create a VAST Tracker instance
+// Create a VAST Tracker instance for a linear ad
 var vastTracker = new DMVAST.tracker(ad, creative);
+
+// Create a VAST Tracker instance for a companion ad
+var vastTracker = new DMVAST.tracker(ad, creative, companion);
 ```
 
 ## Methods

src/companionad.coffee

@@ -7,7 +7,9 @@ class VASTCompanionAd
         @staticResource = null
         @htmlResource = null
         @iframeResource = null
+        @altText = null
         @companionClickThroughURLTemplate = null
+        @companionClickTrackingURLTemplates = []
         @trackingEvents = {}
 
 module.exports = VASTCompanionAd

src/creative.coffee

@@ -1,5 +1,9 @@
 class VASTCreative
-    constructor: ->
+    constructor: (creativeAttributes = {}) ->
+        @id = creativeAttributes.id or null
+        @adId = creativeAttributes.adId or null
+        @sequence = creativeAttributes.sequence or null
+        @apiFramework = creativeAttributes.apiFramework or null
         @trackingEvents = {}
 
 class VASTCreativeLinear extends VASTCreative
@@ -23,6 +27,7 @@ class VASTCreativeNonLinear extends VASTCreative
 
 class VASTCreativeCompanion extends VASTCreative
     constructor: ->
+        super
         @type = "companion"
         @variations = []
 

src/nonlinear.coffee

@@ -3,12 +3,18 @@ class VASTNonLinear
         @id = null
         @width = 0
         @height = 0
-        @minSuggestedDuration = "00:00:00"
+        @expandedWidth = 0
+        @expandedHeight = 0
+        @scalable = true
+        @maintainAspectRatio = true
+        @minSuggestedDuration = 0
         @apiFramework = "static"
         @type = null
         @staticResource = null
         @htmlResource = null
         @iframeResource = null
         @nonlinearClickThroughURLTemplate = null
+        @nonlinearClickTrackingURLTemplates = []
+        @adParameters = null
 
 module.exports = VASTNonLinear

src/parser.coffee

@@ -36,7 +36,7 @@ class VASTParser
             cb = options if typeof options is 'function'
             options = {}
 
-        maxWrapperDepth = options.maxWrapperDepth || DEFAULT_MAX_WRAPPER_WIDTH
+        maxWrapperDepth = options.wrapperLimit || DEFAULT_MAX_WRAPPER_WIDTH
         options.wrapperDepth = 0
 
         @_parse url, null, options, (err, response) ->
@@ -253,18 +253,24 @@ class VASTParser
 
                 when "Creatives"
                     for creativeElement in @childsByName(node, "Creative")
+                        creativeAttributes =
+                            id           : creativeElement.getAttribute('id') or null
+                            adId         : creativeElement.getAttribute('adId') or null
+                            sequence     : creativeElement.getAttribute('sequence') or null
+                            apiFramework : creativeElement.getAttribute('apiFramework') or null
+
                         for creativeTypeElement in creativeElement.childNodes
                             switch creativeTypeElement.nodeName
                                 when "Linear"
-                                    creative = @parseCreativeLinearElement creativeTypeElement
+                                    creative = @parseCreativeLinearElement creativeTypeElement, creativeAttributes
                                     if creative
                                         ad.creatives.push creative
                                 when "NonLinearAds"
-                                    creative = @parseNonLinear creativeTypeElement
+                                    creative = @parseNonLinear creativeTypeElement, creativeAttributes
                                     if creative
                                         ad.creatives.push creative
                                 when "CompanionAds"
-                                    creative = @parseCompanionAd creativeTypeElement
+                                    creative = @parseCompanionAd creativeTypeElement, creativeAttributes
                                     if creative
                                         ad.creatives.push creative
                 when "Extensions"
@@ -320,8 +326,8 @@ class VASTParser
 
             collection.push ext
 
-    @parseCreativeLinearElement: (creativeElement) ->
-        creative = new VASTCreativeLinear()
+    @parseCreativeLinearElement: (creativeElement, creativeAttributes) ->
+        creative = new VASTCreativeLinear(creativeAttributes)
 
         creative.duration = @parseDuration @parseNodeText(@childByName(creativeElement, "Duration"))
         skipOffset = creativeElement.getAttribute("skipoffset")
@@ -428,8 +434,8 @@ class VASTParser
 
         return creative
 
-    @parseNonLinear: (creativeElement) ->
-        creative = new VASTCreativeNonLinear()
+    @parseNonLinear: (creativeElement, creativeAttributes) ->
+        creative = new VASTCreativeNonLinear(creativeAttributes)
 
         for trackingEventsElement in @childsByName(creativeElement, "TrackingEvents")
           for trackingElement in @childsByName(trackingEventsElement, "Tracking")
@@ -444,7 +450,11 @@ class VASTParser
             nonlinearAd.id = nonlinearResource.getAttribute("id") or null
             nonlinearAd.width = nonlinearResource.getAttribute("width")
             nonlinearAd.height = nonlinearResource.getAttribute("height")
-            nonlinearAd.minSuggestedDuration = nonlinearResource.getAttribute("minSuggestedDuration")
+            nonlinearAd.expandedWidth = nonlinearResource.getAttribute("expandedWidth")
+            nonlinearAd.expandedHeight = nonlinearResource.getAttribute("expandedHeight")
+            nonlinearAd.scalable = @parseBoolean nonlinearResource.getAttribute("scalable")
+            nonlinearAd.maintainAspectRatio = @parseBoolean nonlinearResource.getAttribute("maintainAspectRatio")
+            nonlinearAd.minSuggestedDuration = @parseDuration nonlinearResource.getAttribute("minSuggestedDuration")
             nonlinearAd.apiFramework = nonlinearResource.getAttribute("apiFramework")
 
             for htmlElement in @childsByName(nonlinearResource, "HTMLResource")
@@ -459,13 +469,20 @@ class VASTParser
                 nonlinearAd.type = staticElement.getAttribute("creativeType") or 0
                 nonlinearAd.staticResource = @parseNodeText(staticElement)
 
+            adParamsElement = @childByName(nonlinearResource, "AdParameters")
+            if adParamsElement?
+                nonlinearAd.adParameters = @parseNodeText(adParamsElement)
+
             nonlinearAd.nonlinearClickThroughURLTemplate = @parseNodeText(@childByName(nonlinearResource, "NonLinearClickThrough"))
+            for clickTrackingElement in @childsByName(nonlinearResource, "NonLinearClickTracking")
+                nonlinearAd.nonlinearClickTrackingURLTemplates.push @parseNodeText(clickTrackingElement)
+
             creative.variations.push nonlinearAd
 
         return creative
 
-    @parseCompanionAd: (creativeElement) ->
-        creative = new VASTCreativeCompanion()
+    @parseCompanionAd: (creativeElement, creativeAttributes) ->
+        creative = new VASTCreativeCompanion(creativeAttributes)
 
         for companionResource in @childsByName(creativeElement, "Companion")
             companionAd = new VASTCompanionAd()
@@ -481,6 +498,8 @@ class VASTParser
                 companionAd.iframeResource = @parseNodeText(iframeElement)
             for staticElement in @childsByName(companionResource, "StaticResource")
                 companionAd.type = staticElement.getAttribute("creativeType") or 0
+                for child in @childsByName(companionResource, "AltText")
+                    companionAd.altText = @parseNodeText(child)
                 companionAd.staticResource = @parseNodeText(staticElement)
             for trackingEventsElement in @childsByName(companionResource, "TrackingEvents")
                 for trackingElement in @childsByName(trackingEventsElement, "Tracking")
@@ -500,6 +519,10 @@ class VASTParser
     @parseDuration: (durationString) ->
         unless (durationString?)
             return -1
+        # Some VAST doesn't have an HH:MM:SS duration format but instead jus the number of seconds
+        if VASTUtil.isNumeric(durationString)
+            return parseInt durationString
+
         durationComponents = durationString.split(":")
         if durationComponents.length != 3
             return -1
@@ -528,6 +551,9 @@ class VASTParser
 
         return parseInt yPosition or 0
 
+    @parseBoolean: (booleanString) ->
+            return booleanString in ['true', 'TRUE', '1']
+
     # Parsing node text for legacy support
     @parseNodeText: (node) ->
         return node and (node.textContent or node.text or '').trim()

src/tracker.coffee

@@ -1,10 +1,12 @@
 VASTClient = require('./client')
 VASTUtil = require('./util')
 VASTCreativeLinear = require('./creative').VASTCreativeLinear
+VASTNonLinear = require('./nonlinear')
+VASTCompanionAd = require('./companionad')
 EventEmitter = require('events').EventEmitter
 
 class VASTTracker extends EventEmitter
-    constructor: (@ad, @creative) ->
+    constructor: (@ad, @creative, @variation = null) ->
         @muted = no
         @impressed = no
         @skipable = no
@@ -27,9 +29,18 @@ class VASTTracker extends EventEmitter
             @linear = yes
             @clickThroughURLTemplate = @creative.videoClickThroughURLTemplate
             @clickTrackingURLTemplates = @creative.videoClickTrackingURLTemplates
+        # Nonlinear and Companion
         else
             @skipDelay = -1
             @linear = no
+            # Used variation has been specified
+            if @variation
+                if @variation instanceof VASTNonLinear
+                    @clickThroughURLTemplate = @variation.nonlinearClickThroughURLTemplate
+                    @clickTrackingURLTemplates = @variation.nonlinearClickTrackingURLTemplates
+                else if @variation instanceof VASTCompanionAd
+                    @clickThroughURLTemplate = @variation.companionClickThroughURLTemplate
+                    @clickTrackingURLTemplates = @variation.companionClickTrackingURLTemplates
 
         @on 'start', ->
             VASTClient.lastSuccessfullAd = +new Date()

src/util.coffee

@@ -94,5 +94,7 @@ class VASTUtil
 
         return storage
 
+    @isNumeric: (n) ->
+        return !isNaN(parseFloat(n)) and isFinite(n)
 
 module.exports = VASTUtil