View source for Documentation YAML for OpenPetra Forms

== Inheritance ==
* generally the yml files inherit from each other ('''BaseYaml''')
** this allows us to only define the default menu items once, in PetraForm.yaml, and they will be included in all derived forms
== Attributes of the root node ==
* '''Template''': this refers to the cs file that is used for the template; PetraForm.yaml points to window.cs; the templates are located incsharp\ICT\PetraTools\Templates\Winforms
** ''window'': the default template, sufficient for module main screens etc; example: FinanceMain
** ''reportwindow'': for the reporting screens
** ''windowEditUIConnector'': this is for bigger edit screens, that require stateful sessions on the server; example: PartnerEdit? APEditSupplier?
** ''windowMaintainTable'': maintain the rows of a single table, in a grid, with edit section at the bottom; example: SetupCurrency
** ''windowEditWebConnectorMasterDetail'': edit a master row, and maintain the detail rows; example: APEditDocument
** ''windowFind'': template for find screens. uses UIConnector for paged search results; example: APMain
** ''windowTDS'': template for complex find and browse screens that allow to change the data; example: GLBatch
* '''FormType''': Is not so important, because '''Template''' already defines a lot; at the moment, only the ''report'' type is different from the other types; this might change, and we will only need Template but not FormType
** ''abstract'': if this is just used as a base form for other real forms
** ''navigation'': the main window, the module windows
** ''edit'': edit screens
** ''crud'': CRUD screens (Create, Read, Update, Delete)
** ''find'', ''browse'': find screens
** ''report'': reporting screens
* '''MasterTable''': if this is set, you will need to write less DataField attributes for the controls. The name of the controls will be matched to a field in the given table; if such a table field exists, it will be linked to the control.
* '''DetailTable''': similar to MasterTable, but this is for the detail table; controls must have the word ''Detail'' after the prefix, eg. txtDetailAmount
* '''DatatableType''': this is used for the DetailTable, if it is derived from a database table, in a dataset; eg UC_GLTransactions: <code>DatatableType: Ict.Petra.Shared.MFinance.GL.Data.GLBatchTDSATransaction</code>
** Update: better use DatasetType, which allows mapping of tables to their dataset names automatically
* '''MasterTableType''': this is used for the MasterTable, if it is derived from a database table, in a dataset
** Update: better use DatasetType, which allows mapping of tables to their dataset names automatically
* '''DatasetType''': this will make sure that fields get mapped much easier to the appropriate table and datafield. You can use eg a controlname txtPFamilyFirstName, txtNoSolicitation, etc., and the controls will be mapped to the right table. You can even use data fields from custom tables and custom fields. You have to use the full namespace for DatasetType.
* '''UsingNamespaces''': refer to namespaces that should be included
* '''Namespace''': this is the namespace that this screen should belong to. eg. <code>Ict.Petra.Client.MFinance.Gui.AccountsPayable</code>
** if you want methods to be linked automatically to a web connector, you need to make sure that there is a webconnector in the same namespace (Server instead of Client, without Gui, but WebConnectors at the end), eg. <code>Ict.Petra.Server.MFinance.AccountsPayable.WebConnectors</code>.
* '''ClassName''': this is only required if the name of the yaml file should not be the same as the name of the class; the naming convention is: TFrmSetupCurrency is the classname, SetupCurrency.cs is the filename; for user controls: TUC_GLJournals is in file UC_GLJournals.cs
* '''PropertyForSubScreens''': this is useful if you use '''ActionOpenScreen''' in your actions, because it will assign the property to the new screen (if it has that propery too); eg. in Finance module the ledger number
* TODO: '''BaseYaml''', '''FormTitle''', '''WindowWidth''', '''WindowHeight'''

== Events ==
* '''Events''': here you can link form events to methods in your code
** eg. <code>Activated: {class=System.EventHandler,method=FTheObject.TFrmPetra_Activated}</code>
== Actions ==
* '''Actions''': actions can be used by menuitems, toolbarbuttons, and other controls; this is useful to be able to enable/disable an action on the whole screen, and to only define a certain action once, and refer to it from all controls that trigger the same action
** eg. <code>actClose: {Label=&Close, ActionId=eClose, Tooltip=Closes this window, Image=Close.ico}</code>
** eg. <code>actMainMenu: {Label=Petra &Main Menu, ActionClick=FTheObject.OpenMainScreen}</code>
** '''Enabled''': Actions can depend on other actions or conditions; they will be disabled if the condition is false; eg <code>Enabled: cndSelectedSupplier</code>; this can be set in a grid, with '''SelectedRowActivates'''; eg <code>grdSupplierResult: {Dock=Fill, ActionDoubleClick=actSupplierTransactions, SelectedRowActivates=cndSelectedSupplier}</code>

* special situation: create a detail row: see for example APEditDocument.ManualCode.cs; we do use the generated function CreateAApDocumentDetail, but we need to first calculate some actual parameters

* Actions are linked by menu items, toolbar buttons etc either by using attribute '''Action''', or by convention, ie. the name of the control matches the name of the action (eg. mniSaveSettingsAs matches actSaveSettingsAs)

== ManualCode ==
The following functions can be written in the *.ManualCode.cs file, and the next run of nant generateWinforms will pick them up and call them from the generated code. If the functions don't exist, they will not be called from the generated code: this should avoid unnecessary empty functions in the manual code file.

Here are the names of the manual functions:
 InitializeManualCode (run before activation)
 RunOnceOnActivationManual
 ExitManualCode
 NewRowManual
 StoreManualCode
 ShowDataManual
 ShowDetailsManual
 BeforeShowDetailsManual
 GetDataFromControlsManual
 GetDetailDataFromControlsManual
 ReadControlsManual (for reports)

== Controls ==
* '''Controls''': see [[Screen scaffolding: controls]]
== Menu & Toolbar ==
* '''Menu''': 
** if you are working with a window template derived from PetraForm.yaml, then there is already a mnuMain control with the Close button
** if you are working with a tabbed page (eg using template controlMaintainTable, deriving from UserControl), you should add a control with name mnuTabPage; the contents of that menu will be added to the main menu when the tab page is active.
** generally, when deriving forms from each other, the menu items are inherited; use attribute '''Order''' with values '''AlwaysLast''', or '''AlwaysFirst'''. Whoever is higher in the hierarchy, will have more weight. eg. the Help Menu Item in the root yaml file with Order=AlwaysLast will always be last, even if derived forms will have another item with AlwaysLast, which will be inserted before the help menu item.
* '''Toolbar''': very similar to Menu, just different names: tbrMain, tbrTabPage

== Layout ==
* '''Layout''': TODO (Tabbed pages etc)

Another option for layout is the '''Controls''' property that can be used for Panels and GroupBoxes: You can use several rows to arrange the controls and they are aligned in a table layout. see also [[Screen_scaffolding:_controls#Layout_of_Controls|Layout of Controls]]