HTML Credits

CHANGES.md

@@ -9,6 +9,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).
@@ -23,6 +26,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)
 * Added support for ordering in `DataSourceCollection` [#6316](https://github.com/AnalyticalGraphicsInc/cesium/pull/6316)
   * All ground geometry from one `DataSource` will render in front of all ground geometry from another `DataSource` in the same collection with a lower index.
   * Use `DataSourceCollection.raise`, `DataSourceCollection.lower`, `DataSourceCollection.raiseToTop` and `DataSourceCollection.lowerToBottom` functions to change the ordering of a `DataSource` in the collection. 

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

@@ -28,7 +28,7 @@ define([
 
     var printedBingWarning = false;
     var errorCredit;
-    var errorString = 'This application is using Cesium\'s default Bing Maps key.  Please create a new key for the application as soon as possible and prior to deployment by visiting https://www.bingmapsportal.com/, and provide your key to Cesium by setting the Cesium.BingMapsApi.defaultKey property before constructing the CesiumWidget or any other object that uses the Bing Maps API.';
+    var errorString = '<b>This application is using Cesium\'s default Bing Maps key.  Please create a new key for the application as soon as possible and prior to deployment by visiting <a href="https://www.bingmapsportal.com/">https://www.bingmapsportal.com/</a>, and provide your key to Cesium by setting the Cesium.BingMapsApi.defaultKey property before constructing the CesiumWidget or any other object that uses the Bing Maps API.</b>';
 
     BingMapsApi.getKey = function(providedKey) {
         if (defined(providedKey)) {
@@ -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 + '>' + 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,26 @@
 define([
+        '../ThirdParty/xss',
         './defaultValue',
         './defined',
         './defineProperties',
+        './deprecationWarning',
         './DeveloperError'
     ], function(
+        xss,
         defaultValue,
         defined,
         defineProperties,
+        deprecationWarning,
         DeveloperError) {
     'use strict';
 
     var nextCreditId = 0;
     var creditToId = {};
 
-    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;
-    }
-
     /**
      * 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 +35,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 +111,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 +140,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 +153,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 +166,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;
             }
         },
@@ -187,7 +205,19 @@ define([
         element: {
             get: function() {
                 if (!defined(this._element)) {
-                    this._element = getElement(this);
+                    var html = this.html;
+                    html = xss(html);
+
+                    var div = document.createElement('div');
+                    div.style.display = 'inline';
+                    div.innerHTML = html;
+
+                    var links = div.querySelectorAll('a');
+                    for (var i = 0; i < links.length; i++) {
+                        links[i].setAttribute('target', '_blank');
+                    }
+
+                    this._element = div;
                 }
                 return this._element;
             }
@@ -200,6 +230,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 +240,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 +268,27 @@ 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 = credit.html.indexOf('ion-credit.png') !== -1;
+        return credit;
+    };
+
     return Credit;
 });