Displays a form that is edited/inserted into the database.
Component mode: Duplicate record
Shows an existing record in the form and saves it as a new record.
Introduction
The NewEdit component presents a number of input fields for inserting, updating or duplicating a record in the database (see "Component mode"). There are different kinds of input fields ("Controls") for different kinds of data, such as text boxes, drop-down lists and so on. For a list of the available controls and their functionality, refer to "Controls" in the Softadmin® documentation. Here we will focus on how the controls can be presented and grouped within a NewEdit menu item.
Columns
You can split the input fields in columns. In the above example there are three columns.
If the browser window is too narrow, the input fields will not rearrange. Instead you will get a horizontal scrollbar.
Buttons
The default buttons are "Save" and "Cancel", but you can change their wording, or specify a completely different set of buttons.
Confirm close
To prevent losing data, the NewEdit component will raise a warning if you try to leave the page without saving changes. It does not appear if you have not made any change to any of the input fields. The warning also appears if you close the browser window.
JavaScript button
Every control can display one or more buttons to their right. In this example, the dropdown list with available customers is accompanied by a "New customer" button.
It opens a menu item to create a new customer, displayed in a popup window.
In this example, the user created a new customer named Carl Carlsson. When the new customer is saved, it is automatically added to the customer dropdown in the "Edit car" menu item. Notice that the user did not have to reenter all the other data, like Model, Year model, Price etc, since the New customer menu item took place in a popup window.
Controls
These are the controls available in the NewEdit component:
- Boolean dropdown
- Checkbox
- Colorpicker
- Date
- Datetime
- Dropdown
- File
- Heading
- Heading (Collapsible)
- Heading with checkbox
- Hidden
- HTML
- Info text
- Listbox
- Multi-control
- Multi-listbox
- Multi-picker
- Multirow
- Password
- Picture
- Radio buttons
- Separator
- Textarea
- Textbox
- Textbox with autosearch
- Textbox with autosuggest
- Textbox with dropdown
- Textbox with popup
- Textbox with redirect
- Time
- Uneditable text
Component settings
SQL
SQL Call: Retrieve record (mandatory)
Retrieves the record to edit in the form.
Parameters
Resultset: Specify number of columns (optional)
Columns
AdminColumns mandatory int
AdminLayout optional string
| Possible value | Description |
|---|---|
| column | The component expects n resultsets to follow and allocates the fields in the same resultset to a separate column. |
| row | The component expects one resultset to follow where the n first fields are allocated to row one, the next n fields to row 2, etc... Fields on the same row will be aligned (middle) with each other. |
Resultset: Fields to edit
Columns
<fieldname> optional string
Resultset: Dynamic field information (optional)
Columns
AdminFieldName mandatory string
AllowHtml optional bit
ButtonJavaScript<xxx> optional string
ButtonJavaScript<xxx>_Label optional string
CellAlignment optional string
The alignment of grid columns and InfoSQL values.
| Possible value | Description |
|---|---|
| center | Only applicable to grid columns. |
| left | |
| right |
ColumnTooltip optional string
DefaultValue optional string
DefaultValueSql optional string
Description optional string
EnabledJavaScript optional string
FieldGroupId optional int
FieldInfoId optional int
FieldLabel optional string
FieldType optional string
| Possible value | Description |
|---|---|
| boolean checkbox | Legacy alias. Use "checkbox" instead. |
| boolean dropdown | |
| chart | |
| checkbox | |
| checkbox tree | |
| colorpicker | |
| date | |
| datetime | |
| dropdown | |
| file | |
| file upload area | |
| heading | |
| heading with checkbox | |
| hidden | |
| html | Legacy alias. Use "html editor" instead. |
| html editor | |
| info text | |
| listbox | |
| multi-autosearch | |
| multi-listbox | |
| multi-picker | |
| multirow | |
| password | |
| picture | |
| radio buttons | |
| radio cards | |
| signature | |
| textarea | |
| textbox | |
| textbox with autosearch | |
| textbox with autosuggest | |
| textbox with dropdown | |
| textbox with popup | |
| time | |
| uneditable text |
Height optional int
IgnoreOnSave optional bit
InfoSqlLayout optional string
| Possible value | Description |
|---|---|
| Default | Inherit layout from menu item. |
| LabelAbove | Full width, label above. |
| LabelLeft | Label to the left. |
| NoLabel | Full width, no label. |
| Standard | Deprecated. Use LabelLeft instead. |
MandatoryJavaScript optional string
JavaScript that controls the mandatory status of the field, this overwrites nullchoice if set. This is only available to control types for which the mandatory JavaScript field is visible in the user interface.
MaxDate optional date
MinDate optional date
NullChoice optional bit
NumberOfDecimals optional int
OnChangeJavaScript optional string
OutputFormat optional string
| Possible value | Description |
|---|---|
| Hyperlink | |
| MailToLink | |
| PhoneLink |
Placeholder optional string
Sql optional string
TextDirection optional string
Which direction the script is written in. Not to be confused with the CellAlignment property.
| Possible value | Description |
|---|---|
| default | System default. Not useful unless you are trying to override an already explicit text direction on existing field information. |
| ltr | Left-to-right (for example English) |
| rtl | Right-to-left (for example Arabic) |
ThousandDelimiter optional string
TimePickerFrom optional string
TimePickerTo optional string
Width optional int
The width of the control.
At one point, this was a pixel value. Back when Softadmin used Verdana 10px, and before fields had width-categories. Now, it is just a value that is converted to a width category.
The possible values listed below are just suggestions. For example, both 1 and 30 will be converted to shortest, and both 500 and 9999 to longest.
| Possible value | Description |
|---|---|
| 150 | Medium-long |
| 30 | Shortest |
| 300 | Long |
| 500 | Longest |
| 60 | Short |
| 90 | Medium short |
VisibleJavaScript optional string
Resultset: Button specification (optional)
Columns
AdminButtonId mandatory string
The specified AdminButtonId is passed to the insert/update procedure in the @AdminButtonId parameter when the button is clicked. Button ID is not used for cancel buttons.
If the ID is NULL, and the button is not a Cancel button, it will be the default save button.
ButtonText optional string
Used to override the default text on the button.
CidStepsBack optional int
Legacy column. Prefer using IsCancelButton instead.
Using CidStepsBack = 1 is equivalent to using IsCancelButton = 1. Behavior is undefined for non-null values other than 1.
EnforceMandatoryFields optional bit
Whether mandatory fields should be forced to contain a value. Used to implement a Save as Draft button, where users are allowed to leave mandatory fields empty in the draft stage but not when submitting the final form.
By default, Save buttons validate mandatory fields. Cancel buttons never do, and is an error to try to make them.
IsCancelButton optional bit
The button acts as a Cancel button, and will not call InsertUpdate when clicked.
IsDefaultButton optional bit
This is the default button. Its appearance will be distinct from the other buttons, and the enter and ctrl+s shortcuts will click it. There should be exactly one Default button.
PhraseId optional string
Phrase ID for the text of the button.
Resultset: JavaScript lookup functions (optional)
If you have fixed lookup tables that fields need for visibility scripts then you can have NewEdit generate JavaScript lookup functions.
For example
SELECT
ComponentId AS ADMINJavaScriptLookup,
HasComponentSql AS componentHasSql,
HasInfoSql AS componentHasInfoSql
FROM dbo.ADMINComponent
Columns
ADMINJavaScriptLookup mandatory int
xxx mandatory int
For each column xxx a JavaScript function xxx is generated. The function maps the id values in the ADMINJavaScriptLookup-column to the values in the xxx-column.
If this is a bit column then the SQL value 1 is converted to the JavaScript value true, and both 0 and NULL are converted to false.
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.
Parameters
Resultset: Messages (optional)
Columns
ADMIN_Force optional string
ADMIN_Message optional string
Insert/Update/Delete SP
SQL Call: Insert record (mandatory)
Inserts a new record into the database.
NOTE: Fields that both have validation and are hidden (e.g. with Visibility JavaScript) are passed as NULL to the procedure.
May use SoftadminApi.Progress_SetTitle and SoftadminApi.Progress_SetStep.
Parameters
Resultset: Clear cache and forwarding definitions (optional)
Columns
ADMIN_ErrorMessage optional string
Displays a user friendly error message to the user. This blocks any forwarding for the user.
ADMIN_ConfirmDelete optional string
Displays a user friendly confirmation message to the user with a delete button as the confirm button. If the user chooses OK the SQL call will be rerun with the parameter @ButtonAction set to 'Delete'.
ADMIN_ConfirmQuestion optional string
Displays a user friendly confirmation message to the user with a question style. If the user chooses OK the SQL call will be rerun with the parameter @ButtonAction set to 'Confirm'.
ADMIN_ConfirmWarning optional string
Displays a user friendly confirmation message to the user with a warning style. If the user chooses OK the SQL call will be rerun with the parameter @ButtonAction set to 'Confirm'.
ADMIN_InfoMessage optional string
Displays a user friendly info message to the user. When the user clicks OK the user is forwarded.
ADMIN_SuccessMessage optional string
Displays a user friendly success message to the user. When the user clicks OK the user is forwarded.
ADMIN_Dialog optional string
The dialog alias of a predefined dialog to show the user. Must be the first column in the result set table. Use multiple result set tables to combine with other forwarding.
Use the menu item "Admin > Dialogs" to register new dialogs or find aliases for existing ones.
<xxx> (for ADMIN_Dialog) optional any
Any column without special meaning in the result set with the first column ADMIN_Dialog will be used to make replacements of placeholders in the message and title text.
ADMIN_DebugInfo optional string
Additional information to show the developer when using ADMIN_Dialog.
<passing_field> optional string
ADMIN_CancelCidStepsBack optional int
ADMIN_CancelReturnToMenuItem optional string
ADMIN_CancelMenuItem optional string
ADMIN_CancelMenuItemId optional int
Deprecated. Use ADMIN_CancelMenuItem instead.
Id of the menuitem to execute if the user clicks Cancel in an ADMIN_FORCE dialog (the default being none). This value overrides cancelmenuitemid specified in the query string.
ADMIN_CidStepsBack optional int
ADMIN_ReturnToMenuItem optional string
ADMIN_Force optional string
ADMIN_Forward optional string
ADMIN_ForwardLink optional string
ADMIN_ForwardMenuGroup optional string
Alias of the menu group to show after execution (instead of former menu item). This value overrides any destination specified by the query string.
ADMIN_ForwardMenuGroupId optional int
Deprecated. Use ADMIN_ForwardMenuGroup instead.
Id of the menu group to show after execution (instead of former menu item). This value overrides any destination specified by the query string.
ADMIN_ForwardMenuItem optional string
ADMIN_ForwardMenuItemId optional int
Deprecated. Use ADMIN_ForwardMenuItem instead.
Id of the menu item to execute after execution (instead of former menu item). This value overrides any destination specified by the query string.
ADMIN_Message optional string
Displays a user friendly error message to the user.
ADMIN_PasteHtmlFromPopup optional string
ADMIN_SetFieldValueFromPopup optional string
ADMIN_ClosePopup optional bit
ADMIN_ClosePopupAndReloadOpener optional bit
If this column is anything but NULL the popup will be closed and the parent will be reloaded. Only select this column if the menu item is opened in a popup. Avoid using this feature if the opener is a newEdit as that may interrupt the user's ongoing input.
ADMIN_Unselect optional bit
ADMIN_UnselectAll optional bit
ADMIN_ClearHistory optional any
ADMIN_RefreshMenu optional bit
Cache optional string
CacheUserId optional string
Clears all caches (e.g. access permissions) related to the specified user id.
Use '%' to clear caches for all users.
CancelButtonText optional string
Changes the text of the Cancel button when used with ADMIN_Force, ADMIN_ConfirmWarning, ADMIN_ConfirmQuestion, ADMIN_ConfirmDelete.
OkButtonText optional string
Changes the text of the OK button when used with ADMIN_ErrorMessage, ADMIN_ConfirmWarning, ADMIN_ConfirmQuestion, ADMIN_ConfirmDelete, ADMIN_InfoMessage, ADMIN_SuccessMessage, ADMIN_Message, ADMIN_Force, or ADMIN_Forward. ADMIN_Force,
Resultset: Raise sync entity (optional)
This SQL call may use SoftadminApi.SyncEntity_RaiseChanged.
Columns
InfoSQL
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'.
Resultset: Access permissions
Columns
GrantAccess mandatory bit
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
Examples
How to handle transactions
Avoid using nested transactions (since only the outermost matters regarding ROLLBACK or COMMIT). The following code only starts transactions when necessary, ie if one has not already been started. Make sure to look at the @IsUsingLocalTransaction parameter before any COMMITs or ROLLBACKs.
-----------------------
-- Begin transaction --
-----------------------
DECLARE
@IsUsingLocalTransaction bit
IF @@TRANCOUNT = 0
BEGIN
SET XACT_ABORT ON
BEGIN TRANSACTION
SELECT
@IsUsingLocalTransaction = 1
END
--------------------------
-- INSERT/UPDATE/DELETE --
--------------------------
<DML statements>
------------------------
-- Commit transaction --
------------------------
IF @IsUsingLocalTransaction = 1
BEGIN
COMMIT TRANSACTION
END
Dynamic field info - NewEdit
Example of how dynamic field info can be used to change the properties of fields in a NewEdit.
ALTER PROCEDURE Example.NewEdit_DynamicFieldInfoGetEditFields
AS
BEGIN
-----------------------
-- Fields to NewEdit --
-----------------------
SELECT
-- In this example, this field keeps its original field info
CONVERT(varchar(1000), NULL) AS [ExampleFieldChangedByDynamicFieldInfo1],
-- And these fields will have their field changed by dynamic field info
CONVERT(varchar(1000), NULL) AS [ExampleFieldChangedByDynamicFieldInfo2],
CONVERT(varchar(1000), NULL) AS [ExampleFieldChangedByDynamicFieldInfo3],
CONVERT(varchar(1000), NULL) AS [ExampleFieldChangedByDynamicFieldInfo4]
------------------------
-- Dynamic field info --
------------------------
/*
You don't have to SELECT all dynamic field info in one result set,
the presence of the column [ADMINFieldName] in the result sets tells
Softadmin® that the result set specifies dynamic field info.
The basic structure is to specify the field to change in a column [ADMINFieldName],
the other columns are the properties to be changed. NULL values are
interpreted as keeping the static field info.
*/
SELECT
-- Field to change
'ExampleFieldChangedByDynamicFieldInfo2' AS [ADMINFieldName],
-- Properties to change
'Look how I''ve changed the label but not the description' AS [FieldLabel],
NULL AS [Description] -- NULL value, original description will be used
SELECT
-- Field to change
'ExampleFieldChangedByDynamicFieldInfo3' AS [ADMINFieldName],
-- Properties to change
'Look how I''ve changed the description, width and height' AS [Description],
400 AS [Width],
225 AS [Height]
SELECT
-- Field to change
'ExampleFieldChangedByDynamicFieldInfo4' AS [ADMINFieldName],
-- Properties to change
'Look how I''ve changed the label, type and default value' AS [FieldLabel],
'Uneditable text' AS [FieldType],
'* Try and change me if you can *' AS [DefaultValue]
END
Column layout
There are many different ways of dividing fields into columns using ADMIN_Columns. The red arrows indicate tab-order.
ALTER PROCEDURE Example.ColumnLayout_GetEditFields
@id int = NULL
AS
BEGIN
/* ONE COLUMN, ONE HEADER */
SELECT
1 AS ADMINColumns;
SELECT
NULL AS HeadingA1,
NULL AS FieldA1,
NULL AS FieldA2,
NULL AS FieldA3,
NULL AS FieldA4
WHERE
1 = 0;
/* TWO INDEPENDENT COLUMNS, ONE HEADER */
SELECT
1 AS ADMINColumns;
SELECT -- The heading must be in its own table to span both columns.
NULL AS HeadingB1
WHERE
1 = 0;
SELECT
2 AS ADMINColumns;
SELECT
NULL AS FieldB1,
NULL AS FieldB2
WHERE
1 = 0;
SELECT
NULL AS FieldB3,
NULL AS FieldB4
WHERE
1 = 0;
/* TWO DEPENDENT COLUMNS, ONE HEADER */
SELECT
1 AS ADMINColumns;
SELECT -- The heading must be in its own table to span both columns.
NULL AS HeadingC1
WHERE
1 = 0;
SELECT
2 AS ADMINColumns,
'ROW' AS ADMINLayout;
SELECT
NULL AS FieldC1,
NULL AS FieldC2,
NULL AS FieldC3,
NULL AS FieldC4
WHERE
1 = 0;
/* TWO COLUMNS, TWO HEADERS */
SELECT
2 AS ADMINColumns;
SELECT
NULL AS HeadingD1,
NULL AS FieldD1,
NULL AS FieldD2
WHERE
1 = 0;
SELECT
NULL AS HeadingD2,
NULL AS FieldD3,
NULL AS FieldD4
WHERE
1 = 0;
/* Dynamic field info */
SELECT
'HeadingA1' AS ADMINFieldName,
'One column, one header' AS FieldLabel,
'Heading' AS FieldType;
SELECT
'HeadingB1' AS ADMINFieldName,
'Two independent columns, one header' AS FieldLabel,
'Heading' AS FieldType;
SELECT
'HeadingC1' AS ADMINFieldName,
'Two dependent columns, one header' AS FieldLabel,
'Heading' AS FieldType;
SELECT
'HeadingD1' AS ADMINFieldName,
'Two columns, left header' AS FieldLabel,
'Heading' AS FieldType;
SELECT
'HeadingD2' AS ADMINFieldName,
'Two columns, right header' AS FieldLabel,
'Heading' AS FieldType;
SELECT
CONCAT('Field', L.Letter, N.Num) AS ADMINFieldName,
CONCAT('Field ', L.Letter, N.Num) AS FieldLabel
FROM (VALUES (1), (2), (3), (4)) AS N(Num)
CROSS JOIN (VALUES ('A'), ('B'), ('C'), ('D')) AS L (Letter);
END;
Using progress output
This code demonstrates how to use the process functions to maintain a progress bar during processing.
CREATE TABLE #ToPostProcess
(
ThingyId int not null
);
/* Choose things to post-process here */
INSERT #ToPostProcess (ThingyId)
SELECT n
FROM SoftadminUtil.Number_Range(1,5);
EXEC SoftadminApi.Progress_SetTitle
@TitleText = 'Post processing thingies';
DECLARE
@CompletedSteps int = 0,
@TotalSteps int = (SELECT COUNT(*) FROM #ToPostProcess);
DECLARE ThingyCursor CURSOR LOCAL FOR
SELECT
ThingyId
FROM
#ToPostProcess;
OPEN ThingyCursor;
WHILE 1=1
BEGIN
EXEC SoftadminApi.Progress_SetStep
@CompletedSteps = @CompletedSteps,
@TotalSteps = @TotalSteps;
DECLARE @ThingyId int;
FETCH ThingyCursor INTO @ThingyId;
IF @@FETCH_STATUS <> 0
BREAK;
/* Post-process Thingy with id @ThingyId here */
-- EXEC Example.Thingy_PostProcess @ThingyId = @ThingyId;
SET @CompletedSteps += 1;
END
CLOSE ThingyCursor;
DEALLOCATE ThingyCursor;
DROP TABLE #ToPostProcess;
Best practice
Name of stored procedure
The edit fields stored procedure should be named "<Schema>.<Table>_GetEditFields". The insert/update procedureshould be named "<Schema>.<Table>_InsertUpdate" (or just "Insert" or "Update" if the procedure doesn't handle both actions).