html credits

CHANGES.md

@@ -6,6 +6,9 @@ Change Log
 ##### Deprecated :hourglass_flowing_sand:
 * `ClippingPlaneCollection` is now supported in Internet Explorer, so `ClippingPlaneCollection.isSupported` has been deprecated and will be removed in Cesium 1.45.
 * `ClippingPlaneCollection` should now be used with `ClippingPlane` objects instead of `Plane`. Use of `Plane` objects has been deprecated and will be removed in Cesium 1.45.
+* `Credit` now takes an `html` and `showOnScreen` parameters instead of an `options` object.  Use of the `options` parameter is deprecated and will be removed in Cesium 1.46.
+* `Credit.text`, `Credit.imageUrl` and `Credit.link` properties have all been deprecated and will be removed in Cesium 1.46.  Use `Credit.html` to retrieve the credit content.
+* `Credit.hasImage` and `Credit.hasLink` functions have been deprecated and will be removed in Cesium 1.46.
 
 ##### Additions :tada:
 * Added support for glTF models with [Draco geometry compression](https://github.com/fanzhanggoogle/glTF/blob/KHR_mesh_compression/extensions/Khronos/KHR_draco_mesh_compression/README.md).
@@ -20,6 +23,7 @@ Change Log
   * sourceType specifies the type of data source if the URL doesn't have a known file extension.
   * flyTo=false optionally disables the automatic flyTo after loading the data source.
 * Added a multi-part CZML example to Sandcastle. [#6320](https://github.com/AnalyticalGraphicsInc/cesium/pull/6320)
+* `Credit` has been modified to take an HTML string as the credit content [#6331](https://github.com/AnalyticalGraphicsInc/cesium/pull/6331)
 
 ##### Fixes :wrench:
 * Fixed support of glTF-supplied tangent vectors. [#6302](https://github.com/AnalyticalGraphicsInc/cesium/pull/6302)

LICENSE.md

@@ -686,6 +686,34 @@ https://github.com/google/draco
 >License for the specific language governing permissions and limitations under
 >the License.
 
+### JSXSS
+
+https://github.com/leizongmin/js-xss
+
+> Copyright (c) 2012-2017 Zongmin Lei(雷宗民) <[email protected]>
+> http://ucdok.com
+> 
+> The MIT License
+> 
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> "Software"), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+> 
+> The above copyright notice and this permission notice shall be
+> included in all copies or substantial portions of the Software.
+> 
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+> LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
 Tests
 =====
 

Source/Core/BingMapsApi.js

@@ -52,10 +52,7 @@ define([
         }
 
         if (!defined(errorCredit)) {
-            errorCredit = new Credit({
-                text : errorString,
-                showOnScreen : true
-            });
+            errorCredit = new Credit(errorString, true);
         }
 
         return errorCredit;

Source/Core/CesiumTerrainProvider.js

@@ -131,7 +131,7 @@ define([
 
         var credit = options.credit;
         if (typeof credit === 'string') {
-            credit = new Credit({text: credit});
+            credit = new Credit(credit);
         }
         this._credit = credit;
 
@@ -163,12 +163,11 @@ define([
 
                 var uri = new Uri(metadataResource.url);
                 if (uri.authority === 'assets.agi.com') {
-                    var deprecationText = 'The STK World Terrain tileset is deprecated and will be available until September 1, 2018';
+                    var deprecationText = 'The STK World Terrain tileset is deprecated and will be available until September 1, 2018.';
                     var deprecationLinkText = 'Check out the new high-resolution Cesium World Terrain';
                     var deprecationLink = 'https://cesium.com/blog/2018/03/01/introducing-cesium-world-terrain/';
                     that._tileCredits = [
-                        new Credit({ text: deprecationText, showOnScreen: true }),
-                        new Credit({ text: deprecationLinkText, link: deprecationLink, showOnScreen: true })
+                        new Credit('<span>' + deprecationText + '</span> <a href="' + deprecationLink + '" target="_blank">' + deprecationLinkText + '</a>', true)
                     ];
                     deprecationWarning('assets.agi.com', deprecationText + ' ' + deprecationLinkText + ' ' + deprecationLink);
                 } else {
@@ -327,7 +326,7 @@ define([
                         }
                     }
 
-                    var layerJsonCredit = new Credit({ text: attribution });
+                    var layerJsonCredit = new Credit(attribution);
 
                     if (defined(that._tileCredits)) {
                         that._tileCredits.push(layerJsonCredit);

Source/Core/Credit.js

@@ -1,62 +1,39 @@
 define([
-        './defaultValue',
-        './defined',
-        './defineProperties',
-        './DeveloperError'
-    ], function(
-        defaultValue,
-        defined,
-        defineProperties,
-        DeveloperError) {
+    './defaultValue',
+    './defined',
+    './defineProperties',
+    './deprecationWarning',
+    './DeveloperError',
+    '../ThirdParty/xss'
+], function(
+    defaultValue,
+    defined,
+    defineProperties,
+    deprecationWarning,
+    DeveloperError,
+    xss) {
     'use strict';
 
     var nextCreditId = 0;
     var creditToId = {};
 
+    function createDomNode(html) {
+        var span = document.createElement('span');
+        span.innerHTML = html;
+
+        return span;
+    }
+
     function getElement(credit) {
-        var element = document.createElement('span');
-        var text = credit.text;
-        var link = credit.link;
-        var a;
-        if (credit._hasImage) {
-            var content = document.createElement('img');
-            content.src = credit.imageUrl;
-            if (defined(text)) {
-                content.alt = text;
-                content.title = text;
-            }
-            if (credit._hasLink) {
-                a = document.createElement('a');
-                a.appendChild(content);
-                a.href = link;
-                a.target = '_blank';
-                element.appendChild(a);
-            } else {
-                element.appendChild(content);
-            }
-            element.className = 'cesium-credit-image';
-        } else {
-            if (credit._hasLink) {
-                a = document.createElement('a');
-                a.textContent = text;
-                a.href = link;
-                a.target = '_blank';
-                element.appendChild(a);
-            } else {
-                element.textContent = text;
-            }
-            element.className = 'cesium-credit-text';
-        }
-        return element;
+        var html = credit.html;
+        html = xss(html);
+        return createDomNode(html);
     }
 
     /**
      * A credit contains data pertaining to how to display attributions/credits for certain content on the screen.
-     * @param {Object} [options] An object with the following properties
-     * @param {String} [options.text] The text to be displayed on the screen if no imageUrl is specified.
-     * @param {String} [options.imageUrl] The source location for an image
-     * @param {String} [options.link] A URL location for which the credit will be hyperlinked
-     * @param {Boolean} [options.showOnScreen=false] If true, the credit will be visible in the main credit container.  Otherwise, it will appear in a popover
+     * @param {String} html An string representing an html code snippet (can be text only)
+     * @param {Boolean} [showOnScreen=false] If true, the credit will be visible in the main credit container.  Otherwise, it will appear in a popover
      *
      * @alias Credit
      * @constructor
@@ -71,38 +48,74 @@ define([
      *     link : 'https://cesiumjs.org/'
      * });
      */
-    function Credit(options) {
-        options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+    function Credit(html, showOnScreen) {
+        var id;
+        var key;
+        if (typeof html !== 'string') {
+            var options = defaultValue(html, defaultValue.EMPTY_OBJECT);
+            deprecationWarning('Credit options', 'The options parameter has been deprecated and will be removed in Cesium 1.46.  Instead, pass in an HTML string (or a string of text)');
+            showOnScreen = defaultValue(options.showOnScreen, showOnScreen);
+            var text = options.text;
+            var imageUrl = options.imageUrl;
+            var link = options.link;
 
-        var text = options.text;
-        var imageUrl = options.imageUrl;
-        var link = options.link;
-        var showOnScreen = defaultValue(options.showOnScreen, false);
+            var hasLink = (defined(link));
+            var hasImage = (defined(imageUrl));
+            var hasText = (defined(text));
 
-        var hasLink = (defined(link));
-        var hasImage = (defined(imageUrl));
-        var hasText = (defined(text));
+            //>>includeStart('debug', pragmas.debug);
+            if (!hasText && !hasImage && !hasLink) {
+                throw new DeveloperError('options.text, options.imageUrl, or options.link is required.');
+            }
+            //>>includeEnd('debug');
 
-        //>>includeStart('debug', pragmas.debug);
-        if (!hasText && !hasImage && !hasLink) {
-            throw new DeveloperError('options.text, options.imageUrl, or options.link is required.');
-        }
-        //>>includeEnd('debug');
+            if (!hasText && !hasImage) {
+                text = link;
+            }
 
-        if (!hasText && !hasImage) {
-            text = link;
-        }
+            this._text = text;
+            this._imageUrl = imageUrl;
+            this._link = link;
+            this._hasLink = hasLink;
+            this._hasImage = hasImage;
 
-        this._text = text;
-        this._imageUrl = imageUrl;
-        this._link = link;
-        this._hasLink = hasLink;
-        this._hasImage = hasImage;
-        this._showOnScreen = showOnScreen;
+            var element = document.createElement('span');
+            var a;
+            if (hasImage) {
+                var content = document.createElement('img');
+                content.src = imageUrl;
+                if (defined(text)) {
+                    content.alt = text;
+                    content.title = text;
+                }
+                if (hasLink) {
+                    a = document.createElement('a');
+                    a.appendChild(content);
+                    a.href = link;
+                    a.target = '_blank';
+                    element.appendChild(a);
+                } else {
+                    element.appendChild(content);
+                }
+                element.className = 'cesium-credit-image';
+            } else {
+                if (hasLink) {
+                    a = document.createElement('a');
+                    a.textContent = text;
+                    a.href = link;
+                    a.target = '_blank';
+                    element.appendChild(a);
+                } else {
+                    element.textContent = text;
+                }
+                element.className = 'cesium-credit-text';
+            }
 
-        // Credits are immutable so generate an id to use to optimize equal()
-        var id;
-        var key = JSON.stringify([text, imageUrl, link]);
+            html = '<span>' + element.innerHTML + '</span>';
+            key = JSON.stringify([text, imageUrl, link]);
+        } else {
+            key = html;
+        }
 
         if (defined(creditToId[key])) {
             id = creditToId[key];
@@ -111,12 +124,27 @@ define([
             creditToId[key] = id;
         }
 
-        this._id = id;
+        showOnScreen = defaultValue(showOnScreen, false);
 
+        // Credits are immutable so generate an id to use to optimize equal()
+        this._id = id;
+        this._html = html;
+        this._showOnScreen = showOnScreen;
         this._element = undefined;
     }
 
     defineProperties(Credit.prototype, {
+        /**
+         * The credit content
+         * @memberof Credit.prototype
+         * @type {String}
+         * @readonly
+         */
+        html : {
+            get : function() {
+                return this._html;
+            }
+        },
         /**
          * The credit text
          * @memberof Credit.prototype
@@ -125,6 +153,7 @@ define([
          */
         text : {
             get : function() {
+                deprecationWarning('Credit.text', 'Credit.text is deprecated and will be removed in Cesium 1.46.  Instead, use Credit.html to get the credit content.');
                 return this._text;
             }
         },
@@ -137,6 +166,7 @@ define([
          */
         imageUrl : {
             get : function() {
+                deprecationWarning('Credit.imageUrl', 'Credit.imageUrl is deprecated and will be removed in Cesium 1.46.  Instead, use Credit.html to get the credit content.');
                 return this._imageUrl;
             }
         },
@@ -149,6 +179,7 @@ define([
          */
         link : {
             get : function() {
+                deprecationWarning('Credit.link', 'Credit.link is deprecated and will be removed in Cesium 1.46.  Instead, use Credit.html to get the credit content.');
                 return this._link;
             }
         },
@@ -200,6 +231,7 @@ define([
      * @returns {Boolean}
      */
     Credit.prototype.hasImage = function() {
+        deprecationWarning('Credit.hasImage', 'Credit.hasImage is deprecated and will be removed in Cesium 1.46.');
         return this._hasImage;
     };
 
@@ -209,6 +241,7 @@ define([
      * @returns {Boolean}
      */
     Credit.prototype.hasLink = function() {
+        deprecationWarning('Credit.hasLink', 'Credit.hasLink is deprecated and will be removed in Cesium 1.46.');
         return this._hasLink;
     };
 
@@ -236,5 +269,26 @@ define([
         return Credit.equals(this, credit);
     };
 
+    /**
+     * @private
+     * @param attribution
+     * @return {Credit}
+     */
+    Credit.getIonCredit = function(attribution) {
+        var credit;
+        var showOnScreen = defined(attribution.collapsible) && !attribution.collapsible;
+        if (defined(attribution.html)) {
+            credit = new Credit(attribution.html, showOnScreen);
+        } else {
+            credit = new Credit({
+                text: attribution.text,
+                link: attribution.url,
+                imageUrl: attribution.image
+            }, showOnScreen);
+        }
+        credit._isIon = true;
+        return credit;
+    };
+
     return Credit;
 });

Source/Core/GoogleEarthEnterpriseMetadata.js

@@ -546,7 +546,7 @@ define([
                     var provider = providerInfo[i];
                     var copyrightString = provider.copyrightString;
                     if (defined(copyrightString)) {
-                        providers[provider.providerId] = new Credit({text: copyrightString.value});
+                        providers[provider.providerId] = new Credit(copyrightString.value);
                     }
                 }
             })