|
|
| Line 1: |
Line 1: |
| − | {{ScoutPage|cat=Tutorial}}
| + | #REDIRECT [[Scout/Tutorial/Minicrm/Add a search form]] |
| − | {{note|Scout Tutorial|This page belongs to the {{ScoutLink|Tutorial|minicrm|Minicrm Tutorial}}. }}
| + | |
| − | | + | |
| − | Once we have '''created a table page''' and '''implemented the service''' to get the table data, we can take advantage of a feature the Scout SDK offers: it can '''create a search form''' based on the existing information.
| + | |
| − | | + | |
| − | The alternative, of course, is to create the search form manually.
| + | |
| − | | + | |
| − | Once you have all that, it's time to {{ScoutLink|Tutorial|minicrm/Add_A_Form_To_Edit_The_Data|Add a form to edit the data}}.
| + | |
| − | | + | |
| − | == What are we talking about? ==
| + | |
| − | | + | |
| − | We need to create a '''search form''' that will be shown together with our newly created '''table page'''. The values provided by the user (i.e. the chosen search criteria) are packed into a '''FormData''' object, which is passed along to the '''outline service'''. There, we need to build an appropriate <tt>WHERE</tt> clause.
| + | |
| − | | + | |
| − | [[Image:Scout Search Form Details.png|900px]]
| + | |
| − | | + | |
| − | == Create a Search Form ==
| + | |
| − | | + | |
| − | Go to the ''CompanyTablePage'', right-click and choose '''Create Search Form'''. The created search form contains a field for each column defined on the base table page.
| + | |
| − | | + | |
| − | [[Image:Newsearchform.jpg]]
| + | |
| − | | + | |
| − | Use ''Company'' as the name and click ''Next''.
| + | |
| − | | + | |
| − | [[Image:Newsearchformwizard.jpg]]
| + | |
| − | | + | |
| − | {{note|Form Data|When creating a ''form'', Scout SDK will automatically create a ''form data'' class in the background. The ''form data'' class will be created in the '''shared''' plugin. This is the data transfer object used for communication between client and server. Every form provides the context menu '''Update Form Data''' to re-generate the ''form data'' class based on the form.}}
| + | |
| − | | + | |
| − | Done! What did Scout SDK do?
| + | |
| − | | + | |
| − | # it created a '''CompanySearchForm''' in the client plugin | + | |
| − | # it created a '''CompanySearchFormData''' in the shared plugin
| + | |
| − | # it set the '''Search Form property''' of the ''CompanyTablePage'' to ''CompanySearchForm''
| + | |
| − | | + | |
| − | {{note|How does it work?|The Scout runtime will create the ''search form'' when showing the ''company table page''. Using the search form will generate a ''SearchFilter'' object that is passed on to the <tt>execLoadTableData</tt> method of the ''table page''. The search filter contains the ''form data'' of the ''SearchForm''.}}
| + | |
| − | | + | |
| − | == Adding Fields ==
| + | |
| − | | + | |
| − | Add a field to the ''search form'': right-click on the ''CompanySearchForm'' and pick '''New Form Field...''' from the menu.
| + | |
| − | | + | |
| − | [[Image:Scout New Form Field.png]] | + | |
| − | | + | |
| − | Pick '''String Field''' from the list and click ''Next''. Set the name to ''Name'' and click ''Finish''.
| + | |
| − | | + | |
| − | [[Image:Scout New String Form Field.png]]
| + | |
| − | | + | |
| − | {{warning|Do not forget to update the ''form data''!|You need to use the '''Update Form Data''' context menu on the ''CompanySearchForm''. If you don't, the ''form data'' will know nothing of the name field you just added.}}
| + | |
| − | | + | |
| − | This is already enough to show a functional ''search form'':
| + | |
| − | | + | |
| − | [[Image:Scout Minicrm With Search Form.png|600px]]
| + | |
| − | | + | |
| − | '''Before we continue''', add a ''Short Name'' field to the ''company search form''!
| + | |
| − | | + | |
| − | Don't forget to '''update the form data''' after adding a new field! :)
| + | |
| − | | + | |
| − | There is one missing piece, obviously. The service that gets the actual data needs to build some sort of constraint (a WHERE clause to the SQL statement) to filter the returned rows.
| + | |
| − | | + | |
| − | == Adapt the outline service operation getCompanyTableData ==
| + | |
| − | | + | |
| − | In order to constrain the SQL statement for the company outline, we have to adapt the service operation ''getCompanyTableData'' and add a parameter ''searchFilter'' of the type ''CompanySearchFormData'' to the method. Do that for both the service interface ''IStandardOutlineService'' and the service implementation ''StandardOutlineService''. There are two easy ways to find them: Ctrl+Shift+T, or find the ''StandardOutlineService'' on the server side in the ''Scout Perspective'' and click on the two links.
| + | |
| − | | + | |
| − | Interface:
| + | |
| − | | + | |
| − | <source lang="java">
| + | |
| − | public interface IStandardOutlineService extends IService {
| + | |
| − | public Object[][] getCompanyTableData (CompanySearchFormData formData) throws ProcessingException;
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Implementation:
| + | |
| − | | + | |
| − | <source lang="java">
| + | |
| − | public Object[][] getCompanyTableData(CompanySearchFormData formData) throws ProcessingException {
| + | |
| − | StringBuilder statement = new StringBuilder();
| + | |
| − | statement.append(
| + | |
| − | "SELECT COMPANY_NR, SHORT_NAME, NAME " +
| + | |
| − | "FROM COMPANY " +
| + | |
| − | "WHERE 1=1 ");
| + | |
| − | if (!StringUtility.isNullOrEmpty(formData.getShortName().getValue())) {
| + | |
| − | statement.append("AND UPPER(SHORT_NAME) LIKE UPPER(:shortName || '%')");
| + | |
| − | }
| + | |
| − | if (!StringUtility.isNullOrEmpty(formData.getName().getValue())) {
| + | |
| − | statement.append("AND UPPER(NAME) LIKE UPPER(:name || '%')");
| + | |
| − | }
| + | |
| − | return SQL.select(statement.toString(), formData);
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''Prefixing of names with a colon''' automatically makes these instances '''bind variables'''. The Scout runtime will bind these ''bind variables'' to the corresponding fields from the ''form data'' object.
| + | |
| − | | + | |
| − | {{warning|Naming Convention|We're relying on a naming convention, here! If your form has a field called '''ShortName''', then the bind variable will be called ''':shortName'''. Note the capitalization.}}
| + | |
| − | | + | |
| − | Now we need to forward the ''CompanySearchFormData'' to the server. Return to the method '''execLoadTableData''' in the '''CompanyTablePage''' and add a new parameter to the service call according to its interface definition. The required ''CompanySearchFormData'' is available from the ''filter'' parameter:
| + | |
| − | | + | |
| − | <source lang="java">
| + | |
| − | @Override
| + | |
| − | protected Object[][] execLoadTableData(SearchFilter filter) throws ProcessingException {
| + | |
| − | return SERVICES.getService(IStandardOutlineService.class).getCompanyTableData((CompanySearchFormData) filter.getFormData());
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | If the search is inactivated with <code>setSearchActive(false);</code>, the method call <code>filter.getFormData()</code> returns <tt>null</tt>. Therefore, it can be interesting to do this check on client side and to send an empty formData (corresponding to a search request without any constraints).
| + | |
| − | <source lang="java">
| + | |
| − | @Override
| + | |
| − | protected Object[][] execLoadTableData(SearchFilter filter) throws ProcessingException {
| + | |
| − | CompanySearchFormData formData = (CompanySearchFormData) filter.getFormData();
| + | |
| − | if(formData == null) {
| + | |
| − | formData = new CompanySearchFormData();
| + | |
| − | }
| + | |
| − | return SERVICES.getService(IStandardOutlineService.class).getCompanyTableData(formData);
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''Enjoy!'''
| + | |
| − | | + | |
| − | [[Image:Scout Minicrm With Two Search Fields.png|600px]]
| + | |
