Docs for Symphony 2.5 - Migration from 2.4

jquery.md

Some of the jquery plugins shipped with 2.5 has been optimized for large sections (+100 fields) and also features and brand new jquery plugin: the affix plugin.

The optimization also brings new public events on the collapsible plugin:

• updatesize.collapsible which will invalidate the cached values for the height of the DOM elements.
• setsize.collapsible which will set the min and max height CSS properties based on the cached values.

If you develop a field that uses the collapsible plugin, feel free to trigger those events.

The new plugin, affix will make a element "sticky" on the page, in order to "follow" the scroll. This plugin is used in the section editor in order to make the Expand/Collapse button always visible.

A normal usage of the affix plugin is to call it on the element(s) you want to make sticky.

$('#my-sticky-thing').symphonyAffix();

By default, the elements will be restricted by the size of its immediate parent element. You can change this to any other element on the page by passing a container option which can be a string or a jQuery object.

$('#my-sticky-thing').symphonyAffix({
    container: 'body'
});

prepareTableValue.md

Symphony 2.5 brings better control to field developers with regards to associations and how the data is displayed outside the publish sections. Until now, the only thing a field developer could do was to implement prepareTableValue method in the field class. It was not meant that way, but this method got relyed upon in many place in order to display the "text" representation of the field's actual value.

So it has been decided that this part of the public interface of the field should be split in order clearly state responsibilities. Mainly, the goals was:

1. Better control over value formatting: field should be able to provide either a raw or formatted value
2. Better reuse of the code: since responsibilities are split up, developers change better choose what to override and what to keep.
3. Backwards compatibility

It was already possible to get some values out of fields in a nice way: Exportable interface has been introduce in 2.3 in order to acheive this, but since it is an interface, it was still a opt-in basis and we felt that the core should at least offer some simple way to get a textual value.

What shipped with 2.5 is two new methods that split the original prepareTableValue implementation into a waterfall.

• prepareTextValue: https://github.com/symphonycms/symphony-2/blob/integration/symphony/lib/toolkit/class.field.php#L1036 Returns a string representation.
• prepareReadableValue: https://github.com/symphonycms/symphony-2/blob/integration/symphony/lib/toolkit/class.field.php#L1005 Calls prepareTextValue and formats/truncate the its return value for better readability.
• prepareTableValue: https://github.com/symphonycms/symphony-2/blob/integration/symphony/lib/toolkit/class.field.php#L973 Calls prepareReadableValue

In most cases, the migration to be done is to remove the prepareTableValue implementation and use the API at a lower level. The Field class sub-classes should then override the prepareTextValue method. The only requirement for this method is to return a complete, valid string representation of the field value, so it is even easier to implement that having to deal with prepareTableValue's $link parameter.

But if your field hold complex data, you should not be afraid to play with the waterfalls calls and it will make your field as seamless as possible. A common use case would be a custom prepareReadableValue implementation in order to be sure that if the field is the first visible field in the section, the title of the edit publish page will look great.

As for backward compatibility, if the prepareReadableValue value returns an empty string, some old calls to prepareTableValue are left in the code base. This is a way of easing the pain a bit, but is not 100% backward compatible since it could break in some different ways.

We will do our part to upgrade most of the existing extensions in order to comply with this new API, but feel free to fork and send a PR: it will boost your karma and help lots of people!

Please note that fetchAssociatedEntryIDs method as been deprecated. Use findRelatedEntries and/or findParentRelatedEntries.