|
|
| (49 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| − | {{note|Scout Tutorial|This page belongs to the {{ScoutLink|Tutorial|Minicrm Step-by-Step|Minicrm Step-by-Step Tutorial}}. It explains how create your first page in your project and fill it with data from the database. You need to {{ScoutLink|Tutorial|Setup a SQL Service|connect a database to your application}} in order to continue.}}
| + | The Scout documentation has been moved to https://eclipsescout.github.io/. |
| − | | + | |
| − | A typical Eclipse Scout application consists of multiple '''outlines'''. Think of it as a folder hierarchy. Each "folder" is called a '''page'''. These pages comes '''with nodes''' (a list of child pages) or '''with table''' (a table filled with rows of data from a data sources such as a database).
| + | |
| − | | + | |
| − | == What are we talking about? ==
| + | |
| − | | + | |
| − | When we talk about ''outlines'' and ''pages'', think of a simple application. In this tutorial we're creating a miniature CRM. Here's what it may have, using the Eclipse Scout terminology:
| + | |
| − | | + | |
| − | # one outline for companies and persons
| + | |
| − | ## the companies page shows a table with rows from the company table on the database
| + | |
| − | ## the persons page shows a table with rows from the persons table on the database
| + | |
| − | ## for every person there is a list of nodes naming all the child pages
| + | |
| − | # there may be other outlines for different tasks or topics such as campaigns
| + | |
| − | | + | |
| − | [[Image:Scout Pages and Outlines.jpg]]
| + | |
| − | | + | |
| − | If you look at the diagram above, there are some interesting things to note.
| + | |
| − | | + | |
| − | # the outline itself acts like a page with nodes -- it just shows the titles of the child pages (persons and companies)
| + | |
| − | # there can be only one child page for a page "with table" -- every row in the table has the same child
| + | |
| − | # the title of a child page underneath a table is not shown -- by default the first visible column of the table replaces whatever the name was (in the example above "Catherine" replaces whatever the name of the Person Details Page was)
| + | |
| − | | + | |
| − | In this tutorial our '''first page''' will be the '''company''' table page. The '''standard outline''' is a prerequesite for it, so we'll start there.
| + | |
| − | | + | |
| − | All of these structures are stricly client-side structures. The '''server''' couldn't care less how the various services it provides will get used. The only thing we need on the server side is '''a service that returns company data'''.
| + | |
| − | | + | |
| − | == Add an Outline first ==
| + | |
| − | | + | |
| − | Since a page can only be contained within an Outline, you need to define the ''Outline'' first. Open the client node in Eclipse Scout and expand the tree until you get to the ''Desktop'' node. Do a right click on that node and choose ''New Outline...''.
| + | |
| − | | + | |
| − | [[Image:Newoutline.jpg|Newoutline.jpg]]
| + | |
| − | | + | |
| − | Choose ''Standard'' as the name and make sure the checkbox ''Add to Desktop'' is ticked. Then click ''Finish''.
| + | |
| − | | + | |
| − | [[Image:Newoutlinewizard.jpg|Newoutlinewizard.jpg]]
| + | |
| − | | + | |
| − | {{note|Multilingual Texts|If you type ''Standard'' into the name field, you'll see all sorts of texts in the language of your locale. If you're not sure whether the string you picked is the right one, you can right-click it and choose ''Modify Entry...'' from the context menu. This will show you the ''key'' and all the translations. If you're still not happy, just create a new multilingual text: type ''Standard'' into the name field and pick '''New translated text...''' from the list.}}
| + | |
| − | | + | |
| − | If you expand the ''Desktop'', you should see the newly created ''StandardOutline''.
| + | |
| − | | + | |
| − | [[Image:Standardoutline.jpg|Standardoutline.jpg]]
| + | |
| − | | + | |
| − | {{note|Files Created|If you switch to the '''Java Perspective''' you can look at the file created: eclipse.org.minicrm.client.ui.desktop.outlines contains the new '''StandardOutline.java'''. If you see the key "SC_Label_UseDefaults" being used in the source code, then you might have picked a multilingual text you did not intend to. Go back to the '''StandardOutline''' in the ''Scout Perspective'' and modify the entry for the name as discussed above in the note on multilingual texts.}}
| + | |
| − | | + | |
| − | == Add a page to the Outline ==
| + | |
| − | | + | |
| − | Now you can add a new page to your StandardOutline. Right click on the ''Child Pages'' node of your ''StandardOutline'' and then choose ''New Page...''.
| + | |
| − | | + | |
| − | [[Image:Newpage.jpg|Newpage.jpg]]
| + | |
| − | | + | |
| − | From the dropdown list choose '''AbstractPageWithTable''' then click next.
| + | |
| − | | + | |
| − | [[Image:Newtablepage.jpg|Newtablepage.jpg]]
| + | |
| − | | + | |
| − | Now enter the name for the new table page: ''Company''.
| + | |
| − | | + | |
| − | If there is no appropriate multilingual text pick ''New translated text...'' from the list and provide a key and a default translation.
| + | |
| − | | + | |
| − | [[Image:Newtext.jpg|Newtext.jpg]]
| + | |
| − | | + | |
| − | [[Image:Companytext.jpg|Companytext.jpg]]
| + | |
| − | | + | |
| − | {{note|Files Changed|Creating a new translated text will create an entry in '''Texts.java''' and appropriate property files: ''Texts.properties'' for the default language, ''Texts_de.properties'' for German, and so on). You can find these files in the ''Java Perpective'' under ''eclipse.org.minicrm.shared/resources/texts''.}}
| + | |
| − | | + | |
| − | Eclipse Scout also comes with an editor to '''edit all the property files for multilingual texts''' in one go. If you expand the ''shared'' node in your Eclipse Scout project, activate ''Texts'' and click on <u>open nls editor</u> link in the Scout Object properties view, you can manage all your application's texts.
| + | |
| − | | + | |
| − | [[Image:Nls.jpg|Nls.jpg]]
| + | |
| − | | + | |
| − | Back to the ''CompanyTablePage'' example: pick ''Company'' from the list (create a new translated text if you haven't done so already) and click ''Finish''.
| + | |
| − | | + | |
| − | [[Image:Companytablepage.jpg|Companytablepage.jpg]]
| + | |
| − | | + | |
| − | When you expand now the ''Child Pages'' folder below your ''StandardOutline'', you'll find the new ''CompanyTablePage''. When you expand the node ''Table'', you'll find a folder ''Menus'' and ''Columns''. Below ''Columns'' we will now '''add the columns''' that are needed to display the company data.
| + | |
| − | | + | |
| − | [[Image:Finishedcompanytablepage.jpg|Finishedcompanytablepage.jpg]]
| + | |
| − | | + | |
| − | {{note|Files|Creating the Company Table Page has created the file ''eclipse.org.minicrm.client.ui.desktop.outlines.pages/CompanyTablePage.java'' and it has added code to ''eclipse.org.minicrm.client.ui.desktop.outlines/StandardOutline.java''. The newly created method '''execCreateChildPages''' in ''StandardOutline'' shows how child pages are instantiated and added to the list.}}
| + | |
| − | | + | |
| − | == Add colums to the table ==
| + | |
| − | | + | |
| − | The next step is '''adding columns to the table'''. Add a column for the primary key (''CompanyNrColumn''), one for the company's shortname (''ShortNameColumn'') and one for the company's name (''NameColumn'').
| + | |
| − | | + | |
| − | The context menu for creating a new table column is on the ''Columns'' node right below the page's table.
| + | |
| − | | + | |
| − | [[Image:Newcolumn.jpg|Newcolumn.jpg]]
| + | |
| − | | + | |
| − | First, you have to choose a '''template''' for your column. The template used depends on the '''data type''' of your data and the '''format''' you want to use when displaying it. Eclipse Scout will attempt to cast your data types appropriately.
| + | |
| − | | + | |
| − | Choose ''Long Column'' for the first column and ''String Column'' for the remaining columns.
| + | |
| − | | + | |
| − | [[Image:Columntemplate.jpg|Columntemplate.jpg]]
| + | |
| − | | + | |
| − | ''CompanyNrColumn'' is going to be an invisible column. Thus, it requires no name. Just provide the ''Type Name''. The remaining columns get multilingual texts for their labels, just like everything else in an Eclipse Scout application.
| + | |
| − | | + | |
| − | [[Image:Newcolumnname.jpg|Newcolumnname.jpg]]
| + | |
| − | | + | |
| − | {{note|Inner Classes|A '''page with table''' is a single Java class. In this example, we're talking about the '''CompanyTablePage'''. The '''table''' itself is an '''inner class''' of the page. The '''columns''' are '''inner classes''' of the table. Take a look at the source to see how that works. The Scout SDK parses the Java code in order to create its model, and the Scout runtime does the same thing.}}
| + | |
| − | | + | |
| − | == Column Width ==
| + | |
| − | | + | |
| − | If you restart your client, you will see that the table layout is '''not optimal'''.
| + | |
| − | | + | |
| − | The '''column width''' could be improved. The table has a property called ''Auto resize columns'' and every column has a property called ''Width''. You can either specify a higher width for all of your columns or you can tell your table to auto resize all columns. When auto resizing, the available width is shared by all columns.
| + | |
| − | | + | |
| − | {|
| + | |
| − | |style="vertical-align:top"|[[Image:Tableprops.jpg]]
| + | |
| − | |[[Image:Columnprops.jpg]]
| + | |
| − | |}
| + | |
| − | | + | |
| − | {{warning|Auto Resizing|Generally speaking you should only use ''auto resize columns'' when '''prototyping'''. In a real application, most '''numbers and dates should be in fixed width columns'''. In addition to that, in some cases you will end up with a lot of columns. Twenty, thirty, and more columns are not unheard of. In this case, fixed columns width and (a lot of) horizontal scrolling is the only solution. Auto resized columns would result in an unreadable mess.}}
| + | |
| − | | + | |
| − | == Hiding Columns ==
| + | |
| − | | + | |
| − | In addition to that, users are typically '''not interested in primary keys'''. You should hide ''CompanyNrColumn'' from the user.
| + | |
| − | | + | |
| − | You can do that by unticking the '''Visible''' property on the column. Users can make invisible columns visible, however. If you want to prevent this (and in this case you do), untick the '''Displayable''' property.
| + | |
| − | | + | |
| − | [[Image:Organize.jpg]]
| + | |
| − | | + | |
| − | {{note|Visible and Displayable Colums|An invisible is only invisible initially. Users can right-click on the column headers of a table and ''organize'' their columns. This is where users can show and hide columns, and this is where they can change their order. '''Invisible columns can be made visible''' using this dialog. If you want to prevent users from making invisible columns visible, you must make them ''not displayable''.}}
| + | |
| − | | + | |
| − | Sometimes '''invisible but displayable columns''' are used if a certain table is used like a ''report'' for slightly different target users. Some users are interested in a certain subset of columns, other users are interested in a different subset. Instead of preparing a customized table for every target user you can provide one single table for all users with specialized columns being invisible but displayable. Every user then gets to show the particular extra columns they are interested in.
| + | |
| − | | + | |
| − | == Create an Outline Service ==
| + | |
| − | | + | |
| − | In order to fill the table in our ''CompanyTablePage'' we need to have a service available on the server side. This service will contact the database and retrieve the data we need on the client.
| + | |
| − | | + | |
| − | First, we need to create an ''OutlineService''. Go to the ''server'' node in your Eclipse Scout project, expand it, go to ''Outline Services'', right click and choose ''New Outline Service...''.
| + | |
| − | | + | |
| − | [[Image:Newoutlineservice.jpg]]
| + | |
| − | | + | |
| − | {{note|Service Types|Services are grouped by ''type'' on the server side. '''Outline''' services are used by the pages "with table" in an outline. '''Process''' services are used by forms (dialogs). '''Lookup''' Services are used by items showing a list of values (smartfields, listboxes).}}
| + | |
| − | | + | |
| − | As name choose ''StandardOutlineService'' since this OutlineService goes together with your ''StandardOutline'' (hence all the TablePages that will in your ''StandardOutline'' in the end will call a service operation in the ''StandardOutlineService'' at the end).
| + | |
| − | | + | |
| − | [[Image:Standardoutlineservice.jpg]]
| + | |
| − | | + | |
| − | If you click ''next'', you will see that there will be a ''Service Proxy Registration'' in the client plugin of your project. This will support for calling this service's operation from within the client as well.
| + | |
| − | | + | |
| − | [[Image:Servicereg.jpg]]
| + | |
| − | | + | |
| − | Click on finish in order to create the new service. If you expand now the node ''Outline Services'' you will see a new node ''StandardOutlineService''. Right click on it and choose ''New Service operation''.
| + | |
| − | | + | |
| − | [[Image:Newserviceop.jpg]]
| + | |
| − | | + | |
| − | Choose ''getCompanyTableData'' as a name, and as return name enter a double object array ''Object[][]'' and click finish.
| + | |
| − | | + | |
| − | [[Image:Getcompanytabledata.jpg]]
| + | |
| − | | + | |
| − | It is a good Scout practice to name service operations which collect data to be displayed in a TablePage in a way corresponding to '''''get*TableData'''''.
| + | |
| − | | + | |
| − | Now open the implementation of ''getCompanyTableData'' either by expanding the node ''StandardOutlineService'' and double clicking on ''getCompanyTableData'' or by opening the class ''StandardOutlineService'' directly (''CTRL-Shift-T'') and scrolling down to ''getCompanyTableData''. This is the place where we have to add an SQL statement which collects the needed data.
| + | |
| − | | + | |
| − | | + | |
| − | The DB you've downloaded contains the following tables:
| + | |
| − | | + | |
| − | [[Image:Company.jpg]]
| + | |
| − | | + | |
| − | [[Image:Person.jpg]]
| + | |
| − | | + | |
| − | As described in the [[Scout_Overview|Scout Overview]], Scout provides for a base service ''SQL''. In order to access the DB and select data therefore you need to call ''SQL.select(...)''. When writing your SELECT statement pay attention to specify the db columns in exactly the same order as the order of your table columns. The second parameter, the ''Bind Bases'', are needed to add a constraint to your SELECT statement. For the moment we leave that empty.
| + | |
| − | | + | |
| − | [[Image:Sql.jpg]]
| + | |
| − | | + | |
| − | == Load the data for your Page ==
| + | |
| − | The last thing to do is now to add the call to the ''getCompanyTableData'' service operation, for this we need to overwrite the method ''AbstractPageWithTable.execLoadTableData(SearchFilter)''. Go back to your ''CompanyTablePage'', in the lower part of the properties view ''exec'' click on ''Exec Load Table Data'' in order to create this method in your tablepage. When it asks you wether to create the create the method, click on ''Yes''.<br/>[[Image:Execload.jpg|left]]<br clear="all" />Now you can use the convenience accessor class SERVICES to lookup your ''IStandardOutlineService'' class and then call the method ''getCompanyTableData'' to load the data in your TablePage. Now restart your application and enjoy :-)<br/>[[Image:Services.jpg|left]]<br clear="all" />
| + | |
