Falcon Space. Working with forms

Description of the Form component

An example of forms can be viewed on the component demostend.
Forms are used to create entities (itemID=0), as well as to edit parameters of an entity (itemID>0).
The form can contain either standard or custom markup.

Example of a form without parameters - interactive statistics widget  on the demo stand. 

Howto by form can be viewed here - HOWTO by Falcon Space forms.

A snippet is used to output the form on the page

<div class="as-form" data-code="{code}" data-itemid="falcon-space--rabota-s-formami">div>


To create a form you must do the following:

• Create a form in the Forms section

• Configure form parameters

• Customize form fields

• Create a stored procedure fm_{code}_getItem(for the edit form. It gets data to load the current state of the form. You don't need to do this for the add form). 

• Create a stored procedure fm_{code}_checkItem. It is called to check the form fields before saving them. If it is not present, the check is not performed. 

• Create a stored procedure fm_{code}_saveItem. It saves the form values in the database when you click the Save button.

Configure form settings

The settings also include 3 parameters for connecting external sources (comma-separated API request codes for executing outgoing requests for various form events):

• GetItem API-runs before the GetItem procedure (loading the form).
• SaveItem API-runs before the SaveItem procedure (click Save).
• CheckField API-runs before the CheckField procedure (changed the field).

The result of the API request response is passed to the stored procedure via the @parameters ExtendedDictionaryKey parameter (the request code is written in the Key). 

Documentation for API requests

If you need a button to clear form fields on the form, use any button with the class as-form-reset

<a href="#" class="as-form-reset">Reset form</a>

Set up form columns

Note

• In the form settings for sqlCheckItem and sqlSaveItem procedures, there must be exactly as many parameters as there are in the form and they have a prefix in the form "field".
• You can pass the value to the data-itemID parameter - it will be replaced with the URL value of the param1 parameter. This is necessary for the editing form. To add the data-itemID form, set it to 0.
• the width of the form field can be set in any CSS units-px,%, etc.
• Names of stored procedures - fm_{code}_functionName
• Example of custom form markup:

Configure stored procedures for a form

Main stored procedures GetItem, CheckItem and SaveItem are done via the control panel. It is extremely important to follow the General style and type of template procedures (they have the fm_example_prefix).

Stored procedure for retrieving GetItem form data

CREATE PROCEDURE [dbo].[fm_tatest_getItem]
@itemID int, --Standard parameters, they always come in this procedure.
   @username nvarchar(256)
AS
BEGIN
	-- initializing the form with data. The names of the 1 SELECT output must match the form elements
    if(@itemID>0) begin        --Before you start, you can check the rights of this username
        -- 1 SELECT values of form elements
        select *
        from as_trace t1 where id = @itemID

        -- 2 SELECT additional form settings
       /* select 'Editing "'+header+'"' Title,
        '' Subtitle,
        'Save' ButtonText,
        'success' Background 	*/

        -- 3 SELECT some table data in a free format for output in the form via JS Render
    end else begin
        select 1
    end
END

The first query returns an entity, and the second returns additional form parameters (you can change the title or subtitle).

Note: The optional @parameters DictionaryParameter parameter can be passed to the procedure in which system parameters are passed:

• langID - the user's current language
• falconGuid-the user's guid stored in cookies (works for all users, including unauthorized users). 

3 selectorsto output the form:

1. SELECT 1-form data (columns).

This request also specifies metadata for columns:

• The field type can be redefined via type_{colCode}
• Possible additional CSS classes for elements are set via class_{colCode}.
• You can specify that the field can be edited singly using the prefix edt_{colCode}.
• You can specify additional suggestions for the field (clicking on them will change the value of the field)  example_{colCode}. You can specify multiple values using "| | " as the value, for example, value1||value2||value3

2. SELECT 2-form Settings.

• Title-form title
• Subtitle-markup under the form header
• EnablePrint - if 1, the send to print button appears (only the form is printed, not the entire page).
• Background (form background code, e.g. success) - sets the form background.
• ButtonText-text for the action button (Save).
• EditableSuccessMessage-sets the message text for a successful change to a single field.
• ChangeTriggerFieldOnLoad - if a form field is specified, a field change event will be called during loading (for example, to load some data via ChangeitemField). 

        

3. SELECT 3-additional table data (custom columns) for output via jsRender markup
   
   

Stored procedure for checking the CheckItem element

CREATE PROCEDURE [dbo].[fm_test_checkItem]
   @username nvarchar(256),
   @itemID int,
   @parameters ExtendedDictionaryParameter READONLY

AS
BEGIN
-- procedure for checking the correctness of data before saving
declare @ptitle nvarchar(max)
select @ptitle = value from @parameters where [key] = 'title'

declare @id int
select @id = id from as_trace where header=@ptitle and id<> @itemID

if(@id>0)
begin
	select 0 Result, 'The system already has an element with the selected Title (ID='+cast(@id as nvarchar)+')' Msg
end else
begin
	select 1 Result, '' Msg
end
END

The procedure returns the model ResultModel: Result, Msg

If Result=1, the check was successful.

Note: 

Previously, we used the method of passing form columns as parameters of a stored procedure (this method was left for compatibility). Currently, the @parameters collection is used for transmitting columns;(langID and falconGuid are also passed as part of this collection).

If you don't want to use CheckItem, leave only select 1 Result, " Msg

Stored procedure for saving the SaveItem element

CREATE PROCEDURE [dbo].[fm_metric_saveItem]
  @username nvarchar(256),
  @itemID int,
  @parameters ExtendedDictionaryParameter READONLY
AS
BEGIN
   declare @pcode nvarchar(max), @ptitle nvarchar(max)
   select @pcode = Value from @parameters where [key]='code'
   select @ptitle = Value from @parameters where [key]='title'


    update as_mt_metrics
    set code = @pcode,
        title = @ptitle,
    where id = @itemID

    -- SELECT 1
    select 1 Result, '' Msg

    -- SELECT 2 External actions
  --  select 'notification' type, 'text1' text , 'demo1' [to], 'ticketExecutor' typeCode, 'http///' url, 'add111' additional
    select 'email' type,  'ru@rudensoft.ru' [to], 'sub1' subject, 'body1' body
END

Note: in @parameters, use Key, Value2

The first query (SELECT 1) returns the model:

• Msg - sets the text of the operation result message,
• Result  - if 1 then the operation was successfully completed,
• SuccessUrl  - if a non-empty string, then after the operation is performed, the transition to this address is performed,
• HideFormAfterSubmit - if 1, the form is hidden after saving (and the modal window closes),
• RefreshContainer - selector of the container to update (for example, you can put a global container on the page.pHtml’). In the end, after the app is going to update the other components within the specified container.

The second request (SELECT 2) is a call to an external action. See calling external actions

Note: 

Previously, we used the method of passing form columns as parameters of a stored procedure (this method was left for compatibility). Currently, the @parameters collection is used for transmitting columns (langID and falconGuid are also passed within this collection)

Stored procedure for saving a single SaveField field

CREATE PROCEDURE [dbo].[fm_metric_saveEditableField]
  @pk nvarchar(128),	    -- id for item
  @fieldCode nvarchar(64),    -- form field
  @value nvarchar(max),	  -- field value
  @username nvarchar(256)  -- current user
AS
BEGIN

if(@fieldCode='XXXXXXXXXXXXXXXXXXXXX') begin
    update as_categories set typeCode = @value where id = @pk
    select 1 Result, '' Msg
    return
end
-- ...
--SELECT 1 Result,Msg
select 0 Result, 'Entity ID not found' Msg

-- SELECT 2 External actions (notification, email и т.д.)

END

Returns SELECT 1 (Result, Msg) and SELECT 2 (External actions)

You can also pass the @parameters parameter of the ExtendedDictionaryParamerer type to the procedure for passing special parameters (langID and falconGuid).

Stored procedure for filling in list fields

The procedure name is set automatically as fm_{formCode}_{colCode}_dict and the procedure is edited via the column Management dashboard.

CREATE PROCEDURE [dbo].[fm_notificationType_categoryName_dict]
  @username nvarchar(256)
  @itemID int
AS
BEGIN
    select 'Не выбрано' Text, 0 Value, 0 Selected   -- 'Group1' optGroup для категорий в списке. (и по нему же должна быть сортировка)
    union
    select name Text, id Value, Selected from as_nt_notificationCategories
    order by Text

END

Itemid is passed if the universal procedure is used. The output model is Value, Text, Selected, OptGroup, Color.

Note.

1. the optional @parameters DictionaryParameter parameter can be passed to the procedure and the system parameters (langID, falconGuid)
2. Previously, the field was used for storing the procedure name. It remained working for compatibility. This field is not output now, and you need to use new editing procedures via the dashboard instead.
3. If you need an element Not selected, you can do  union select 0 Value,‘Text
4. OptGroup is used for organizing a list with categories (for this, the first optGroup must be non-empty and the list must be ordered by optGroup).
5. If Color is set, the list and its elements will have the specified colors. 

 

Stored procedure for checking single fields when filling out a form

If there is a similar procedure named fm_{entity}_checkItemField, it will be called whenever one of the form fields is edited.

CREATE PROCEDURE [dbo].[fm_metric_checkItemField]
   @username nvarchar(256),
   @itemID int,
   @field nvarchar(256),
   @value nvarchar(max)

AS
BEGIN
    if(@field = 'roles') begin
        if(charindex(' ', @value)>0)
        begin
            select 'There should be no spaces in the roles!' Msg, 0 Result,
'.projectStageCont' RefreshContainer, '.p1' ShowContainer, '.p2' HideContainer,
'' ReplaceContainer, '' ReplaceContainerHtml
	end
    end
    select '' Msg, 1 Result
END

The input contains the entity ID, field code, value, and current user.

You can also pass the@parameters parameter of the ExtendedDictionaryParamerer type to the procedure for passing special parameters (langID and falconGuid).

At the output:

• Msg message
• Result-1 or 0 (if 0 means the field is invalid)
• RefreshContainer - jquery selector for updating part of the page (which area of the page with components to update)
• ShowContainer - which container to show, jquery selector
• HideContainer - which container to hide, jquery selector
• ReplaceContainer and ReplaceContainerHtml - if you have a task to replace HTML in some block, specify the selector in ReplaceContainer and the markup in ReplaceContainerHtml.

Stored procedure for displaying the status of filling out the Progress form

CREATE PROCEDURE [dbo].[fm_knowledgeBaseArticle_progress]
   @username nvarchar(256),
   @itemID int,
   @parameters ExtendedDictionaryParameter Readonly
AS
BEGIN
    -- procedure for visualizing form progress
    declare @fieldchannel nvarchar(max) = '',
    select @fieldchannel = value from @parameters where [key]='channel'

    -- SELECT 1
    select 1 Result, '' Msg

    -- SELECT 2 набор индикаторов прогресса
    select 'The first parameter' Title, 40 Value, 'Хорошо' [Text]
    union
    select 'The second parameter' Title, 20 Value, 'Не очень' [Text]

END

Example: [fm_example_progress]

All form elements are input (passed from an unsaved form in the @parameters parameter, where langID and falconGuid are passed). 

output: 

SELECT 1 - Result, Msg

SELECT 2 - Text, Value (from 0 to 100), Title

The procedure stage is called if the progresbar type is set in GetItem Select 1: 'circle|line' ProgressType

Called every time the form elements are changed and output where the markup {form-progress}

Note: 

The pie chart only works with multiples of 10 (i.e. rounds to tens). If you need to use exact values (for example, display a 3.5% discount, then use line mode to display progress). 

Types of form fields

Example of form fields on the demo stand

You can use the following types of fields

1. String, string-1-line text field
2. Integer, int-integer
3. Fractional number, float-floating point number
4. date selection, date-date selection via the Datepicker plugin (the format is set in GetLayoutInfo in the dateFormat parameter).
5. HTML, html-select Rich tinymce editor
6. HTML Lite, html-lite-selecting the Rich tinyMCE editor in simplified form
7. Checkbox, bool-checkbox
8. Switch-a checkbox in the form of a switch (Yes, No). In placeholder, you can set text instead of Yes/No.
9. List, select-combos for single selection
10. Chosen list, chosen-select from the searchable list
11. Multiple list chosen, chosenMiltiple-multiple selection of items from the list (they are separated by commas in the list).
12. Multiline text, text-output textarea
13. List-search, select-search - search via autocomplete
14. Value slider - selects a number or range of numbers as a slider. 
15. Radio selection, radio-single selection via radio buttons (in the style of linked Bootstrap buttons)
16. Standard radio selection, defaultRadio-standard selection from radio fields.
17. Images Radio, imageRadio-selection via radio buttons with the image
18. Images Checkboxes, imageCheckboxes-select flags with images.
19. Checkboxes checkboxes - multiple selection through checkboxes
20. Editor (HTML), editorHTML editor with HTML syntax highlighting
21. Editor (SQL), editorSQL - SQL editor with syntax highlighting
22. Editor (CSS), editorCSS - CSS editor with syntax highlighting
23. Editor (JS), editorJS - JS editor with syntax highlighting
24. HTML5 Color, html-color-color editing
25. HTML5 Email, html-email-editing email
26. HTML5 Month, html-month - select the month. The saving format is YYYY-MM.
27. HTML5 Week, html-week-week selection. The save format is 2020-W01 (YYYY-WWW).
28. HTML5 Number, html-number-number selection
29. HTML5 Tel, html-tel - field for the phone (the format is set via GetLayoutInfo, the phoneFormat parameter)
30. HTML5 Url, html url-URL input field
31. HTML5 Date, html-date - fields for entering dates. Save form YYYY-MM-DD (and does not depend on the settings in GetLayoutInfo dateFormat!)
32. HTML5 Time, html-time-time input field/save Format HH:MM
33. HTML5 Datetime local, html-datetime-local-field for entering date and time without considering the time zone. Save format YYYY-MM-DDTHH:MM, IMPORTANT-datatime-local does not work in Firefox (so use the date + time fields in most cases).
34. Location selection (geo), geo-autocomplete-output of the field with geolocation search. The format for storing the value is {lat}||{lon}|/{geotext}||{JSONOptions}
35. Entering a password, password-used in registration forms. Hides input in the form of asterisks.
36. File contents, fileContent-loading a file via the resource Manager and passing its contents to the SQL procedure as a string.
37. File on an external resource, remoteFile - specifying the URL and passing the body of the file uploaded at this URL to the saveItem procedure.
38. File selection, files - you can add files to the form (including in the add form, when there is no entity to link files to yet).
39. Timer, timer-a field that allows you to start the timer by seconds. The time is eventually passed as mm:ss. 
40. localStorage, sessionStorage, cookie, urlParameter - hidden fields for passing parameters to saveItem from cookies, local browser resources, or from URLS. 
41. multiple Color. colorCheck, colorRadio-color selection (single and multiple). In value - color, in text-text (optional). 

Note: if HTML5 is entered incorrectly, it will be highlighted in pink and the form will not be saved until the errors are corrected.

Form with editing by individual fields (instant saving of fields, editable fields).

You can create a form where each field is saved separately.

To do this, do the following:

1. In GetItem, set which fields will be editable. to do this, add the output columns of the form 1 edt_{colName} to SELECT 1 (these columns will respond to changes and cause saving of these fields).
2. Implement the SaveField procedure (saving individual form fields).
3. Save button or hide It via CSS, or use custom form markup and do not insert the button in the markup. 

Note:

1. this save mode is suitable for input fields, checkboxes, radio switches, textarea, and selection from a list. This mode does not work for a set of checkboxes or for complex fields of the Code Editor type.

2. If you need to set the message output after successfully saving the field, use the EditableSuccessMessage (string) parameter in the GetItem form procedure in SELECT 2.

Form without parameters

This form can be used to perform any actions.

I.e. output information using Getitem and custom markup + perform the action.

Important! The CheckItem and SaveItem procedures must not have fieldname parameters.

Solve problems

I can't save the script correctly in the form

When using

<script></script>

when custom form markup occurs, there is a problem with nested script tags. Therefore, do not use custom markup for the form if you plan to use this form to edit any scripts (script tags, for example, counters). 

Error during initial loading of the form

fm_{code}_getItem-some result must always be returned. If your form is for adding, you can just return select 1.

Captions for form elements are displayed crookedly

Use the bootstrap markup for the form skeleton (row, col-md-X, and so on). for labels, use the label tag with the as-form-cap class.

Custom form markup will look something like this:

<div class="row">
<div class= "col-lg-1 col-md-1 col-sm-1 col-xs-12"><label class'as-form-cap=" ">Name</label></div>
<div class="col-lg-4 col-md-4 col-sm-4 col-xs-12">{colcontrol-title}</div>
<div class= "col-lg-1 col-md-1 col-sm-1 col-xs-12"><label class'as-form-cap=" "> Code</label></div>
<div class="col-lg-4 col-md-4 col-sm-4 col-xs-12">{colcontrol-code}</div>
<div class= "col-lg-1 col-md-1 col-sm-1 col-xs-12"><label class'as-form-cap=" ">order</label></div>
<div class="col-lg-4 col-md-4 col-sm-4 col-xs-12">{colcontrol-ord}</div>
</div>

For a complete list of questions about how to implement a feature on a form, see HOWTO Forms.