Microsoft Dynamics® AX 2012 Enterprise Portal Development Cookbook White paper This white paper provides guidance on Enterprise Portal applica- tion development and customization. www.microsoft.com/dynamics/ax Mey Meenakshisundaram, Principal Group Program Manager Anees Ansari, Program Manager Send suggestions and comments about this document to [email protected]. Please include the title with your feedback. 1 Table of Contents Introduction ................................................................................................................................................................................................................ 6 User interface .............................................................................................................................................................................................................. 7 List pages ................................................................................................................................................................................................................. 7 Details pages ....................................................................................................................................................................................................... 11 Architecture .............................................................................................................................................................................................................. 12 Page processing ................................................................................................................................................................................................. 13 Web Parts .................................................................................................................................................................................................................. 15 Application Object Tree elements ................................................................................................................................................................... 21 Development tools and prerequisites ........................................................................................................................................................... 23 Before you get started .................................................................................................................................................................................... 23 MorphX ................................................................................................................................................................................................................. 23 Visual Studio ........................................................................................................................................................................................................ 23 SharePoint Products and Technologies ................................................................................................................................................... 24 Data sources and data sets ................................................................................................................................................................................ 25 Data sources ........................................................................................................................................................................................................ 25 Properties ......................................................................................................................................................................................................... 25 Methods ........................................................................................................................................................................................................... 25 Data sets................................................................................................................................................................................................................ 29 Methods ........................................................................................................................................................................................................... 30 Aggregation .................................................................................................................................................................................................... 32 Framework controls .............................................................................................................................................................................................. 35 AxDataSource ..................................................................................................................................................................................................... 35 Properties ......................................................................................................................................................................................................... 35 Filtering ............................................................................................................................................................................................................. 36 Methods ........................................................................................................................................................................................................... 36 Events ................................................................................................................................................................................................................ 37 AxForm .................................................................................................................................................................................................................. 38 Properties ......................................................................................................................................................................................................... 38 Events ................................................................................................................................................................................................................ 39 EPFormAction enumeration ..................................................................................................................................................................... 40 Requiring record context........................................................................................................................................................................... 41 Table inheritance and row creation ...................................................................................................................................................... 41 Layout controls ................................................................................................................................................................................................... 42 AxMultiSection............................................................................................................................................................................................... 42 2 AxSection ......................................................................................................................................................................................................... 42 AxMultiColumn ............................................................................................................................................................................................. 43 AxColumn ........................................................................................................................................................................................................ 43 AxGroup ........................................................................................................................................................................................................... 44 AxGridView .......................................................................................................................................................................................................... 46 Properties ......................................................................................................................................................................................................... 46 Events ................................................................................................................................................................................................................ 47 Examples .......................................................................................................................................................................................................... 49 AxHierarchicalGridView .................................................................................................................................................................................. 52 AxFilter ................................................................................................................................................................................................................... 53 AxContextMenu ................................................................................................................................................................................................. 54 BoundField controls ......................................................................................................................................................................................... 54 Examples .......................................................................................................................................................................................................... 55 Summary fields .............................................................................................................................................................................................. 56 Template fields ................................................................................................................................................................................................... 56 Action Pane and toolbars .............................................................................................................................................................................. 59 AxActionPane ................................................................................................................................................................................................. 59 AxToolbar ........................................................................................................................................................................................................ 61 AxLookup .............................................................................................................................................................................................................. 67 Multi-selection ............................................................................................................................................................................................... 69 PreLoad ............................................................................................................................................................................................................. 72 LookupCacheScope ..................................................................................................................................................................................... 73 AxDatePicker ....................................................................................................................................................................................................... 74 AxDateTimeHelper............................................................................................................................................................................................ 74 FactBox controls ................................................................................................................................................................................................ 75 AxPartContentArea ...................................................................................................................................................................................... 75 AxFormPart ..................................................................................................................................................................................................... 75 AxInfoPart ........................................................................................................................................................................................................ 75 CueGroupPartControl ................................................................................................................................................................................. 75 AxContentPanel ................................................................................................................................................................................................. 76 AxPopup ............................................................................................................................................................................................................... 78 AxModalPrompt ................................................................................................................................................................................................ 82 AxReportViewer ................................................................................................................................................................................................. 83 AxEnhancedPreview ......................................................................................................................................................................................... 83 List and details pages ........................................................................................................................................................................................... 84 3 Model-driven list pages .................................................................................................................................................................................. 84 Details pages ....................................................................................................................................................................................................... 86 Advanced list page development ............................................................................................................................................................... 88 List page interaction classes ..................................................................................................................................................................... 88 Secondary list pages .................................................................................................................................................................................... 89 Multi-selection ............................................................................................................................................................................................... 92 General guidelines ....................................................................................................................................................................................... 92 Preview pane title ......................................................................................................................................................................................... 94 Converting Microsoft Dynamics AX 2009 client list pages .......................................................................................................... 95 Converting Microsoft Dynamics AX 2009 secondary list pages ................................................................................................ 96 Report list pages ........................................................................................................................................................................................... 97 Advanced details page development ....................................................................................................................................................... 98 Creating a new project ............................................................................................................................................................................... 98 Editing an existing project ........................................................................................................................................................................ 98 Creating a new user control ..................................................................................................................................................................... 99 Editing an existing user control .............................................................................................................................................................. 99 Removing a web control ........................................................................................................................................................................... 99 General guidelines ..................................................................................................................................................................................... 100 Auto Action Pane buttons....................................................................................................................................................................... 101 Embedding user controls ........................................................................................................................................................................ 102 Modal window properties ....................................................................................................................................................................... 103 Modal windows – Interaction patterns .............................................................................................................................................. 104 Modal windows – Programming .......................................................................................................................................................... 110 CommonControls.ControlHelper ......................................................................................................................................................... 113 General development ......................................................................................................................................................................................... 114 Sessions ............................................................................................................................................................................................................... 114 Windows Server AppFabric..................................................................................................................................................................... 115 Context ................................................................................................................................................................................................................ 116 Data ...................................................................................................................................................................................................................... 119 Metadata ............................................................................................................................................................................................................ 121 Changing metadata at run time ........................................................................................................................................................... 122 Pages .................................................................................................................................................................................................................... 124 Page definition properties ...................................................................................................................................................................... 124 Events .............................................................................................................................................................................................................. 124 Page titles ...................................................................................................................................................................................................... 127 4 Custom filters .................................................................................................................................................................................................... 128 Creating custom filters in model-driven list pages ....................................................................................................................... 128 Creating an advanced filter via a user control ................................................................................................................................ 129 Creating a custom filter in a non-modeled list page by modifying the data set ............................................................. 130 Creating a custom filter in a non-modeled list page without modifying the data set .................................................. 131 Custom lookup ................................................................................................................................................................................................. 132 Creating a custom lookup in managed code.................................................................................................................................. 132 Creating a custom lookup in X++ ....................................................................................................................................................... 133 Getting the selected row ......................................................................................................................................................................... 133 AutoPostback when OK is clicked........................................................................................................................................................ 134 Proxies .................................................................................................................................................................................................................. 135 Creating a new proxy project ................................................................................................................................................................ 135 Proxy deployment ...................................................................................................................................................................................... 137 General guidelines ..................................................................................................................................................................................... 137 Formatting ......................................................................................................................................................................................................... 138 Validation ........................................................................................................................................................................................................... 139 Error handling ................................................................................................................................................................................................... 140 Debugging ......................................................................................................................................................................................................... 141 Infolog ................................................................................................................................................................................................................. 144 ViewState ............................................................................................................................................................................................................ 145 WebLink and AxUrlMenuItem.................................................................................................................................................................... 146 HTMLUtilities ..................................................................................................................................................................................................... 148 Adding JavaScript............................................................................................................................................................................................ 149 Images ................................................................................................................................................................................................................. 149 ASP.NET chart controls ................................................................................................................................................................................. 150 Web modules .................................................................................................................................................................................................... 152 ShowParentModule ................................................................................................................................................................................... 152 Cues ...................................................................................................................................................................................................................... 153 SharePoint integration ....................................................................................................................................................................................... 155 Enterprise Search ............................................................................................................................................................................................. 155 Themes ................................................................................................................................................................................................................ 158 Tips ........................................................................................................................................................................................................................ 158 Workflow ................................................................................................................................................................................................................. 159 5 Introduction Enterprise Portal for Microsoft Dynamics AX is an organization’s window into its business. It enables users to di- rectly access relevant business information, and to collaborate and conduct business transactions with Microsoft Dynamics AX. Enterprise Portal also serves as a web platform. It enables developers to web-enable and customize existing business applications in Microsoft Dynamics AX, or to create new business applications. Enterprise Portal expands the reach of your enterprise resource planning (ERP) solutions. It provides a simple and intuitive user interface that helps improve productivity. Developers can easily customize and extend Enterprise Portal to quickly respond to changing business needs. The framework enables rapid application development, so that you can jump-start your solutions. Simplified installation, deployment, and management tasks help system administrators be more efficient. The primary help resources for developing Enterprise Portal are available at Enterprise Portal for Microsoft Dy- namics AX on MSDN. 6 User interface Pages in Enterprise Portal provide the main mechanism for organizing content. Enterprise Portal uses a set of standard page types throughout the application to enforce a consistent layout, making the application intuitive for users. Two main page types are the list page and the details page. List pages List pages in Enterprise Portal display a list of records. This section describes the various user interface compo- nents of a list page. Figure 1 An Enterprise Portal list page Top navigation bar The top navigation bar is a set of links at the top of the page. Users can use this to navi- gate between the various modules that are visible to them, such as Sales and Procurement. Each link in the top navigation bar points to the default page of the corresponding module. Figure 2 A top navigation bar 7 Action Pane The Action Pane uses the familiar Microsoft Office ribbon layout. It categorizes a set of buttons on contextual tabs and in button groups. This enhances simplicity and discoverability, because the actions that are available vary, based on the permissions that the user has been granted. For example, in the following figure:  The buttons are first grouped on various tabs, such as Customer, Sell, and General.  The Customer tab is currently selected, and its contents are visible.  On the tab, the buttons are further grouped into button groups, such as New, Maintain, Ac- counts, and Price. Figure 3 An Action Pane Quick Launch Quick Launch is a set of links on the left side of the page. Users can use this to navigate to the various areas and pages within a module. In Microsoft Dynamics AX 2012, support was added for displaying a hierarchy, so that you can show multiple levels of links. By default, Quick Launch contains links to both primary and secondary list pages. Secondary list pages apply additional conditions to filter and display a subset of the data displayed on the primary list pages. Figure 4 Quick Launch Quick filter A quick filter is a control used to apply a simple filter condition on a list page. The quick filter pro- vides a menu of the fields displayed in the grid. A user can select a field and specify a value to search for in that field. The quick filter was added in Microsoft Dynamics AX 2012 to help reduce the number of clicks required to find data. Figure 5 A quick filter 8 Advanced filter An advanced filter is a control used to apply complex filter conditions on a list page. The ad- vanced filter enables filtering for all fields, not just the fields displayed in the grid. It also provides a range of op- erators and enables multiple simple filter conditions to be combined to create a complex filter condition. Figure 6 An advanced filter List The list displays the records on the page in a grid. It provides the ability to sort, select, and page through the records. The conditions applied by using the quick and advanced filters filter the records displayed in the list. Figure 7 A list Preview pane The preview pane is the area below the grid and is used to display extended information for the record that is currently selected in the list. The preview pane is automatically updated, based on the selected record. The preview pane is a great way to show users more data on the same page, without making them navi- gate away. Figure 8 A preview pane FactBox FactBoxes are displayed on the right side of the page. A FactBox is used to display information related to the record that is currently selected in the list. Like the preview pane, FactBoxes are automatically updated, based on the selected record. They help show the user more data on the same page. 9 Figure 9 A FactBox 10