Transition layout titles from being strings to be objects [882]

Author: rmoestl

src/components/titles/index.js

@@ -74,7 +74,8 @@ function draw(gd, titleClass, options) {
 
     var opacity = 1;
     var isplaceholder = false;
-    var txt = (cont.title || '').trim();
+    var title = cont.title;
+    var txt = (title && title.text ? title.text : '').trim();
 
     // only make this title editable if we positively identify its property
     // as one that has editing enabled.

src/plot_api/helpers.js

@@ -176,6 +176,23 @@ exports.cleanLayout = function(layout) {
         }
     }
 
+    // Check for old-style title definitions
+    if(!Lib.isPlainObject(layout.title)) {
+        layout.title = {
+            text: layout.title
+        };
+    }
+    if(layout.xaxis && !Lib.isPlainObject(layout.xaxis.title)) {
+        layout.xaxis.title = {
+            text: layout.xaxis.title
+        };
+    }
+    if(layout.yaxis && !Lib.isPlainObject(layout.yaxis.title)) {
+        layout.yaxis.title = {
+            text: layout.yaxis.title
+        };
+    }
+
     /*
      * Moved from rotate -> orbit for dragmode
      */

src/plot_api/subroutines.js

@@ -452,7 +452,7 @@ exports.drawMainTitle = function(gd) {
 
     Titles.draw(gd, 'gtitle', {
         propContainer: fullLayout,
-        propName: 'title',
+        propName: 'title.text',
         placeholder: fullLayout._dfltTitle.plot,
         attributes: {
             x: fullLayout.width / 2,

src/plots/cartesian/axes.js

@@ -2387,7 +2387,7 @@ axes.drawTitle = function(gd, ax) {
 
     Titles.draw(gd, axId + 'title', {
         propContainer: ax,
-        propName: ax._name + '.title',
+        propName: ax._name + '.title.text',
         placeholder: fullLayout._dfltTitle[axLetter],
         avoid: avoid,
         transform: transform,

src/plots/cartesian/axis_defaults.js

@@ -68,7 +68,7 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
     // try to get default title from splom trace, fallback to graph-wide value
     var dfltTitle = splomStash.label || layoutOut._dfltTitle[letter];
 
-    coerce('title', dfltTitle);
+    coerce('title.text', dfltTitle);
     Lib.coerceFont(coerce, 'titlefont', {
         family: font.family,
         size: Math.round(font.size * 1.2),

src/plots/cartesian/layout_attributes.js

@@ -41,10 +41,12 @@ module.exports = {
         ].join(' ')
     },
     title: {
-        valType: 'string',
-        role: 'info',
-        editType: 'ticks',
-        description: 'Sets the title of this axis.'
+        text: {
+            valType: 'string',
+            role: 'info',
+            editType: 'ticks',
+            description: 'Sets the title of this axis.'
+        }
     },
     titlefont: fontAttrs({
         editType: 'ticks',

src/plots/layout_attributes.js

@@ -26,12 +26,14 @@ globalFont.color.dflt = colorAttrs.defaultLine;
 module.exports = {
     font: globalFont,
     title: {
-        valType: 'string',
-        role: 'info',
-        editType: 'layoutstyle',
-        description: [
-            'Sets the plot\'s title.'
-        ].join(' ')
+        text: {
+            valType: 'string',
+            role: 'info',
+            editType: 'layoutstyle',
+            description: [
+                'Sets the plot\'s title.'
+            ].join(' ')
+        }
     },
     titlefont: fontAttrs({
         editType: 'layoutstyle',

src/plots/plots.js

@@ -1324,7 +1324,7 @@ plots.supplyLayoutGlobalDefaults = function(layoutIn, layoutOut, formatObj) {
 
     var globalFont = Lib.coerceFont(coerce, 'font');
 
-    coerce('title', layoutOut._dfltTitle.plot);
+    coerce('title.text', layoutOut._dfltTitle.plot);
 
     Lib.coerceFont(coerce, 'titlefont', {
         family: globalFont.family,

test/jasmine/tests/titles_test.js

@@ -12,7 +12,11 @@ describe('Plot title', function() {
     'use strict';
 
     var data = [{x: [1, 2, 3], y: [1, 2, 3]}];
-    var layout = {title: 'Plotly line chart'};
+    var layout = {
+        title: {
+            text: 'Plotly line chart'
+        }
+    };
     var gd;
 
     beforeEach(function() {
@@ -24,11 +28,22 @@ describe('Plot title', function() {
     it('is centered horizontally and vertically above the plot by default', function() {
         Plotly.plot(gd, data, layout);
 
+        expectDefaultCenteredPosition();
+    });
+
+    it('can still be defined as `layout.title` to ensure backwards-compatibility', function() {
+        Plotly.plot(gd, data, {title: 'Plotly line chart'});
+
+        expect(titleSel().text()).toBe('Plotly line chart');
+        expectDefaultCenteredPosition();
+    });
+
+    function expectDefaultCenteredPosition() {
         var containerBB = gd.getBoundingClientRect();
 
         expect(titleX()).toBe(containerBB.width / 2);
         expect(titleY()).toBe(gd._fullLayout.margin.t / 2);
-    });
+    }
 
     function titleX() {
         return Number.parseFloat(titleSel().attr('x'));
@@ -39,7 +54,9 @@ describe('Plot title', function() {
     }
 
     function titleSel() {
-        return d3.select('.infolayer .g-gtitle .gtitle');
+        var titleSel = d3.select('.infolayer .g-gtitle .gtitle');
+        expect(titleSel.empty()).toBe(false, 'Title element missing');
+        return titleSel;
     }
 });
 
@@ -117,9 +134,9 @@ describe('editable titles', function() {
 
     it('has hover effects for blank titles', function(done) {
         Plotly.plot(gd, data, {
-            xaxis: {title: ''},
-            yaxis: {title: ''},
-            title: ''
+            xaxis: {title: {text: ''}},
+            yaxis: {title: {text: ''}},
+            title: {text: ''}
         }, {editable: true})
         .then(function() {
             return Promise.all([
@@ -133,18 +150,18 @@ describe('editable titles', function() {
 
     it('has no hover effects for titles that used to be blank', function(done) {
         Plotly.plot(gd, data, {
-            xaxis: {title: ''},
-            yaxis: {title: ''},
-            title: ''
+            xaxis: {title: {text: ''}},
+            yaxis: {title: {text: ''}},
+            title: {text: ''}
         }, {editable: true})
         .then(function() {
-            return editTitle('x', 'xaxis.title', 'XXX');
+            return editTitle('x', 'xaxis.title.text', 'XXX');
         })
         .then(function() {
-            return editTitle('y', 'yaxis.title', 'YYY');
+            return editTitle('y', 'yaxis.title.text', 'YYY');
         })
         .then(function() {
-            return editTitle('g', 'title', 'TTT');
+            return editTitle('g', 'title.text', 'TTT');
         })
         .then(function() {
             return Promise.all([