Difference between revisions of "ACP Flexbox"
(Rewrote page for end user)
Line 1: Line 1:
−
From the Draft spec Google Doc:
+
Use ACP FlexBox to make ACP diagrams responsive to the size of the browser window! With FlexBox, ACP will automatically rearrange text boxes, frame nodes, and other nodes to fit the browser window. FlexBox is automatically available to all users using ACP.
  
−
ACP FlexBox borrows from the CSS Flexbox to make ACP layouts ''responsive'' to the width of the browser window to make ACP more useable on phones and tablets. For example, if a diagram contains text, and frame or tall nodes arranged from left to right in diagram in Desktop Analytica, when viewed in ACP on a narrow screen, Flexbox may rearrange the text nodes one above the other.
+
== What does it do? ==
 +
ACP FlexBox borrows from [https://www.w3schools.com/csS/css3_flexbox.asp CSS FlexBox] to allow you to turn nodes such as Text Nodes into FlexBox items that are automatically displayed in a line and automatically wrap to the next line where there is not enough space for them on the current line like so:
 +
{| class="wikitable"
 +
|+Examples images of what FlexBox does in ACP models
 +
!Wide window
 +
!Narrow window
 +
|-
 +
| rowspan="2" |[[File:1a widewindow.png|frameless]]
 +
|Without FlexBox
 +
[[File:1c narrowwindownoflex.png|frameless]]
 +
|-
 +
|With FlexBox
 +
[[File:1b narrowwindow.png|frameless]]
 +
|}
 +
Items contained in FlexBox items are not responsive, meaning they will keep their layout within the FlexBox item and will not change their size or location within the FlexBox even if the browser window changes size. If the window is too small to accommodate an entire FlexBox item, a scrollbar will appear.
 +
[[File:2 scrollbars.png|none|thumb|364x364px|Example of a window that is too small to accommodate a FlexBox item and is showing scrollbars ]]
  
−
==Status==
 
  
−
The current implementation is partial and experimental for testing ideas.  From EW 1955: This is just a first step. There are still a lot of things to do to get this feature complete. It's likely the specs for the feature will change and that the current demo may not work in the future.
+
Note that diagram arrows in FlexBox items will '''not''' be displayed.
  
−
==Example model==
+
== How to use it ==
−
You can use this Example model which is included in the EW issues. [[File:Market Model Demo.ana]]
+
To use FlexBox, you’ll need to set a diagram or module to be a FlexBox container, and then set nodes inside the FlexBox container as FlexBox items. You can set FlexBox containers and FlexBox items using the ACP styles attribute. This section will cover the following steps:
−
*Explanation:
 
−
*In the top level diagram, add cps style <code>'''''display: flex</code>''''' – Specifies that the diagram is a FlexBox Container.
 
−
**In the large text boxes, add '''''<code>flex_box_item: yes</code>'''''.
 
−
**The frame node is included by default.
 
  
−
'''Expected: On the diagram, the two large text nodes with inputs / outputs and pictures appear. And there's a frame node. The node Va1 and the Analytica logo also have been added as flex box items.'''
+
# How to enable the ACP styles attribute
 +
# Set a diagram or module to be a FlexBox container
 +
# Set nodes inside the FlexBox container to be FlexBox items
  
−
== FlexBox items==
+
=== Enable ACP Styles ===
 +
To use FlexBox you will need to manually update ACP styles attributes. You can do this in Desktop Analytica using the [[attribute panel]]. You can enable the ACP Styles attribute directly from the attribute panel for individual nodes if it is not an existing option, but to enable it for all nodes you can follow the steps below:
  
−
If you specify a  top level diagram as a Flexbox Container using ACP Style,
+
# Go to the '''Object''' menu
−
<code>'''''display: flex</code>'''''
+
# Go to '''Attributes…''' to open the [[Attributes dialog]]
−
it treats any large Text node <How large?> that contains input and output nodes, Tall nodes and Frame nodes as items that can be rearranged within . Later we might add other node types as FlexBox Item e.g. Picture nodes.
+
# Double click on ACP Styles so it has a checkbox next to it
 +
# Press OK
  
−
Within a Flexbox container, it does not display any nodes that are not FlexBox Items or contained within a FlexBox Item.
+
Note that you will need to do this for both Variables and Module classes to have ACP Styles show up for both classes of nodes. By default, the Attributes dialog changes settings for Variables. Go to the dropdown at the top of the dialog to select Modules and enable ACP Styles for modules as well.
  
 +
You can now add the FlexBox ACP styles into the attribute panel. If there are existing ACP styles, just enter the FlexBox setting on a new line.
  
−
==Module Level AcpStyles==
+
=== FlexBox containers ===
−
===ER 1955 - Flex Box layout ===
+
To enable FlexBox, add the following ACP style attribute into the the top-level diagram (the Module you want to enable FlexBox for):
  
−
*In the top level diagram, add cps style .
+
* '''display: flex'''
−
<code>'''''display: flex</code>''''' – Specifies that the diagram is a FlexBox Container.
 
  
−
===ER 1956 - Flex Direction===
+
[[File:3 flexattribute.png|none|thumb|Attribute panel where FlexBox is enabled]]
−
'''''<code>flex_direction: row</code>''''' (default) or '''''<code>flex_direction: column</code>'''''– Specifies that flex boxes be arranged horizontally or vertically in the Flex Container.
 
−
===ER 1957 - Flex Wrap===
 
−
'''''<code>flex_wrap: wrap</code>''''' (default) or '''''<code>flex_wrap: no_wrap</code>''''' – Specifies that FlexBox items should wrap -- i.e. when displayed horizontally, items that would exceed the width of the Container, will be put on next row beneath the initial items.
 
  
−
==Node Level AcpStyles==
 
  
−
'''''<code>flex_box_item: yes</code>''''' or '''''<code>flex_box_item: no</code>''''' - Specifies whether or not a node should be treated as a FlexBox Item.  The default would be Yes for Tall Nodes and Frame Nodes, and No for other node classes.
+
This turns that diagram into a Flexbox container that can contain FlexBox items. Once a diagram is turned into a FlexBox container, only FlexBox items or nodes entirely contained inside a FlexBox item will be visible in ACP.
  
−
==Implemented in ACP Build 138==
+
=== FlexBox items ===
−
*flex_v_align: top (default), center or bottom – Specifies the vertical alignment of the FlexBox Items.
+
The FlexBox items are the blocks that actually line up and wrap to the next line. Any nodes used to build diagrams (e.g., variables, indexes, modules, or libraries) can be FlexBox items. Input and output nodes and buttons cannot be FlexBox items.
−
*flex_h_align: left (default), center or right – Specifies the horizontal alignment of the FlexBox Items.
+
 
−
*flex_gap: Number of pixels  8  (default) – Specifies the gap or margin between FlexBox items.
+
To turn nodes into FlexBox items, add the following ACP style attribute to the node:
 +
 
 +
* '''flex_box_item: yes'''
 +
 
 +
By default, Frame nodes have the ACP style f'''lex_box_item: yes''' but other nodes will be set to '''flex_box_item: no'''.
 +
 
 +
FlexBox automatically puts all FlexBox items into a single line and does not preserve the exact location of FlexBox items in Desktop Analytica, i.e., you can see below how the two FlexBox item text boxes are not aligned in desktop but are aligned in ACP.
 +
{| class="wikitable"
 +
|+Examples of how FlexBox aligns FlexBox items
 +
!Desktop
 +
!ACP
 +
|-
 +
|[[File:4a alignmentDTA.png|frameless]]
 +
|[[File:4b alignmentACP.png|frameless]]
 +
|}
 +
The order in which FlexBox lines up items is based on their '''vertical position''' from the top of the screen. The higher their position, the earlier in FlexBox’s order they will be. If two nodes have the same vertical position, the leftmost node will come first, e.g.:
 +
{| class="wikitable"
 +
|+Examples of what order FlexBox aligns FlexBox items in
 +
!Desktop
 +
!ACP
 +
|-
 +
|[[File:5a DTAnodes.png|frameless]]
 +
|[[File:5b ACPnodes.png|frameless]]
 +
|}
 +
The simplest way to use FlexBox items is to turn Text or Frame nodes into FlexBox items and put the nodes you want to display inside those Text nodes. Nodes must be entirely contained inside the parent FlexBox item to show up in ACP. Any nodes that are not FlexBox items and not entirely contained inside a FlexBox item will not be visible at all in a FlexBox container diagram; see the below example where all nodes aside from the FlexBox item text node are not FlexBox items:
 +
{| class="wikitable"
 +
|+Examples of what is excluded from FlexBox items
 +
!Desktop
 +
!ACP
 +
|-
 +
|[[File:6a nodecontainexDTA.png|frameless]]
 +
|[[File:6b nodecontainexACP.png|frameless]]
 +
|}
 +
FlexBox items do not nest. Even if a FlexBox item is contained entirely inside another FlexBox item, it will still be included as its own FlexBox item, e.g.:
 +
{| class="wikitable"
 +
|+Examples of how nested FlexBox items display
 +
!Desktop
 +
!ACP
 +
|-
 +
|[[File:7a nestingDTA.png|frameless]]
 +
|[[File:7b nestingACP.png|frameless]]
 +
|}
 +
Note that FlexBox does not work with the ACP Style auto zoom. If both auto zoom is enabled and a FlexBox container is designated, ACP will not auto zoom. Only FlexBox will be enabled.
 +
 
 +
== Settings ==
 +
These settings should be added to the ACP styles attributes of the top-level diagram where flex_display is set.
 +
 
 +
=== Flex direction ===
 +
This attribute sets the direction of the line of FlexBox items.
 +
 
 +
* '''flex_direction: row''' (default) displays FlexBox items are horizontally in rows
 +
* '''flex_direction: column''' display the FlexBox items vertically in columns
 +
 
 +
The following images show examples of how Flex direction affects the display of items. Notice how the nodes are displayed in a different direction and therefore when nodes wrap to the next line the overall arrangement of nodes differs.
 +
[[File:8a DTAarrangement.png|none|thumb|Example arrangement in Desktop Analytica]]
 +
{| class="wikitable"
 +
|+How the example desktop arrangement displays with different Flex direction settings
 +
!Flex direction: Row (default)
 +
!Flex direction: Column
 +
|-
 +
|[[File:5b ACPnodes.png|frameless]]
 +
|[[File:8c ACPcol.png|frameless|216x216px]]
 +
|-
 +
|[[File:8d ACPrownarrow.png|frameless]]
 +
|[[File:8e ACPcolnarrow.png|frameless]]
 +
|}
 +
 
 +
=== Flex wrap ===
 +
Use Flex wrap to turn off flex wrapping.
 +
 
 +
* '''flex_wrap: wrap''' (default) turns on flex wrap, which is what tells the FlexBox items to automatically wrap to the next row when the window is too small to fit the FlexBox items in the selected flex direction
 +
* '''flex_wrap: no_wrap''' turns off flex wrap so items will not automatically break to the next line. FlexBox items will still rearrange themselves on a single line by shrinking the gap between items as the browser window shrinks to show all of the nodes in the screen, e.g.: [[File:5b ACPnodes.png|frameless|551x551px]]  will turn into the following when wrap is turned off and the window is narrowed: [[File:9b narrowwrap.png|frameless|549x549px]]
 +
 
 +
=== Flex vertical alignment ===
 +
This attribute sets where the FlexBox items display vertically in the browser window.
 +
 
 +
* '''flex_v_align: top''' (default) vertically aligns FlexBox items to the top of the browser window, like so:  [[File:10a aligntop.png|frameless]]
 +
* '''flex_v_align: center''' vertically aligns FlexBox items to the center of the browser window
 +
* '''flex_v_align: bottom''' vertically aligns FlexBox items to the bottom of the browser window, like so:  [[File:10c alignbottom.png|frameless]]
 +
 
 +
=== Flex horizontal alignment ===
 +
This attribute sets where the FlexBox items display horizontally in the browser window.
 +
 
 +
* '''flex_h_align: left''' (default) horizontally aligns FlexBox items to the left of the window
 +
* '''flex_h_align: center''' horizontally aligns FlexBox items to the center of the window
 +
* '''flex_h_align: right''' horizontally aligns FlexBox items to the right of the window
 +
 
 +
Note that for center and right horizontal alignment, the items will automatically realign to the center or right, respectively, if the browser size is changed.
 +
 
 +
=== Flex gap ===
 +
 
 +
* '''flex_gap: x''' where x is a number sets the gap between FlexBox items to x pixels. By default the flex_gap is set to 8 pixels

Revision as of 02:48, 8 November 2024

Use ACP FlexBox to make ACP diagrams responsive to the size of the browser window! With FlexBox, ACP will automatically rearrange text boxes, frame nodes, and other nodes to fit the browser window. FlexBox is automatically available to all users using ACP.

What does it do?

ACP FlexBox borrows from CSS FlexBox to allow you to turn nodes such as Text Nodes into FlexBox items that are automatically displayed in a line and automatically wrap to the next line where there is not enough space for them on the current line like so:

Examples images of what FlexBox does in ACP models
Wide window Narrow window
1a widewindow.png Without FlexBox

1c narrowwindownoflex.png

With FlexBox

1b narrowwindow.png

Items contained in FlexBox items are not responsive, meaning they will keep their layout within the FlexBox item and will not change their size or location within the FlexBox even if the browser window changes size. If the window is too small to accommodate an entire FlexBox item, a scrollbar will appear.

Example of a window that is too small to accommodate a FlexBox item and is showing scrollbars


Note that diagram arrows in FlexBox items will not be displayed.

How to use it

To use FlexBox, you’ll need to set a diagram or module to be a FlexBox container, and then set nodes inside the FlexBox container as FlexBox items. You can set FlexBox containers and FlexBox items using the ACP styles attribute. This section will cover the following steps:

  1. How to enable the ACP styles attribute
  2. Set a diagram or module to be a FlexBox container
  3. Set nodes inside the FlexBox container to be FlexBox items

Enable ACP Styles

To use FlexBox you will need to manually update ACP styles attributes. You can do this in Desktop Analytica using the attribute panel. You can enable the ACP Styles attribute directly from the attribute panel for individual nodes if it is not an existing option, but to enable it for all nodes you can follow the steps below:

  1. Go to the Object menu
  2. Go to Attributes… to open the Attributes dialog
  3. Double click on ACP Styles so it has a checkbox next to it
  4. Press OK

Note that you will need to do this for both Variables and Module classes to have ACP Styles show up for both classes of nodes. By default, the Attributes dialog changes settings for Variables. Go to the dropdown at the top of the dialog to select Modules and enable ACP Styles for modules as well.

You can now add the FlexBox ACP styles into the attribute panel. If there are existing ACP styles, just enter the FlexBox setting on a new line.

FlexBox containers

To enable FlexBox, add the following ACP style attribute into the the top-level diagram (the Module you want to enable FlexBox for):

  • display: flex
Attribute panel where FlexBox is enabled


This turns that diagram into a Flexbox container that can contain FlexBox items. Once a diagram is turned into a FlexBox container, only FlexBox items or nodes entirely contained inside a FlexBox item will be visible in ACP.

FlexBox items

The FlexBox items are the blocks that actually line up and wrap to the next line. Any nodes used to build diagrams (e.g., variables, indexes, modules, or libraries) can be FlexBox items. Input and output nodes and buttons cannot be FlexBox items.

To turn nodes into FlexBox items, add the following ACP style attribute to the node:

  • flex_box_item: yes

By default, Frame nodes have the ACP style flex_box_item: yes but other nodes will be set to flex_box_item: no.

FlexBox automatically puts all FlexBox items into a single line and does not preserve the exact location of FlexBox items in Desktop Analytica, i.e., you can see below how the two FlexBox item text boxes are not aligned in desktop but are aligned in ACP.

Examples of how FlexBox aligns FlexBox items
Desktop ACP
4a alignmentDTA.png 4b alignmentACP.png

The order in which FlexBox lines up items is based on their vertical position from the top of the screen. The higher their position, the earlier in FlexBox’s order they will be. If two nodes have the same vertical position, the leftmost node will come first, e.g.:

Examples of what order FlexBox aligns FlexBox items in
Desktop ACP
5a DTAnodes.png 5b ACPnodes.png

The simplest way to use FlexBox items is to turn Text or Frame nodes into FlexBox items and put the nodes you want to display inside those Text nodes. Nodes must be entirely contained inside the parent FlexBox item to show up in ACP. Any nodes that are not FlexBox items and not entirely contained inside a FlexBox item will not be visible at all in a FlexBox container diagram; see the below example where all nodes aside from the FlexBox item text node are not FlexBox items:

Examples of what is excluded from FlexBox items
Desktop ACP
6a nodecontainexDTA.png 6b nodecontainexACP.png

FlexBox items do not nest. Even if a FlexBox item is contained entirely inside another FlexBox item, it will still be included as its own FlexBox item, e.g.:

Examples of how nested FlexBox items display
Desktop ACP
7a nestingDTA.png 7b nestingACP.png

Note that FlexBox does not work with the ACP Style auto zoom. If both auto zoom is enabled and a FlexBox container is designated, ACP will not auto zoom. Only FlexBox will be enabled.

Settings

These settings should be added to the ACP styles attributes of the top-level diagram where flex_display is set.

Flex direction

This attribute sets the direction of the line of FlexBox items.

  • flex_direction: row (default) displays FlexBox items are horizontally in rows
  • flex_direction: column display the FlexBox items vertically in columns

The following images show examples of how Flex direction affects the display of items. Notice how the nodes are displayed in a different direction and therefore when nodes wrap to the next line the overall arrangement of nodes differs.

Example arrangement in Desktop Analytica
How the example desktop arrangement displays with different Flex direction settings
Flex direction: Row (default) Flex direction: Column
5b ACPnodes.png 8c ACPcol.png
8d ACPrownarrow.png 8e ACPcolnarrow.png

Flex wrap

Use Flex wrap to turn off flex wrapping.

  • flex_wrap: wrap (default) turns on flex wrap, which is what tells the FlexBox items to automatically wrap to the next row when the window is too small to fit the FlexBox items in the selected flex direction
  • flex_wrap: no_wrap turns off flex wrap so items will not automatically break to the next line. FlexBox items will still rearrange themselves on a single line by shrinking the gap between items as the browser window shrinks to show all of the nodes in the screen, e.g.: 5b ACPnodes.png will turn into the following when wrap is turned off and the window is narrowed: 9b narrowwrap.png

Flex vertical alignment

This attribute sets where the FlexBox items display vertically in the browser window.

  • flex_v_align: top (default) vertically aligns FlexBox items to the top of the browser window, like so: 10a aligntop.png
  • flex_v_align: center vertically aligns FlexBox items to the center of the browser window
  • flex_v_align: bottom vertically aligns FlexBox items to the bottom of the browser window, like so: 10c alignbottom.png

Flex horizontal alignment

This attribute sets where the FlexBox items display horizontally in the browser window.

  • flex_h_align: left (default) horizontally aligns FlexBox items to the left of the window
  • flex_h_align: center horizontally aligns FlexBox items to the center of the window
  • flex_h_align: right horizontally aligns FlexBox items to the right of the window

Note that for center and right horizontal alignment, the items will automatically realign to the center or right, respectively, if the browser size is changed.

Flex gap

  • flex_gap: x where x is a number sets the gap between FlexBox items to x pixels. By default the flex_gap is set to 8 pixels
Comments


You are not allowed to post comments.