Position

The position of a widget refers to its location relative to other widgets with the same placement. The following sections describe Brightspot’s default positioning logic as well as techniques for overriding that logic.

Default Positioning

Within the same Placement (top, bottom, right, dedicated tab), Brightspot by default positions custom widgets in alphabetical order based on the class’s fully qualified name. For example, suppose you defined three custom widgets widgets.AdamsCustomWidget, widgets.JacksCustomWidget, and specials.widgets.ZoesCustomWidget, and all of them appear under the Content Edit Form. By default, Brightspot positions them in alphabetical order as in the following illustration.

../../../_images/default-widget-position.svg

Custom Positioning

You can override the alphabetical sorting for custom widgets by implementing the method ContentEditWidget#getPosition and returning a double value. Values with smaller numbers appear closer to the top, and the default value is zero. Positions with the same value are sorted alphabetically by fully qualified class name.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
package widgets;

import com.psddev.cms.tool.ContentEditWidget;
import com.psddev.cms.tool.ContentEditWidgetPlacement;
import com.psddev.cms.tool.ToolPageContext;

import java.io.IOException;

public class JillsCustomWidget extends ContentEditWidget {

    @Override
    public ContentEditWidgetPlacement getPlacement(ToolPageContext toolPageContext, Object o) {
        return ContentEditWidgetPlacement.BOTTOM;
    }

    @Override
    public double getPosition(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) {
        return 8.0;
    }
}

In the previous snippet—

  • Lines 11–14 place Jill’s widget under the content edit form.
  • Lines 16–19 assign Jill’s widget a relative position of 8.0.

Suppose you assign Zoe’s, Adam’s, Jack’s, and Jill’s widgets return values for getPosition as in the following table.

Example Values for Positioning Widgets
Widget Fully Qualified Class Name getPlacement getPosition
Zoe special.widgets.ZoesCustomWidget ContentEditWidgetPlacement.BOTTOM 10.0
Adam widgets.AdamsCustomWidget ContentEditWidgetPlacement.BOTTOM 10.0
Jack widgets.JacksCustomWidget ContentEditWidgetPlacement.BOTTOM 8.0
Jill widgets.JillsCustomWidget ContentEditWidgetPlacement.BOTTOM 9.0

Because all the widgets have the same placement, Brightspot lays them out as in the following illustration.

../../../_images/custom-widget-position.png

Both Zoe’s and Adam’s widgets have the same return value for getPosition, so Brightspot breaks the tie by sorting by fully qualified class name.

Custom Positioning with Substitution

If you use a custom widget that is imported from another package, that widget may have a result from getPosition that conflicts with your implementation. Referring to the table Example Values for Positioning Widgets, Zoe’s custom widget has a position of 10, but you may want to place her widget first, in front of all the other custom widgets.

You can use Substitutions to incorporate an imported widget into your project and then override the original value for getPosition.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
package ported.widgets;

import com.psddev.cms.tool.ContentEditWidgetPlacement;
import com.psddev.cms.tool.ToolPageContext;
import com.psddev.dari.db.Substitution;
import special.widgets.ZoesCustomWidget;

public class ZoesPortedCustomWidget extends ZoesCustomWidget implements Substitution {

    @Override
    public double getPosition(ToolPageContext page, Object content, ContentEditWidgetPlacement placement) {
        return 6.0;
    }

}

In the previous snippet—

  • Line 1 declares the class’s package.
  • Line 6 imports the custom widget ZoesCustomWidget from another package.
  • Line 8 declares a ported custom widget ZoesPortedCustomWidget by extending the imported custom widget and implementing Substitution.
  • Lines 10–13 override the imported widget’s position, now assigning it 6 (compared to the original 10 as listed in the table Example Values for Positioning Widgets). This position value is the lowest of all other custom widgets.

At run time, the ported custom widget appears first among all other custom widgets under the content edit form.

../../../_images/custom-widget-position-substitution.png

See also: