plugins/org.eclipse.sirius.doc/specs/proposal/440296_Required_side_for_border_nodes/440296_Required_side_for_border_nodes.textile - sirius/org.eclipse.sirius - Git at Google

 h1. Sirius Evolution Specification: Allow to specify authorized sides for border nodes

 h2. Preamble

 _Summary_: Allow to specify authorized sides for border nodes.

 |_. Version |_. Status |_. Date        |_. Authors |_. Changes |
 | v0.1        | DRAFT    | 2015-04-08 | smonnier    | Initial version. |
 | v0.1        | DRAFT    | 2015-05-18 | smonnier    | Updated. |

 _Relevant tickets_:
 * "Bugzilla #440296, Specify border nodes side in the VSM":https://bugs.eclipse.org/bugs/show_bug.cgi?id=440296

 h2. Introduction

 The goal of this evolution is to be able to specify the authorized sides for border nodes.

 h2. Detailed Specification

 A common Sirius code customization is to redefine the layout in order to choose on which sides a border node should be placed regarding its container. For example, the input port of a component should be on the left and the output port should be on the right. This specification presents how this behavior could be available in the VSM for the specifier.

 * VSM Editor update :
 ** The style of a border node will display a new field in the *Advanced* tab. The field will have the label *Authorized Sides* with four checkboxes, one for each side. These sides will be displayed in the order North, East, South, West. This is the clockwise order, which is already used in the border nodes placement algorithm. By default, every side (4 checkboxes) will be checked to match the current behavior.
 ** There is no display change for other nodes (nodes on diagram or in containers).
 * Diagram updates :
 ** The default border node positioning is to start on the left of the north face and place the next ones clockwise, changing side when needed. This behavior needs to be overridden in @DBorderItemLocator@ and @DDiagramCanonicalSynchronizer@ as the side here is required. Therefore it should still be placed clockwise but not changing side when full anymore.
 *** If too many border nodes are required to be on a side, they will overlap at the "extremity" as they are placed clockwise (right extremity for north, bottom extremity for east, left extremity for south and top extremity for west). We consider it as the expected behavior.
 *** Let's have a border node mapping defined as placed on the south border of its parent container. The element are placed clockwise, therefore right to left on the south border. <br/> !images/southBorder.png!
 *** When the border side if "full", the elements will be stacked at the "end" of this side, here the left side. <br/> !images/southBorder2.png! <br/> Note that on there are six border nodes but only five are displayed because *border_node_6* is displayed over *border_node_5* making it non visible.
 ** _Optional_: As it may be confusing for users that the south side is filled right to left and the west side is filled bottom-up, the @DBorderItemLocator@ could be overridden to fill these side, alike their opposite, respectively left to right and top-down. However, this algorithm is sensitive enough already.
 ** This new behavior should be in sync in the (Sirius) DNode locations as well as the GMF Node locations.
 ** Diagram visual operation should not move a border node to an unauthorized side even if it is closer. This concerns:
 *** Arrange all;
 *** Arrange selection;
 *** Arrange linked border nodes;
 *** Diagram element creation. Currently, the element is placed on the closest side. It should be placed on the closest authorized side;
 *** Diagram element Move (if the element is dropped on an unauthorized side, the element should go back to the previous location);
 *** Diagram element Resize (and the alternative resize with F3);
 *** Distribute selection;
 *** Align selection;
 *** Copy/Paste Layout;
 * _Optional_: in sequence diagram, @SouthCenteredBorderItemLocator@ and @ExecutionItemLocator@ could be reworked to use this Border Node location feature.
 ** *Lifelines* are on the south border of the parent *Instance Role*
 ** *Executions* are on the east border of the parent *Lifelines* or *Executions*
 ** *End of life* are on the south border of the parent *Lifelines*


 h2. Backward Compatibility and Migration Paths

 * This evolution requires a migration that will set the @locationOnParentBorder@ reference of the @style@ with each side of the @Location@ enumeration.

 h3. Metamodel Changes

 * Metamodel diagram.ecore updates :
 ** In the package @style@ an enumeration @Side@ should be created with the enumeration literals : @NORTH@, @EAST@, @SOUTH@, @WEST@;
 ** The metaclass @NodeStyleDescription@ should have a @authorizedSides@ multi-values reference typed @Location@.

 h3. API Changes

 This evolution concerns the internal Sirius refresh and layouting mechanisms and should not modify APIs.

 h3. User Interface Changes

 In the VSM, style of border node will have a new option to check the sides on which elements are authorized to be displayed.
 !images/vsmBorderSelection.png!

 Note that this option will not be available for non border node (node on diagram or inside a container).

 h3. Documentation Changes

 * Update specifier documentation and release note about the ability to select on which sides of their parent, border nodes should be displayed.

 h2. Tests and Non-regression strategy

 * test with a single border node on one side;
 ** test for each side;
 * test with a single border node on each side: 4 mappings then;
 * test with more border node on one side than the side can display;
 ** test for each side ;
 * test with more border node on one side than the side can display, for each side: 4 mappings then;
 * test with mapping reused or imported in other context;
 * test arrange all keeps border node on the authorized sides even if it would be closer on an unauthorized side.
 * test arrange selection keeps border node on the authorized sides even if it would be closer on an unauthorized side.
 * test diagram element move keeps border node on the authorized sides even if it would be closer on an unauthorized side.
 * test diagram element resize keeps border node on the authorized sides even if it would be closer on an unauthorized side.
 * test distribute selection keeps border node on the authorized sides even if it would be closer on an unauthorized side.
 * test align selection keeps border node on the authorized sides even if it would be closer on an unauthorized side.
 * test copy/paste layout keeps border node on the authorized sides even if it would be closer on an unauthorized side.

 h2. Implementation choices and tradeoffs

 * It has been decided to keep the clockwise positioning of elements for border nodes on their parent side. Specific positioning, like centered or equaly distributed will still be a custom java extension.
 * It has been decided that the border authorized sides would be a property of the style. Putting the info on the node's style means it will be "inherited" when the mapping is reused or imported in other contexts. It is not wrong, but an alternative would have been to make the container decide which of its bordered nodes it wants on which side. It is probably more complex to implement though.
	h1. Sirius Evolution Specification: Allow to specify authorized sides for border nodes

	h2. Preamble

	_Summary_: Allow to specify authorized sides for border nodes.

	\|_. Version \|_. Status \|_. Date \|_. Authors \|_. Changes \|
	\| v0.1 \| DRAFT \| 2015-04-08 \| smonnier \| Initial version. \|
	\| v0.1 \| DRAFT \| 2015-05-18 \| smonnier \| Updated. \|

	_Relevant tickets_:
	* "Bugzilla #440296, Specify border nodes side in the VSM":https://bugs.eclipse.org/bugs/show_bug.cgi?id=440296

	h2. Introduction

	The goal of this evolution is to be able to specify the authorized sides for border nodes.

	h2. Detailed Specification

	A common Sirius code customization is to redefine the layout in order to choose on which sides a border node should be placed regarding its container. For example, the input port of a component should be on the left and the output port should be on the right. This specification presents how this behavior could be available in the VSM for the specifier.

	* VSM Editor update :
	** The style of a border node will display a new field in the Advanced tab. The field will have the label Authorized Sides with four checkboxes, one for each side. These sides will be displayed in the order North, East, South, West. This is the clockwise order, which is already used in the border nodes placement algorithm. By default, every side (4 checkboxes) will be checked to match the current behavior.
	** There is no display change for other nodes (nodes on diagram or in containers).
	* Diagram updates :
	** The default border node positioning is to start on the left of the north face and place the next ones clockwise, changing side when needed. This behavior needs to be overridden in @DBorderItemLocator@ and @DDiagramCanonicalSynchronizer@ as the side here is required. Therefore it should still be placed clockwise but not changing side when full anymore.
	*** If too many border nodes are required to be on a side, they will overlap at the "extremity" as they are placed clockwise (right extremity for north, bottom extremity for east, left extremity for south and top extremity for west). We consider it as the expected behavior.
	*** Let's have a border node mapping defined as placed on the south border of its parent container. The element are placed clockwise, therefore right to left on the south border. <br/> !images/southBorder.png!
	*** When the border side if "full", the elements will be stacked at the "end" of this side, here the left side. <br/> !images/southBorder2.png! <br/> Note that on there are six border nodes but only five are displayed because border_node_6 is displayed over border_node_5 making it non visible.
	** _Optional_: As it may be confusing for users that the south side is filled right to left and the west side is filled bottom-up, the @DBorderItemLocator@ could be overridden to fill these side, alike their opposite, respectively left to right and top-down. However, this algorithm is sensitive enough already.
	** This new behavior should be in sync in the (Sirius) DNode locations as well as the GMF Node locations.
	** Diagram visual operation should not move a border node to an unauthorized side even if it is closer. This concerns:
	*** Arrange all;
	*** Arrange selection;
	*** Arrange linked border nodes;
	*** Diagram element creation. Currently, the element is placed on the closest side. It should be placed on the closest authorized side;
	*** Diagram element Move (if the element is dropped on an unauthorized side, the element should go back to the previous location);
	*** Diagram element Resize (and the alternative resize with F3);
	*** Distribute selection;
	*** Align selection;
	*** Copy/Paste Layout;
	* _Optional_: in sequence diagram, @SouthCenteredBorderItemLocator@ and @ExecutionItemLocator@ could be reworked to use this Border Node location feature.
	** Lifelines are on the south border of the parent Instance Role
	** Executions are on the east border of the parent Lifelines or Executions
	** End of life are on the south border of the parent Lifelines


	h2. Backward Compatibility and Migration Paths

	* This evolution requires a migration that will set the @locationOnParentBorder@ reference of the @style@ with each side of the @Location@ enumeration.

	h3. Metamodel Changes

	* Metamodel diagram.ecore updates :
	** In the package @style@ an enumeration @Side@ should be created with the enumeration literals : @NORTH@, @EAST@, @SOUTH@, @WEST@;
	** The metaclass @NodeStyleDescription@ should have a @authorizedSides@ multi-values reference typed @Location@.

	h3. API Changes

	This evolution concerns the internal Sirius refresh and layouting mechanisms and should not modify APIs.

	h3. User Interface Changes

	In the VSM, style of border node will have a new option to check the sides on which elements are authorized to be displayed.
	!images/vsmBorderSelection.png!

	Note that this option will not be available for non border node (node on diagram or inside a container).

	h3. Documentation Changes

	* Update specifier documentation and release note about the ability to select on which sides of their parent, border nodes should be displayed.

	h2. Tests and Non-regression strategy

	* test with a single border node on one side;
	** test for each side;
	* test with a single border node on each side: 4 mappings then;
	* test with more border node on one side than the side can display;
	** test for each side ;
	* test with more border node on one side than the side can display, for each side: 4 mappings then;
	* test with mapping reused or imported in other context;
	* test arrange all keeps border node on the authorized sides even if it would be closer on an unauthorized side.
	* test arrange selection keeps border node on the authorized sides even if it would be closer on an unauthorized side.
	* test diagram element move keeps border node on the authorized sides even if it would be closer on an unauthorized side.
	* test diagram element resize keeps border node on the authorized sides even if it would be closer on an unauthorized side.
	* test distribute selection keeps border node on the authorized sides even if it would be closer on an unauthorized side.
	* test align selection keeps border node on the authorized sides even if it would be closer on an unauthorized side.
	* test copy/paste layout keeps border node on the authorized sides even if it would be closer on an unauthorized side.

	h2. Implementation choices and tradeoffs

	* It has been decided to keep the clockwise positioning of elements for border nodes on their parent side. Specific positioning, like centered or equaly distributed will still be a custom java extension.
	* It has been decided that the border authorized sides would be a property of the style. Putting the info on the node's style means it will be "inherited" when the mapping is reused or imported in other contexts. It is not wrong, but an alternative would have been to make the container decide which of its bordered nodes it wants on which side. It is probably more complex to implement though.