5.4.7. Input by string

<< Prev   Next >>

5.4.7.1. General information

For applied objects (catalogs, documents, charts of characteristic types, charts of accounts, charts of calculation types, registers, business processes and tasks, as well as exchange plans), it is possible to specify the attributes which are used for searching in the Input by string property. If the input by string is permitted (the corresponding attributes are set), then it is permissible not to perform a selection from the object form in the corresponding type input field, but to enter the data that is contained in the set object attributes.

For example, we have the Products catalog, which contains several products starting with the word Bosch. Then, by entering the word bosc in the product input field, we get a list of products that begin with this word (see fig. 137).

The string that is entered in the input field to be further used for searching must meet the following requirements:

1. The total string length must not exceed 1,000 characters.
2. This string must not contain more than 32 words (with spaces, non-breaking spaces, and tabs as separators).

If the entered string does not meet one of these requirements, the search will not be performed, and you will see an error message.

The following may be used as the attributes using which the search is be performed:

• For catalogs, charts of calculation types, charts of accounts, charts of characteristic types, exchange plans: Code and Description.
• For documents: Number.
• For business processes and tasks: Number and Description.
• Attributes of Number or String type, for which Index property is set to Index or Index with additional ordering. An example of the latter is the field for entering the SKU, barcode, TIN.

To generate a list of attributes, click the select button and in the opened dialog box move those fields, for which the input by string is supported, to the left list.

If there are several fields, then set their sequence. When searching by string, the search is performed in the fields in sequence in which they are presented in this dialog box. For example, for the Products catalog element, input can be carried out both by code and by SKU. If the value of the one element code matches with the value of the SKU of another element, then the found values will appear in the list of values in the order in which they were specified during configuration.

In addition to specifying which fields will be searched, 1C:Enterprise allows you to further customize some search parameters. The String search method property is used to specify the string search method:

• Only in the beginning of the field selected for input by string (Beginning value). In this case, the search string is not broken into words, and the entered text is searched entirely. For example, the search is performed in the following data: John Miller and Johnson. If you enter John in the input field, Johnson will be found as a result. However, if you enter John Mil in the input field, nothing will be found.
• In any part of the field (Any part value). If the search string consists of several words and the search is performed in any part, then the search uses a query similar to the following (for two fields and two words):

(Field1 DETAILED "%Слово1%" Or Field2 DETAILED "%Слово1%") AND (FIeld1 DETAILED "%Слово2%" Or Field2 DETAILED "%Слово2%")

The Full-text search property allows you to use full-text search when arranging the input by string. Full-text search cannot be used for external data source tables. The use of full-text search has several features:

1. Full-text search is always performed by the beginning of words.
2. Full-text search is used for the initial filtering of objects in which further search will be performed (the number of objects in which the search will be performed is reduced).
3. All the non-indexed references from the table, which was used for the input by string, will be added to the results of the full-text search.
4. In the list of selected objects, the search will be performed by the fields that are selected for use in the input by string functionality in the manner specified by the String search method property.
5. For each word from the search query, the "*" character is added at the end.

These features can cause the following consequences:

• The data will be found if the line search method is set in the value Any part and requires to search the fragments located at the beginning of words.
• The data will not be found if the line search method is set in the value Any part and requires to search the fragments located not at the beginning of words. It is recommended disabling the full-text search if the line fragments located not at the beginning of works are needed to be found. The line search method may be left unchanged.
• If the full-text search fails, the usual search will be applied, in accordance with the String search method property. This can lead to a situation where the object found turns into a not-found one (for the search by any part of a word). For example, the "a" character is entered in the input field. This character is located not only in the beginning, but also in the middle of the word array where the search is performed. For a large data set, the full-text search will terminate with an error (the search result is too large) and using the normal search, data will be found that contain the letter “a” inside. Then the user enters another letter (for example, "ц") and the search string will become "ац". In this case, full-text search will only filter data that starts with “ац” and will ignore data that contains “ац” within.

If the drop-down list is generated by 1C:Enterprise (and not using the application program code), then the presentations of the found objects are generated using a special algorithm. The presentation of the found object consists of two parts: presentation of the attribute that contains the search string (required) and additional presentation (optional).

The presentation itself is generated as follows:

• The field containing the search string is determined:
  • In the case of using full-text search or in the normal search for several words, this field will be the first field from the fields specified in the Input by string property in which the first word from the search string is found.
  • When using the normal single word search, this field will be the attribute in which the search was performed.
• The presentation of a value located in a specific field will be a mandatory part of the presentation of the found object for the drop-down list.
• It is determined whether it is necessary to generate an additional presentation. For this, the components of the fields is determined, which will be used to generate an additional presentation:
  • If the object found has only one field used to generate the presentation, and the search string is found in this attribute, the fields of the alternative presentation are used.
  • Otherwise, the default presentation fields are used. The list of the default and alternative presentation fields is given below.
• If the list of fields to generate an additional presentation is empty, the additional presentation is not generated. Otherwise, the additional presentation is generated as follows:
  • Text presentation of all the fields that are selected to generate an additional presentation is enclosed in parentheses and separated by ",".
  • The generated additional presentation is added to the right, separated by a space, to the mandatory part of the presentation of the object found.
• The following fields are used to generate the default and alternative presentations:
  • Catalog, business process, chart of characteristic types, chart of accounts, chart of calculation types:
    • Default presentation: Description and Code.
    • Alternative presentation: depending on the selected default presentation, the remaining field is used for the alternative presentation.
  • Document:
    • Default presentation: Number and Date.
    • Alternative presentation: none.
  • Task:
    • Default presentation: Description, Number, and Date.
    • Alternative presentation: none.
  • External data source:
    • Default presentation: field specified in the Presentation field property of the external data source table.
    • Alternative presentation: none.

The Selection data retrieval mode property controls how the platform searches for data when input by string. If the property is set to Background, then a background job is used to retrieve data, and an animated image is displayed in the drop-down list, similar to the background report execution. The background job is used if the required data has not been received for display to the user within 200 ms. For the infobase file mode, it is possible to retrieve data in the background if another background or scheduled job is not performed at the time of receiving the data. During the background retrieval of selection results, the user can continue to edit the input field. By specifying the Directly value as a property value, the search is performed without using background jobs.

When configuring input by string it is recommended to observe the following recommendations:

• The Background value for the Selection data retrieval mode property is recommended to be set for objects where a large amount of data is planned.
• Enabling full-text search is recommended for the objects in which a large amount of data is expected.
• It is recommended to enable the string search in any place alongside with a background search, or in tables, where a large amount of data is not expected. It is desirable, also with a large amount of data, if the search in any place is enabled, to enable the full-text search (so that most of the searches would be performed through full-text search).

5.4.7.2. Input field behavior features

When entering data in the input field, consider some features of operating the selection list. If input results in finding several objects, beginning with the entered text, the list of these objects will be located in the drop-down list. During input, the user can use the Up arrow and Down arrow buttons to move through the list, while continuing to type in the field itself. In this case, to make a selection, it is necessary to select the required element and confirm the selection by pressing the Enter or Tab button. To generate a selection list for the input field, the following algorithm is used:

1. Data is retrieved when performing a search in the first field (from the list of selected fields) by the beginning of a string and by substring. The quantity of records retrieved as a result of the search by the beginning of the string will be called RS, and the quantity of records retrieved as a result of the search by substring will be called RP.
2. If RS+RP<=10, the drop-down list will contain all the results of each search.
3. If the RP and RS exceed 5 (each), the selection list will contain 5 records from each list.
4. If any of RP or RS values is less than 5, then all the entries from the smaller list and as many records from the larger list as required to complete the drop-down list to 10 will be added to the drop-down list.
5. If the total quantity of records in the drop-down list turned out to be less than 10, then the algorithm is repeated from step 1 for the next field from the list of selected fields, using the difference between 10 and the quantity of results retrieved as the number of data necessary for retrieval during the next step.

5.4.7.3. Selection list programmatic generation

If the developer is not satisfied with how the selection list is generated, they can override it themselves. This can be done in two ways:

• Directly in the form. In this case, the special generation of the selection list can only be used for this single field. To do this it is required to define StartChoice, AutoComplete and TextEditEnd event handlers.
• In the corresponding object manager module . In this case, special selection list generation will be performed for all the input fields in which the values of the used object are entered.

If the field is associated with data that has a type of reference to an applied object (for example, CatalogRef, EnumRef, and so on), the selection list can be generated either in the corresponding object manager module or using form module handlers. In other cases, the selection list can only be generated using the form module handlers.

Let's take a closer look at how the selection list is generated in the object manager.

To programmatically generate a selection list, it is necessary to redefine the ChoiceDataGetProcessing event handler of the object module. The handler receives a set of parameters that determine the conditions for selection list generation (via the Parameters handler parameter). A parameter set is a structure that contains:

• Search string, a text string containing the text that the user entered in the input field (SearchString property).

  When performing standard data processing, the following assumptions regarding the search string are used:

  • If this parameter is not specified or its value is Undefined, it is considered that the search string is not specified and it is necessary to return the entire available list of values.
  • a value of any type other than the String type, which is specified as the value of the SearchString property, will be converted to a string value.
• Filter is the structure that describes the filtering as it is described by the Filter form parameter of the form extension for a dynamic list. This property is always present.

  The filter specified in this property will be converted (if possible) into a full-text search query, refining this query to increase the search speed.

• The property that indicates the mode of selecting groups and elements (transferred only for hierarchical lists) is the ChoiceFoldersAndItems property.
• The StringSearchMode property that defines the string search mode: by word beginning or by any part.
• The need to use full-text search (the FullTextSearch property).
• The mode of selection data retrieval (the SelectionDataRetrievalMode property).
• The LimitSearchString property that indicates whether to analyze fulfillment of the search string requirements: its total length cannot exceed 1,000 characters and 32 words. If you want to allow violation of these requirements for the search string, set the LimitSearchString property to False.
• In addition, the structure passes the elements, specified in the Selection parameter associations and Selection parameters form element properties.

The handler also has two more parameters. The formal parameter (ChoiceData) is used to return the generated selection list. The StandardProcessing parameter determines the system behaviour after closing the handler. If the developer sets the StandardProcessing parameter to False, then they need to completely generate the selection list themselves.

If the standard processing check box is selected to True, 1C:Enterprise can be allowed to generate a selection list, but you can also modify the selection parameters (add additional selection values, change the selection mode for groups and items, and so on).

So, when the user enters any text, the following code will provide three products with codes 00000002, 00000003 and 00000004 for selection.

Example:

Procedure ChoiceDataGetProcessing(ChoiceData, Parameters, StandardProcessing)

ChoiceData = New ValueList;
ChoiceData.Add(Catalogs.Goods.FindByCode("00000002"));
ChoiceData.Add(Catalogs.Goods.FindByCode("00000003"));
ChoiceData.Add(Catalogs.Goods.FindByCode("00000004"));

StandardProcessing = False;

EndProcedure

In the following example, setting an additional filter expands the filter generated by the input field so that the selection list contains only goods and not all other item kinds. In this case, 1C:Enterprise performs the selection list generation.

Example:

Procedure ChoiceDataGetProcessing(ChoiceData, Parameters, StandardProcessing)

Parameters.Filter.Insert("Type", Enumerations.ProductTypes.Product);

EndProcedure

The following example illustrates a simplified filter implementation using only 1C:Enterprise language. In this example, the filtering of products which names begin with the string entered by the user in the input field will be considered.

Example:

Procedure ChoiceDataGetProcessing(ChoiceData, Parameters, StandardProcessing)

StandardProcessing = False;
Query = New Query;
Query.Text = "SELECT ALLOWED
| Products.Reference as Product
|FROM
| Catalog.Goods AS Goods
|WHERE
| Product.Name LIKE &Name";
Query.SetParameter("Description", Parameters.SearchString + "%");

Result = Query.Execute();
ResultsTable = Results.Export();
ProductsArray = ResultsTable.UnloadColumn("Product");
ChoiceData = New ValueList;
ChoiceData.LoadValues(ProductsArray);

EndProcedure

There is also another way to generate a selection list. Instead of passing a reference to the searched object (as in the examples above), you can pass a structure of special content as an item value of the value list.

This structure consists of the following elements:

• Value. A selected value. It can be a single value or a value array. Structure element with this name is mandatory.

  If the Value structure item contains an array of values, this is useful only for input fields that support multiple choice. In addition, the selection list will display the entire group of values (located in the array) as a single value, and all other structure properties (Warning, DeletionMark, and AdditionalData) will be related to the entire list of values as well.

• DeletionMark. Indicates that the selected value is marked for deletion in the infobase. Structure element with this name is optional.
• Warning. Line with the warning text that1C:Enterprise will display when selecting such element from the list of values. Structure element with this name is optional.
• AdditionalData. This structure item can contain various data that might be required later when operating with the selection list. For example, you can process the value in the handler of the ChoiceProcessing event of the form item. The data will be passed via the AdditionalData event handler parameter.

  You can specify additional data in any of the following event handlers: StartChoice, TextEditEnd, or AutoComplete. In other words, in any handler where a selection list is generated to be displayed in the input field.

If the DeletionMark property is True and Warning property is not specified in the structure, 1C:Enterprise will automatically generate the warning text. If the Warning property is specified, then it is displayed. Remember, that the Warning text ends with the question Continue? and is displayed as a question with Yes and No options.

Next, a modification of the previous example will be shown, where for warehouses with the DontUse attribute set to True, a This warehouse must not be used warning will be generated.

It is also possible to combine both values of Structure type and simple values in a single selection list.

Example:

Procedure ChoiceDataGetProcessing(ChoiceData, Parameters, StandardProcessing)

StandardProcessing = False;
ChoiceData = New ValueList;
// Generate a list with warnings
Query = New Query;
Query.Text = "SELECT
| Warehouses.Reference,
| Warehouses.Name,
| Warehouses.DontUse
|FROM
| Catalog.Warehouses AS Warehouses
|WHERE
| Warehouses.Description LIKE &Description";
Query.SetParameter("Description", Parameters.SearchString + "%");
Result = Query.Execute();
SelectionDetailedRecords = Result.Select();

While SelectionDetailedRecords.Next() Do
Structure = New Structure("Value", SelectionDetailedRecords.Reference);
// Fill in the warning
If SelectionDetailedRecords.DontUse Then
 Structure.Insert("Warning", "This warehouse must not be used!");
EndIf;
Element = ChoiceData.Add();
Element.Value = Structure;
Element.Presentation = SelectionDetailedRecords.Name;
EndDo;

EndProcedure

The following example shows how to generate an array of values as a single value of the input field selection list:

Procedure ChoiceDataGetProcessing(ChoiceData, Parameters, StandardProcessing)

StandardProcessing = False;
ChoiceData = New ValueList;
ArrayOfValues = New Array;
// Generate a list with warnings
Query = New Query;
Query.Text = "SELECT
| Counterparties.Ref AS Ref,
| Counterparties.Description AS Description
|FROM
| Catalog.Counterparties AS Counterparties
|WHERE
| Counterparties.Description LIKE &Description";
Query.SetParameter("Description", Parameters.SearchString+"%");
Result = Query.Execute();
SelectionDetailedRecords = Result.Select();

While SelectionDetailedRecords.Next() Do
ArrayOfValues.Add(SelectionDetailRecords.Ref);
EndDo;

Structure = New Structure("Value", ArrayOfValues);
Structure.Insert("AdditionalData", "Here you can specify additional data");
Structure.Insert("DoMessageBox", "Select multiple counterparties." + Chars.LF);
Element = ChoiceData.Add();
Element.Value = Structure;
Item.Presentation = "List of counterparties";

EndProcedure

<< Prev   Next >>