Dev notes #2
This is the second in a who-knows-how-many series of development notes for the upcoming Symphony 2.3 release. These notes describe two new features of Symphony 2.3, multiple output parameters for Section Datasources, and Publish Labels for Fields.
Section Datasources now have the ability to output multiple parameters which make for much more efficient datasources and more complex filtering between datasources. To support this feature, the syntax of output parameters has slightly altered:
Symphony 2.2.x and lower: $ds-datasource-handle
Symphony 2.3+: $ds-datasource-handle.field-handle
To clarify, parameters now append a . followed by the field-handle of the output parameter. This syntax leads to better readability throughout your code (and works well with Publish Labels!) and allows the current dependency logic to continue working without modification.
While the syntax has changed, the old syntax will continue to be supported for datasources that only output a single parameter for the 2.3.x branch at least. For example, a datasource called Read News that outputs Title will be mirrored as $ds-read-news and $ds-read-news.title. If this datasource is modified to include another output parameter, the mirroring will not occur. That is, if we add Comments as an output parameter, $ds-read-news.title and $ds-read-news.comments will exist, but $ds-read-news will not. Keep this in mind when updating pre Symphony 2.2 datasources!
How often have you had a client request to change a field name because it doesn't make sense to them? The field that you called Product ID is confusing users as they refer to it internally as SKU. Or perhaps you make use of the Paypal Payments extension (which relies on the Field's being named to match Paypal variables) which doesn't lend itself to a particular user friendly publish page. The concept of Publish Labels allows you change field names easily by creating an alias that is only used in the Publish area. This leaves your original field name intact, and means that all your datasources (and XSLT) will continue to work as expected.
So, lets say we have a field named Product ID and we leave the Publish Label setting blank. This will be shown in the backend as Product ID and in the datasources as product-id. A change request comes in for the field to be renamed to SKU. In Symphony 2.2.x and lower, you'd rename the field to SKU and then go through your datasources and XSLT to make sure any reference to product-id was now changed to sku. With Symphony 2.3 you can simply make use of the Publish Label setting to alias this field as SKU. In the Symphony backend (that is the entry form and the entries index), this field will now be labelled as SKU, but your datasources and XSLT will continue to work (and use) product-id. This feature is really handy, but it also has the potential to be abused, so be smart about it :)
Currently Publish Labels is implemented in all core fields by default but extension developers can easily implement it in their Fields by making use of the new Field->buildPublishLabel and Field->label functions.
Field->buildPublishLabel() should be used in your field's displaySettingsPanel function which will create the form field on the Section Editor (in a fashion similar to buildLocationSelect or buildFormatterSelect). Field->label() is then used in displayPublishPanel to return the Publish Label and if no Publish Label is set, Field->label() will return the Field's label. Your field probably makes use of Field->get('label') already so Field->label() is a drop in replacement to support Publish Labels.
You may notice the field placement on the Section Editor looks a little off with the inclusion of the new Publish Label setting. Not to worry, this is something that UX WG is looking to address with the UI refresh, so consider it technically complete, but in need of a lick of paint :)