version

Magic Box

This component is not suitable for users who require assistive technologies.
This component is not suitable for use on mobile devices.

The Magic Box component is used as a planning tool, where users drag & drop boxes between containers.

For example, boxes could represent crates and containers represent delivery trucks, with rows representing fullfilment centers and columns representing shipping dates.

The component is more flexible in its layout than Planner or Calendar, but unlike the more specialized components it offers the end user no filters or date navigation tools out of the box.

Columns, rows, and containers

In its most basic form the component is laid out as a grid, with boxes placed in the cells. You can use the optional Containers table to customize individual cells in the grid, for example to set border or background color.

You can put multiple containers in the same cell, which makes each container a sub-column inside that cell, and then put boxes into the individual containers. You can use row span to make a container span over more than one grid row.

Drop groups

Drop groups are an advanced, optional feature, used when you have boxes that represent incompatible concepts. Boxes can only interact with boxes and containers assigned to the same drop group. For example, you could have different containers representing parking garages and docks, and boxes representing cars and boats, and then use drop groups to prevent users from putting a car in a dock.

The four drop groups are null, 'a', 'b', and 'c', so in the example above you might put cars and garages into the null group and boats and docks in the 'a' group.

Drop groups should only be used when it is immediately obvious to the end user which boxes and containers are incompatible, as the only visual indication they will get is that the cursor will indicate that a drop is not allowed when dragging a box over a container from another drop group.

Security considerations

The procedure must carefully check the values passed to the Drag and drop call.

An attacker can not inject their own id values: only boxes shown in the component can be dragged and they can only be dropped on containers shown in the component. An attacker can however manipulate any boxes that were shown when they opened the menu item, even if they would no longer be returned if the procedure was called again.

An attacker can forge a drag of any box dropped on any container. The CanDrag, CanReorder, CanDrop, and DropGroup columns are not enforced.

SQL

SQL Call: Initial layout (mandatory)

Gets columns, rows, containers, and boxes.

May modify database: No

Resultset: Settings (optional)

Optional table with settings controlling the view.

Table count: repeated zero or one time

Row count: exactly one row

Columns

SyncId optional string

The id to listen for sync events on. Required when the component uses collaborative editing.

SyncTimestamp optional string

Arbitrary timestamp to keep track of the latest client sync moment. Required when the component uses collaborative editing.

BoxHeightMin optional decimal

Minimum height in units for a box.

LabelX optional string

Label on x-axis.

LabelY optional string

Label on y-axis. Only works properly in Internet Explorer.

ScaleX optional decimal

How many pixels to use for 1 width unit.

ScaleY optional decimal

How many pixels to use for 1 height unit.

TableLayout optional string

How boxes flow inside containers.

Possible value	Description
BottomToTop	The first box starts at the bottom of the container, and following boxes are placed above it.
TopToBottom	The first box starts at the top of the container, and following boxes are placed below it.

Resultset: Columns

Table count: repeated exactly once

Row count: one or more rows

Columns

BackgroundColor optional string

Default background color for column's containers. See Colors.

CanDrop optional bit

Default droppability for column's containers. If also specified for rows, both row and column must set CanDrop to 1 for a container be droppable.

ColumnId mandatory string

Column ID.

ColumnWidth optional decimal

Default width (in units) for column's containers.

HeadingHTML optional string

Column heading. Styled HTML. Overrides HeadingText column.

HeadingText optional string

Column heading. Plain text. Shown in bold.

LineColor optional string

Default color for column's containers's left and right border. See Colors.

ToolTip optional string

Column header tooltip. Plain text.

Resultset: Rows

Table count: repeated exactly once

Row count: one or more rows

Columns

BackgroundColor optional string

Default background color for row's containers. See Colors.

CanDrop optional bit

Default droppability for row's containers. If also specified for columns, both row and column must set CanDrop to 1 for a container be droppable.

HeadingHTML optional string

Row heading. Styled HTML. Overrides HeadingText column.

HeadingText optional string

Row heading. Plain text. Shown in bold.

LineColor optional string

Default color for row's containers's top and bottom border. See Colors.

RowHeight optional decimal

Default height (in units) for row's containers.

RowId mandatory string

Row ID.

ToolTip optional string

Row header tooltip. Plain text.

Resultset: Containers (optional)

Optional table with container information.

Containers are usually mapped to cells on a 1:1 basis, but you can have more than one container in the same cell if you need to.

You do not need to declare containers for every cell, only for those where you want to specify attributes (like heading text or passing fields).

Table count: repeated zero or one time

Row count: zero or more rows

Columns

BackgroundColor optional string

Container's background color. See Colors.

BorderColor optional string

Container's border color. See Colors.

CanDrop optional bit

If boxes can be dropped on container.

ColumnID mandatory string

Column to show container in.

ContainerHeight optional decimal

Container's min height. Containers always expand to contain their boxes.
Container height defaults to the row-table's RowHeight value and there's usually no need to assign an explicit height to a container.

ContainerID optional string

Container ID. Useful if you show more than one container in the same cell.

ContainerWidth optional decimal

Container's width.

DropGroup optional string

Only boxes with the same drop group can be dropped into the container. Return NULL or omit the column to use the default drop group. See the section on Drop groups above for details.

HeadingHTML mandatory string

Container's heading. Styled HTML. Overrides HeadingText.

HeadingText mandatory string

Container's heading. Plain text.

RowID mandatory string

Row to show container in.

RowSpan optional int

How many rows the container should span over. If more than one container share the same cell then then all containers in that cell must have the same row span.

When using row span, you must not put any boxes or containers into the rows that you span over. That is, if you in column 1 on row 1 have a container with row span 2, then you can't put any boxes in column 1 on row 2, since that row is "covered" by the container above it.

Stripes optional string

Extra bands of background color. Declared like this:

'5.5 #ff0000; 1.2 green; 2.2 #00f'

See Colors.

Resultset: Boxes

Table count: repeated exactly once

Row count: zero or more rows

Columns

BoxId mandatory string

Box ID.

BackgroundColor optional string

Box's background color. See Colors.

BorderColor optional string

Box's border color. See Colors.

BoxHeight mandatory decimal

Box height (in units). If smaller than the specified minimum height for boxes (see the first table) that height is used instead.

BoxHTML optional string

Box's content. Styled HTML. Overrides BoxText.

BoxLayoutedHTML optional string

Box's content. Layouted HTML. Overrides BoxText and BoxHTML.

BoxStyle optional string

CSS declaration. Must be well-formed CSS. Changing border width, padding, etc, will ruin box layout, so don't do it. Never use a string from a user as part of this column for security reasons.

BoxText optional string

Box's content. Plain text.

CanDrag optional bit

If the box can be dragged and dropped on containers where CanDrop = 1.

CanReorder optional bit

If the box can be dragged and reordered with regards to other boxes where CanReorder = 1

ColumnId optional string

Column to show box in. You must specify either RowID and ColumnID or ContainerID.

ContainerId optional string

Row to show box in. You must specify either ContainerID or RowID and ColumnID.

DropGroup optional string

Boxes can only be dropped into containers with the same drop group. Return NULL or omit the column to use the default drop group. See the section on Drop groups above for details.

RowId optional string

Row to show box in. You must specify either RowID and ColumnID or ContainerID.

ShadeBox optional bit

If true, semi-transparent stripes will be drawn above the box's background.

Tooltip optional string

Box's tooltip. Plain text.

SQL Call: Drag and drop

Called when user has dragged and dropped a box.

May modify database: Yes

Parameters

@BoxIDDrag string

Box that was dragged.

@BoxIDDrop string

Box that the dragged box was dropped above/below.

@ColumnIDDrop string

Column where box was dropped.

@ContainerIDDrop string

Container where box was dropped.

@DropLocation int

Where dragged box was dropped, in relation to the box it was dropped on.

Possible value	Description
1	Below
-1	Above

@RowIDDrop string

Row where box was dropped.

Resultset: Boxes (optional)

If present, a partial update of the page is made using the boxes contained in this table. Otherwise the whole box view is reloaded.

Note that partial updates can't be used together with ADMIN_FORCE. After the user has clicked OK the whole box view is always reloaded.

Table count: repeated zero or one time

Row count: zero or more rows

Columns

BoxId mandatory string

Box ID.

BackgroundColor optional string

Box's background color. See Colors.

BorderColor optional string

Box's border color. See Colors.

BoxHeight mandatory decimal

Box height (in units). If smaller than the specified minimum height for boxes (see the first table) that height is used instead.

BoxHTML optional string

Box's content. Styled HTML. Overrides BoxText.

BoxLayoutedHTML optional string

Box's content. Layouted HTML. Overrides BoxText and BoxHTML.

BoxStyle optional string

CSS declaration. Must be well-formed CSS. Changing border width, padding, etc, will ruin box layout, so don't do it. Never use a string from a user as part of this column for security reasons.

BoxText optional string

Box's content. Plain text.

CanDrag optional bit

If the box can be dragged and dropped on containers where CanDrop = 1.

CanReorder optional bit

If the box can be dragged and reordered with regards to other boxes where CanReorder = 1

ColumnId optional string

Column to show box in. You must specify either RowID and ColumnID or ContainerID.

ContainerId optional string

Row to show box in. You must specify either ContainerID or RowID and ColumnID.

DropGroup optional string

Boxes can only be dropped into containers with the same drop group. Return NULL or omit the column to use the default drop group. See the section on Drop groups above for details.

IsDeleted optional bit

Return 1 to remove a box from the page during a partial update.

RowId optional string

Row to show box in. You must specify either RowID and ColumnID or ContainerID.

ShadeBox optional bit

If true, semi-transparent stripes will be drawn above the box's background.

Tooltip optional string

Box's tooltip. Plain text.

Resultset: Raise sync entity (optional)

This SQL call may use SoftadminApi.SyncEntity_RaiseChanged.

Table count: repeated zero or more times

Row count:

Columns

SQL Call: Client sync

Called when a sync entity change is raised for the entity and id that the component listens to.

May modify database: No

Parameters

@Action string

Will be set to 'ClientSync'.

@SyncId string

The sync id that was retrieved from the initial SQL call.

@SyncTimestamp string

The sync timestamp from when the component was last synced.

Resultset: Boxes (optional)

If present, a partial update of the page is made using the boxes contained in this table. Otherwise the whole box view is reloaded.

Table count: repeated zero or one time

Row count: zero or more rows

Columns

BoxId mandatory string

Box ID.

BackgroundColor optional string

Box's background color. See Colors.

BorderColor optional string

Box's border color. See Colors.

BoxHeight mandatory decimal

Box height (in units). If smaller than the specified minimum height for boxes (see the first table) that height is used instead.

BoxHTML optional string

Box's content. Styled HTML. Overrides BoxText.

BoxLayoutedHTML optional string

Box's content. Layouted HTML. Overrides BoxText and BoxHTML.

BoxStyle optional string

CSS declaration. Must be well-formed CSS. Changing border width, padding, etc, will ruin box layout, so don't do it. Never use a string from a user as part of this column for security reasons.

BoxText optional string

Box's content. Plain text.

CanDrag optional bit

If the box can be dragged and dropped on containers where CanDrop = 1.

CanReorder optional bit

If the box can be dragged and reordered with regards to other boxes where CanReorder = 1

ColumnId optional string

Column to show box in. You must specify either RowID and ColumnID or ContainerID.

ContainerId optional string

Row to show box in. You must specify either ContainerID or RowID and ColumnID.

DropGroup optional string

Boxes can only be dropped into containers with the same drop group. Return NULL or omit the column to use the default drop group. See the section on Drop groups above for details.

IsDeleted optional bit

Return 1 to remove a box from the page during a partial update

RowId optional string

Row to show box in. You must specify either RowID and ColumnID or ContainerID.

ShadeBox optional bit

If true, semi-transparent stripes will be drawn above the box's background.

Tooltip optional string

Box's tooltip. Plain text.

Resultset: Sync Timestamp

Updated sync timestamp that will be sent as a parameter to the next client sync call.

Table count: repeated exactly once

Row count: exactly one row

Columns

SyncTimestamp mandatory string

The timestamp.

SQL Call: Validate parameters

Allows you to validate the SQL parameters before any other SQL is run in the component. This call is only made if the SQL is a stored procedure and Validate parameters is checked.

May modify database: No

Parameters

@Force bit

Set to 1 if the last call to validate parameters used admin_force and the user clicked OK in the OK/Cancel dialog.

@ValidateParams bit

Set to 1 when this call is made.

Resultset: Messages (optional)

Table count: repeated zero or one time

Row count: zero or one row

Columns

ADMIN_Force optional string

Message asking the end user to confirm their parameters.

ADMIN_Message optional string

Message explaining why the parameters are rejected.

InfoSQL

See the InfoSQL documentation for details.

Custom access control and logging

SQL Call: Custom access control and logging

Use this call to restrict which entries a user is allowed to view and edit, and to log which entries a user views.

Access to a menu item is normally controlled through functions and roles alone but some entities need more fine grained control. For example, a user may have access to the View Member menu item for normal members but not for members with a protected identity.

The menu items a user visits are always logged (in ADMINLogMenuItem) but for sensitive data you may need to log exactly what entries are viewed. Do the logging in this call as the common ways of viewing data (grid and InfoSQL) are not allowed to modify the database.

If you bind a scalar function instead of a stored procedure to this call then its name must end with '_GrantAccess'.

May modify database: Yes

Resultset: Access permissions

Return whether the user is allowed to visit the menu item with the current parameters.

Table count: repeated exactly once

Row count: exactly one row

Columns

GrantAccess mandatory bit

1 if the user is allowed to view the menu item, 0 if the user should not be allowed to view the menu item.

If 0 then an error will be logged as the user should not have been able to reach the menu item with the given parameters in the first place.

Querystring parameters

menuitemheading optional

String that replaces the menu item name when the menu item is loaded. It does not replace the name before that (like for example in the navigator). It is ignored if the menu item is displayed as a part in a multipart in which case the name can be set from the multipart procedure.

Examples

Minimal example

CREATE OR ALTER PROCEDURE dbo.Example_MagicBox
AS
BEGIN
	SET NOCOUNT, XACT_ABORT ON;

	SELECT
		NR.n AS ColumnId
	FROM
		SoftadminUtil.Number_Range(1, 2) NR

	SELECT
		NR.n AS RowId
	FROM
		SoftadminUtil.Number_Range(1, 2) NR

	SELECT
		NR.n BoxId,
		NR.n AS ColumnId,
		NR.n AS RowId,
		50 AS BoxHeight,
		'test' AS BoxText
	FROM
		SoftadminUtil.Number_Range(1, 2) NR
END;