Contents
This overview introduces the necessary concepts to enable you to develop WebMaker applications. The aim is to provide wide coverage of topics that are required for the full WebMaker development lifecycle, starting from installation and development, through to deployment and management. You do not have to read the whole document in isolation and you will not need all the information to start developing applications. You can combine this section with the WebMaker Tutorials for a more hands-on experience and reference the relevant sections of this document as you encounter the specific topics depending on the type of application you are building.
Some areas of this document act as introductory material to other parts of the WebMaker documentation and these will be highlighted in the relevant areas. The other main documents you may need to consult for more detailed instructions once you start developing include the FormMaker User Guide, XDE User Guide and the RuleMaker User Guide. Please see the WebMaker Installation and Administration Guide for installation instructions.
WebMaker is a versatile RAD environment, designed to simplify the composition of complex web applications using SOA services. WebMaker's runtime environment is a powerful SOA platform that provides all the power and flexibility of SOA. However, accessing the power of this platform does not require in-depth programming skills.
WebMaker can be used to compose many different types of applications, including:
Dynamic data-driven Self-Service Web Applications and eForms
Feature rich, Ajax-based high transaction e-Commerce and Internal solutions
Contact Centres - CRM integration with existing Line of Business systems
Service-oriented Web Application development for COTS Package Developers
WebMaker provides a complete design and deployment platform for the composition and deployment of Rich Internet Applications (RIA). Unlike other technologies, WebMaker has the ability to compose SOA Services from internal and third-party services, which can then be used to compose RIAs. It is therefore possible to compose complete RIAs for SOA that are enterprise-strength within the WebMaker environment.
Based on a native service-oriented platform, WebMaker provides all the productivity benefits of web application development and leverages a powerful web services platform for page orchestration and integration. WebMaker can be used to automate most of the time consuming elements associated with web application development and integration.
WebMaker has a range of Web Based Graphical IDEs that accelerate the design and composition of modern applications:
Reduced Painting - Use existing WSDL and Schema files to create pages, removing the need to 'paint' pages one field at a time. This includes the ability to drag-and-drop database schema information to create pages. You can also use a range of palette controls, templates and existing pages to help accelerate your development. WebMaker also provides the ability build your own custom controls that can be simple or complex in nature.
Reduced Scripting - Use constraint information within Schemas to perform automatic client-side data validation without having to write script.
Automatic Data Binding - Graphically bind HTML fields to XML structure on the server, removing the need to write custom code or binding frameworks.
Web Service Interoperability - Use the service information contained within WSDL files to automatically generate remote web service proxies, removing the need to write SOAP wrappers and transport coding.
AJAX Support - Write Rich asynchronous pages without massive scripting effort.
Language Support - Write dynamic pages to enable multilingual translations, without modifications.
Accessibility - Write more accessible applications, without parallel development or significant additional coding.
Traditionally, dynamic web applications need to compose XHTML for the browser and decompose the information posted from the browser in server-side logic. WebMaker uses innovative XML techniques to eliminate the bulk of the effort required to pre-populate and validate information to and from the browser. WebMaker uses XPath to enable information to be mapped between the XML form and the underlying XML document from which the data is derived. This is a two-way mapping that provides pre-population of information to the browser and the subsequent capture, after the information has been posted from the browser. This enables the automation of a large part of the server-side scripting role, typically associated with web application development and involves drag-and-drop operations instead of traditional coding.
The key steps for developing WebMaker applications include the following:
Design screen navigation diagram for complex applications (you can start with a single page).
Design or reuse a CSS and application Skin (defaults are available to get you started).
For each page, define or reuse a schema as a starting point, if necessary, to accelerate development. Additionally, you can use the range of controls available in the design palette as well as templates and existing pages. You can also use WSDLs and database Schemas to drag-and-drop information during the page creation process.
The complete application or specific page(s) can be generated at this stage for preview and deployment. The pages at this stage will include validation script based on the underlying schema model and data bindings to enable pre-population of pages and the capture and structuring of html page data after submission. The remaining steps below enable individual fields or groups of fields to be selected, styled, positioned, validated and mapped.
Indicate fields that will be part of each form. Include additional fields here for buttons, etc., which may not be part of schemas.
'Fine-tune' display and validation for each field if required.
Bind fields to XML elements in both directions using XPath.
Design and adapt server-side Controllers for page delivery and remote service orchestration as well as database access.
Import WSDL files to generate remote service proxies that can be used by WebMaker applications to call remote web services.
As well as the XML forms, each WebMaker application uses additional separation of key web application components to enable better engineering and easier future maintenance.
WebMaker application-wide assets:
Common Cascading Style Sheet - This is used to provide a generic application-wide look-and-feel and provides separation of content and presentation.
A common Application Skin - This is in the form of an XSL and provides a template for the overall application. The skin will provide placeholders for menus, logos, headers, footers, etc. The actual content will override this template as necessary for each page, but the parts that are not overridden will remain the same.
The CSS and Skin require definition only once and provide an overall look-and-feel and layout for the web application. The main purpose of WebMaker however is to enable the creation of XML forms. This is achieved by using a component of WebMaker known as FormMaker. FormMaker is part of XStudio and provides a web-based IDE for creating XML forms. FormMaker can be used to produce the following elements of a web application:
Page-specific elements
XML forms encapsulated in XSL. These XSLs are transformed to XHTML during execution to enable wide browser coverage without downloads.
Page-specific CSSs to override or complement the application-wide CSS if necessary.
Javascripts. A common set of javascript files are present for the application, which contain generic scripting for client-side validation. A large part of this scripting is generic and activated based on the schema information that is present for each form. Additional server-side logic can be included to compliment the client-side scripting.
XML Data Mapping information. Similar to the scripting, this information is distributed between the client and the server and enables the data to be mapped bi-directionally between the browser and the underlying XML documents. Once defined, this element is automated and very transparent to the designer.
To get started with WebMaker you need to create a Workspace and a Project. Each Workspace can contain multiple projects and each project is typically deployed as a Web Application. When you start WebMaker for the first time you will need to create a workspace by typing in a name and clicking the New button.
Once the workspace is created you can select the workspace to arrive at the Application Types screen. For web application development you will typically select the Web Application option. For some installations of WebMaker you may not see the Application Types screen, depending on your configuration.
You can manage projects using the Available Projects tab. Using this tab you can create new projects and also Import and Export projects. This provides a convenient method for sharing and archiving WebMaker projects. You can also Copy and Delete projects from this tab.
Once you have created or imported a suitable project, you can click through and start working with the project. The project details are shown within the eXtensible Design Environment (XDE), which deals with most of the server-side development aspects of WebMaker, including rules composition, application packaging and deployment, communication protocols, message tracking, etc. For WebMaker applications you will very rarely need to navigate further from the Project Details tab within XDE. You can start some additional tools to help you build, deploy and test WebMaker applications. You will find these tools and additional options listed along the top of the Project tab. To start creating the overall application map, click one of the FormMaker links.
WebMaker is based on Hyfinity's Morphyc Architecture. The Morphyc Architecture uses a design and deploy approach for composing SOA applications. Products such as WebMaker use a range of design tools to compose application specifications, which are then deployed onto a runtime platform for execution. There is no separate compilation process within the architecture. Furthermore, the design of an application is similar to the runtime, with the XML assets created during the design process actually executing when the application is deployed to the runtime platform.
The Morphyc Architecture uses a native XML service-oriented approach. This means all interactions are loosely-coupled and performed using XML message exchange. The main processing components within the Morphyc Architecture are Nodes. The design tools and the runtime platform are concerned with the design, deployment, execution and monitoring of Nodes.
This section covers the high-level product architecture. For more detailed and product-specific architecture information please see the Runtime Architecture section under Advanced Options.
XStudio (alias: Studio)
XStudio is the collective name for the design and monitoring tools within the Morphyc Architecture. The core XStudio components are described below:
eXtensible Design Environment (XDE) is used for designing Nodes and their interactions. XDE is used to create and manage XML assets and Patterns, used to organise collections of Nodes.
RuleMaker is used for creating Rules, executed by Nodes.
Dashboard is used during application design and runtime. The Dashboard can be used to trace message flow, perform general debugging and also administer the runtime platform, including logging and scalability settings.
XStudio Plugins - The core tools within the Morphyc Architecture include, XDE, RuleMaker and Dashboard. Individual products may include their own plugins to work with certain aspects of the Morphyc Architecture. For example, WebMaker uses FormMaker for Forms Design. FormMaker in-turn uses various XML editing tools, such as XMLSpy to create XML assets.
FormMaker is an XStudio plugin, available as part of the WebMaker product. FormMaker enables the composition and deployment of rich web applications based on SOA services.
Repository (alias: XStore) - Application specifications created by tools such as XDE, FormMaker and RuleMaker, consist of XML metadata. This information is stored within a file-based repository. You should not have to interact with XStore directly.
Blueprint
A Blueprint is a collection of XML metadata, produced by XStudio. A Blueprint within the Morphyc Architecture refers to a particular composition of architectural layers and pattern arrangements, specifically organised to perform particular tasks. For example, the MVC WebMaker blueprint is primarily concerned with the development of rich web applications based on SOA services. The core components of the Blueprint are described below:
Project (aliases: Blueprint Instance, Specification, Design) - A Project is a collection of XML metadata that describes an application, based on a Morphyc product such as WebMaker.
Patterns contain XML metadata that describes collections of Nodes, their Rules, their XML assets and their interactions with other Nodes. Patterns can be viewed as a reusable grouping mechanism for Nodes, arranged to perform certain tasks.
Node (aliases: Agent, Controller) - Nodes are the processing components of the Morphyc Architecture. Nodes execute Rules and may consume and produce other XML assets, such as XSLs, XSDs, etc., as they execute. During the design phase, this is just a metadata representation of the machines. They become 'real' once deployed and executed on XPlatform.
Rules (aliases: Rulebase, Logicsheet) - Rules are represented as XML metadata and executed by Nodes.
Interactions (aliases: Splices, Associations) - Interactions capture the communications between different Nodes, typically exchanging XML messages.
XPlatform (alias: Platform)
XPlatform is the runtime platform that executes Nodes. XPlatform can also use XGate to perform external communications such as HTTP and SOAP. XPlatform can also use Custom Engines to perform specialised processing that may not be ideally suited for a declarative rules-based system.
XGate provides the ability to send and receive messages over different protocols. By default, XGate can communicate over HTTP and SOAP, including REST programming.
XGate Plugins - XGate also has the concept of Plugins that can be used to perform specific tasks. For example, WebMaker uses a Forms Plugin to bind HTML and XML information between the Browser and server environments. You can write your own custom plugins for XGate.
Nodes - (aliases: Agent, Controller) - Nodes execute Rules and interact with other Nodes according to the design. Nodes are the main processing components within the Morphyc Architecture.
The XEngine is the main processing component, and is the heart of each Node. XEngine is a declarative, forward-chaining rules engine that is triggered by incoming requests.
Custom Engines can be written is Java to perform specific processing tasks that may not be best-suited for a native XML forward-chaining rules engine. These custom engines can be integrated with XPlatform in exactly the same way as native XEngines.
XLog is the main logging component of XPlatform. XLog is used by Dashboard to perform the message tracing and debugging operations.
Running WebMaker applications can be thought of as being in two parts. The visual client-side of WebMaker applications are typically web pages, with server-side controllers handling the page orchestration, remote service orchestration, database access, business logic, etc.
You can start your application composition from the client or server parts of WebMaker, but in almost all cases the two are linked by the underlying WSDL and Schema models that define much of the messaging that takes place between WebMaker applications, databases and remote web services.
FormMaker is the main tool you need to create WebMaker applications. You can start FormMaker from the XDE Project tab. You can use the FormMaker Page Structure link to jump straight to the Page Structure tab within FormMaker. This will either create a new blank form or select the first available form if forms already exist within this project. You can also select the FormMaker Application Map link to jump to the Application Map tab within WebMaker. This enables you to create your overall application map before selecting pages or controllers for further design steps. Whether you choose to use the Page Structure link or the Application Map link to launch FormMaker you can switch between the two tabs once you are within FormMaker. These different links for launching FormMaker are for convenience depending on the type of Designer using WebMaker and the type of application being designed.
Within the Application Map tab you have a palette on the left that can be used to create the overall application map. The middle section is the canvas where you can paint the application map. The right hand panel is context-sensitive and will display information relevant to the component that is selected on the canvas.
In order to create your first page, drag and drop a Full Page from the left hand palette on to the canvas in the centre. Once your page is shown on the canvas, you can change the default name by double-clicking the page image. You can also use the right-click to access the context menu that contains the most relevant actions for the item on the canvas.
You can now paint the page by using the Page Structure tab. You can access this tab by clicking the tab at the top or by right-clicking the page and selecting the Page Structure option from the context pop-up menu. Once you are on the Page Structure tab, you will find a palette on the left, which you can use to paint your page. The canvas is on the centre of the screen and represents the page that is being painted. The right hand side of the screen has a set of tabs that are designed to assist with data-driven page design. You can choose to use WSDL files, XML Schemas, Database Schemas, External Application data, Templates and Existing pages to choose data that you wish to include on your page. The Templates tab provides a set of common page templates that can be used as the basis for the page. The Existing Page tab lists all pages within the application map that can be cloned to paint the new page. Whichever option you choose on the right you will typically see an XML document structure containing design information. You can simply drag-and-drop parts of the structure to paint your page. This is the fastest approach for painting pages.
As well as painting the screen, the drag-and-drop information will enable scripts and data bindings for this page. We will discuss validation and bindings later in this document. At this stage we can preview the page. To do this you need to use the set of round buttons on top of the screen. The buttons are available on all tabs within FormMaker, enabling you to preview pages at any time. Use the Generate button to generate the page. Once this has completed you need to click the Preview button to preview the page.
Please Note: There are two tabs on the canvas within the Page Structure tab. The Tree View tab provides a tree structure representation of the page layout, which can be useful during restructuring of pages containing large amounts of information.
Now that we have a page we need a server-side component to receive information from the page. These server-side components in WebMaker are known as Controllers. If you return to the Application Map tab you can drag and drop a Controller from the left hand palette on to the canvas. Again, you can rename the Controller by double-clicking or using the right-click. You can single click the Controller to select it. When selected, the right hand panel will display information relevant to the Controller. We will return to these options later, but for now this is all we need to do to create a server-side controller capable of receiving a request from the page we created earlier.
Now that we have a Page and a Controller, we need to link them together to indicate the direction of information flow. You can indicate information submission by dragging the Action item from the left had palette of the application map tab. Ensure that the originating component of the action is selected on the canvas before dragging the Action because the selected component will be treated as the starting point of the action. Then simply drag and drop the action on to the target component, in this case the controller. This should create a link between the Page and the Controller. You should now be able to single click the Action Link to highlight information relevant to the Link on the right hand panel. Here, you can enter a name for this action. You can also rename the action by double-clicking it or by using the the right-click menu. This will become the name of the form action when the page is generated.
Please Note: you can create as many actions as required. You can also create page-to-page actions and also controller-to-controller actions. Please see the Tutorials and the WebMaker online FAQ for more information.
Now you need to create a field or designate a field on the page to trigger the action. You can do this by revisiting the Page Structure tab and painting a button or hyperlink. Then select the Field Details tab. The Field Details tab contains a left hand panel that lists the items on the Page. From this panel you can select the field you want to use as the submit trigger. For each field there are numerous attributes that can be set to determine look-and-feel, behaviour, etc. We will cover some of these details later and you can learn more by reading the FormMaker User Guide. For now, we are interested in the Event Options category. Here, we can create an event. By default you should find that the onclick event is selected, together with the Form Submission action. Also, since there is only one action originating from this page this action should be preselected. You can change the events, actions and the mappings to the page actions using the various select boxes. We will cover some of this in more detail later. For now we can simply leave the default settings for the new event.
Within FormMaker you have two buttons on the top menu for deployment. These enable you to deploy a single page at a time or the complete application. During initial setup of the application map it is a good idea to use a full deploy to ensure application integrity. Once the application map becomes more complete you can deploy individual pages as you make localised changes.
For our application, click the Generate Application button on the top menu to ensure all application components are generated. Once this is complete click the Deploy All button from the top menu. During development of WebMaker applications, the deployment operations package a copy of the application onto the runtime server that typically runs on port 7080.
When you are ready to package the application for publication to the target live environment you can use the Publish button to select the target environment. Full Deployment and Publication options are available from the link within the XDE Project Details screen. Please see the XDE User Guide for more details.
WebMaker applications run on XPlatform, which is the common web services platform for Hyfinity applications. The runtime Dashboard is the main tool used for running and debugging WebMaker applications. You can start the Dashboard from the top menu within FormMaker. When you first start the Dashboard it will attempt to start the runtime server that will host your deployed applications. To run the deployed application use the Run Application button on the top menu of the Dashboard. You can also start the Dashboard from the Project tab within XDE.
Dashboard is highly configurable and we will cover some of the features in more detail later. Typically, Dashboard is deployed in Development and Production modes. In development mode, all message flows are logged and tracked, starting from the browser, through to remote services and back again. You can organise and view these message flows from within the Dashboard tab. Click the Show Development & Platform Logs button to see the message flows. You can expand and shrink different messages to follow the flow through the runtime platform. This should provide full visibility of the application as it executes. You can click the View in RuleMaker link to open the Rules that were executing at that point in time. We will cover Rules in more detail later. We will also cover more detailed aspects of the Dashboard, including configuration of the logging parameters later in this document.
WebMaker hides much of the protocol and wrapper information for web service invocations by default. This means you can access remote services in a similar manner to local services. Typically, remote services are invoked from Controllers. You can single click a Controller on the Application Map tab to display the relevant details on the right hand panel. You should see an Available Services drop-down. This list should contain all imported service definitions from WSDL files. You simply select the service you are interested in and click the Use Service link. WebMaker will generate the appropriate proxies to compose and make the calls.
The list of Available Services is populated and altered whenever you drag and drop elements from WSDL files to create the structure of your screen within the Page Structure tab. WebMaker parses the WSDL files as they are used and determines the Web Services that may need to be used within a particular page. Proxies for these services are automatically created and made available within the Available Services drop down.
If you know the list of Web Services that will be used within a project in advance you can create the list of available services in the drop-down by importing the relevant WSDL files. You can do this by clicking the Import Service option at the bottom of the Project tab within XDE. You will need to reveal this link by clicking the Show Advanced Options link on the top right hand corner. This process parses the WSDL to generate proxy services for all service definitions contained in the WSDL from the XDE Project screen. You can learn more about this process in the Advanced Options section, but for now this is all that is required to call a remote service from within a WebMaker Controller.
WebMaker provides different binding options to ease the development process. This is achieved using the Page Structure tab and the Data Bindings tab within FormMaker. All bindings in WebMaker occur between HTML page elements and a server-side XML structure. The type of binding you use will depend on the type of page you are building and also the type of operation you are performing from the page. There are two categories of bindings, Page Bindings and Action Bindings. Page bindings occur when a page is supplied by the server Controller and sent to the browser for display. This process involves binding data from an XML structure on the server to the HTML elements on the page. The XML structure is always referring to the structure of the data within the server Controller at runtime.
As you drag and drop controls from the palette and the various design helpers on the right hand panel of the Page Structure tab during the design process, WebMaker will generate default binding structures for you. By default, controls within the palette will reside within the <formData> tag. Any structured data dragged from the right-hand panel will generate a structure that is similar to the original data structure. You can view the generated documents within the right-hand side panel of the Data Bindings tab.
Please note that the generated documents are initial assumptions and you can modify the generated XML instances to more closely resemble your runtime XML data structure. For example, if your server data will contain a composite document resulting from two service calls then your binding instance will contain the response fragments from two responses in a container element of your choice. You can manually change the instance document from the Data Bindings tab.
To return to our task of binding XML data from the Controller to the HTML page elements, you can visit the Data Bindings tab.
On the Data Bindings tab you will see two tabs on the left hand side. The Bindings tab should be selected by default. This tab contains the page elements. The centre section also contains two tabs, one for the Page Display Bindings and one for the Action Submission Bindings. In this scenario we are interested in the page bindings. The right hand panel will display the instance document that was generated by default during the page creation stages. You can change individual bindings by dragging-and-dropping the XML elements on the right to the Page Display Bindings tab in the middle. This binding represents the binding of the server XML element on the right hand side to the page element on the left hand side via the XPath shown on the Page Display Bindings tab in the middle.
Please note that most of the bindings will be completed already. This is performed when you drag and drop the schema structure to create the page in the first instance within the Page Structure tab. You can manually change the elements that are incorrectly bound by selecting the page field on the left and dragging and dropping the elements on the right into the Page Display Bindings tab in the middle. Using these bindings WebMaker will ensure runtime data contained in an XML structure within the Controller is bound to the correct fields on the page.
In the previous section we learned how to bind XML data on the server to HTML fields on the page. WebMaker also enables you to automatically bind HTML field data captured within forms to XML structures on the server Controller. The process is very similar to the one discussed in the previous section, except we can indicate an XML binding fragment for each Action within a page. Again, the XML fragment to bind to is arbitrary and represents the data structure of the Controller at runtime. Navigate to the Data Bindings tab. You are now interested in the Action Submission Bindings. Select this tab on the centre panel and you should see expandable sections for each of the actions that are available on the page. You will also find that most of the bindings will have been pre-populated for you when you created the Page Structure. Using the same drag-and-drop approach as in the previous section you can drag XML elements on the right hand panel onto the bindings tab on the centre for the page field that is selected on the left hand panel.
You can actually insert dummy data into the XML fragments and generate and preview pages as you bind information. The previews should show the data as bound if the bindings have been created correctly. The structure of the data on the right-hand side panel represents the data as it will appear when the selected action is clicked at runtime.
There will be occasions when you may wish to bind submitted HTML fields to an XML fragment that is determined at runtime. This may be because you wish to preserve the data within the fragment and populate or overwrite certain fields only. Whereas the static binding approach discussed so far will create the binding fragment during application design, the dynamic approach creates the binding fragment from the runtime XML structure, together with the runtime data. This in effect helps you to preserve the page data between different server calls
In order to achieve this you need to be located within the Data Bindings tab. Select the Action Configuration tab on the left hand side and click on the action that you are trying to bind. The middle panel should now display the Action Configuration tab. Within this tab you can select the Keep previous form data option.
You can also use the Maintain Additional Link option to preserve as many data fragments as required between page invocations.
The Use base document structure? option uses the XML binding structure created and modified during page design to bind submitted action data). Please see the section on Data Binding within the FormMaker User Guide for more details.
There may be occasions when you need to bind the same page field to many server fields in the submitted structure. For example, you may wish to bind a field to a database request as well as a web service request. In order to achieve this you need to be positioned on the Actions Submission Bindings tab within the Data Bindings tab. You can now use the Add Additional Binding link to specify additional page field to server field bindings.
Please Note: that you can perform the same type of operation within the server rules, but in some scenarios it may prove much easier to perform the bindings during page submission. You can consult the RuleMaker User Guide for more information on server rules. Some of the relevant server actions include Copy, Move and Assign.
Remote service requests are generally created for you by default if you use a WSDL operation message as the binding fragment. The process of submitting the action will bind the HTML fields to the XML structure on the server. The Controller then passes this information to the proxy service, which will perform the necessary wrapping and submission.
You only need to intervene if you wish to perform additional processing on the server Controller before submission. We will cover this under the section on Business Rules, Composition and Orchestration. A detailed explanation on this aspect is also included in under the Advanced Options section.
More detailed information on page design and all available features can be found in the FormMaker User Guide. The two main information container concepts in WebMaker include Groups and Repeats. Repeats and Groups can contain each other. For example, you can define a repeating group of addresses, each address can be a group of fields - house number, postcode, etc. Within this group you may have a repeating set of address lines. When you create page structures from schemas the Repeat and Group structures are created for you by default, but you can add your own versions and remove redundant groups, repeats and elements.
Groups and Repeats are important data-driven design components and they affect the structure of pages, as well as the visibility of fields. In WebMaker it is important to think about the information you wish to display or capture on a page. This is to ensure that the layout of the information is separated from the information itself. For example, we may include a set of fields on a page, however this does not prevent us from choosing to display these fields as a list, set of tabs, repeating group, or not displaying them at all.
Most of the detailed design is undertaken within the Field Details tab. Using this tab you can change the types of controls you want to use for the fields and the look-and-feel of individual fields, data constraints, etc. You can also control field visibility dynamically, perform dynamic hiding and showing, perform value conversions and indicate how to handle errors. You can also indicate mandatory fields. For repeating information you can indicate whether to introduce scrolling for lists, define row and column styling as well as sorting options. For groups you can define the layout of the information group. Specific control types, especially lists, tables, grids, tabs, etc are explained in-detail in the FormMaker User Guide. You can also consult the "How To" Guides.
You will also notice an Event Options section that can be used to define the events against fields on pages, including groups. This area handles the various submission methods, setting of field values and the ability to call custom java script
On the Page Structure tab you can also use the Custom Field element. This field can be used to include any custom HTML fragment within your page.
Each Action Link that is painted on the Application Map tab is available for invocation over HTTP. The action request will be processed, together with any supplied parameters and forwarded to the linked Controller for further processing. The invocations can be via URL, basic HTTP or SOAP.
Within the Field Details tab you will notice a section on External Events. Within this section you can select actions based on events that occur within external application scripts. Essentially, WebMaker generates Javascript functions for each external event that is created and these script functions can be called from external application scripts. The generated WebMaker functions call separate script functions that can be created and modified as required. This level of client script integration is controlled using a event_config.xml file within the common collection of the WebMaker repository.
The main styling of applications within WebMaker is performed using CSS. On the Application Map tab under Advanced Options on the left hand panel you can see the name of the CSS file that is used. This is the application-wide CSS file affecting the whole WebMaker application. You can use a CSS of your choice to style the application. Should you wish to override the style for individual pages you can indicate page-specific CSS files under Advanced Options on the right hand panel with a Page selected on the canvas.
WebMaker separates the data, look-and-feel and also the structure of each page, enabling changes with minimal impact. The structure of each page is governed by an application skin, which is located under Advanced Options on the left hand panel of the Application Map. This is an XSL file with templates for each part of the page. For example, top menu, left menu, main body, logo, etc. Again, the skin only needs to be defined and included once for the whole application.
There are situations when you need to hide, show or disable certain parts of pages based on the value of other fields. Normally you would achieve this using scripting. In WebMaker this can be performed using client or server data. You have a range of options under section Visibility Details. You you choose to perform dynamic visibility using server data you will be prompted for an XPath against this field or group on the Data Bindings page, the outcome of which will determine whether to hide or show the field or group.
Conditional Styling is performed in a very similar manner to dynamic hiding and showing of fields. Under different styling sections on the Page Details tab there are options to Add Conditional Styling. For each of these that you click you will be prompted for an XPath when you visit the Data Bindings page. Again, you can construct an arbitrary XPath to determine when to apply the dynamic styles. These styles can be specified in-line or you may choose CSS class names from your CSS.
Error handling can be performed on the client and server. The server error handling mechanism needs to be designed in terms of how best to capture, manipulate and display such errors. You many find the WebMaker Design Principles document on the Hyfinity FAQ useful. Client-side validation errors can be tailored using the Error Display Details panel.You can access this by clicking the Page Details element on the left hand side of the Field Details tab.
Under Data Constraints you can tick fields that you want to designate as mandatory. To activate validation, select the field against which you have defined a submit event. You should find a Validate checkbox. Ticking this box will ensure all mandatory fields are checked before submission. You can style mandatory fields differently to make them standard out from optional fields. You can use the Mark Mandatory Fields section within the Field Details tab.
There may be occasions when you need to include and apply your own Javascript. You can do this by using the Advanced Options link on the left hand panel of the Application Map tab. The Add Javascript File link enables you to include Javascript files of your choice. To access the script you need to insert function names after selecting Action Type of Custom Script against the Event Options in the Field Details tab.
You can create pages that make asynchronous calls to server Controllers, refreshing parts of a page only. In order to achieve this, you need to use the Add Partial Page control on the palette within the Application Map tab. The development of partial pages is very similar to normal page development, whereby you can access server controller functionality, perform automatic bindings and also use schema-driven development to accelerate page composition. WebMaker hides many of the complexities of asynchronous programming, providing you with the power of AJAX using WebMaker simplicity.
Some of the key differences between full and partial pages include:
In almost all cases partial pages will be linked to from full pages. The partial pages represent a part of the full page.
Each partial page has an integrated server controller because a partial page requires a call to something to enable a refresh of the part of the full page that it is dealing with. You can access the controller details from the right hand panel of the Application Map tab. The rest of the development process is very similar to the process for developing full pages.
You may notice that the partial page previews do not show the skin of the application. This simply denotes that this partial page is part of a full page, which itself is governed by the skin.
In order to make an asynchronous call to the server from a partial page, you have to use the AJAX submission option within the Event Options section of the Field Details tab. Against this submission type you will notice the need to provide a Target Group as well as a Source Type. The target group represents the area of the screen that will be refreshed with the response from the server. You should ensure that you have a suitable container group to receive the response of the AJAX Submission. You will also notice a Source Type option. This allows you to submit a part of the full page as the request or the full page if this is more appropriate.
You may wish to use your own controls either to enhance the WebMaker controls or include new controls altogether. You can include controls from attribute-based control frameworks such as Dojo relatively easily. To do this you need to use the Page Onload Events section and the Custom Attributes section within the Field Details tab. In the Page Onload Events tab you need to enter the requires script calls to ensure the correct controls are included for use. You can access the Page Onload Events section by clicking on the top-level Page Details element on the left hand panel. By default the relevant Dojo script files are included within WebMaker, but you can include script files of your choice within the Application Map tab. Please see section on Including Javascript for more details. Once this is done you can simply include attributes by specifying their name-value pairs under the Customer Attributes section of the Field Details tab.
There may be occasions when you want to call remote services without going through the server controllers. You can achieve this using the Add Third Party Service link on the application map. This enables you to submit an action to a third party service using any of the submission methods, including AJAX and receiving a response.
Please note that because this type of call bypasses the server infrastructure, you will not have access to the bindings capability and you will also need to handle the response from the remote service within the page that makes the request. This will typically be achieved using Javascript. This type of call may typically be used for obtaining and rendering reporting-style information within parts of the full page.
When information from pages is submitted, it is received by the server Controllers. You can access and manipulate this information by using the declarative rules that are available within each controller. To access the rules for each controller use the right-click context menu on the Application Map tab or the View Controller Rules link on the right hand panel of the Application Map.
This will open up the RuleMaker tab showing the rules already created for this Controller. You may typically see a Service Call rule if you indicated a remote service call within the Application Map and you may also see a Page Display rule that typically sets the name of the next page to display. Full details, together with detailed descriptions of all server actions that can be performed using the rules mechanism are provided within the RuleMaker User Guide. Generally, you can manipulate your XML information within controllers to construct service requests, call remote services to aggregate information, cache information and also perform common XML tasks such as validations, transformations, etc.
Within the Page Structure tab you will notice different design options on the Data Source tab. Selecting the Database option will enable you to create a database connection. Once the connection is created you can navigate the various tables and field and drag and drop the schema information onto the Layout View to create WebMaker Pages.
The process of dragging and dropping RDBMS information will also create data bindings and generate default SQL statements within the rules for database access. The type of SQL statements that are generated will depend on the type of application you are trying to build. For example, reporting type applications may generate SELECT statements, whereas interactive applications may also generate UPDATE, INSERT and DELETE statements for example.
You can access RDBMS data using the SQL Statement action. Please see the SQL Statement action within the RuleMaker User Guide for more details.
Within each SQL operation you can either define new connections or reuse existing connections that have already been defined. You can also access the database connection information from the XDE Deployment screens, accessible from the Project tab.
Depending on the WebMaker version and distribution you may notice Additional links on the Data Source tab. These links will refer to other applications that have been integrated to provide design information, typically in the form of XML Schemas. You can select these applications and follow the different application-specific navigation options to select and use the resulting schemas.
Once a schema has been selected the rest of the page design process in exactly the same as for standard W3C Schemas or WSDLs.
WebMaker provides a configurable Data Source tab that can be used to integrate to external applications using custom integration adaptors. If you would like to integrate an application that can provide design information to accelerate your development, please contact Hyfinity to learn about the integration options and the necessary technical details for a successful integration.
It is possible to write Java Controllers on the server to handle client requests and produce responses. This enables Java Programmers to use Java to access other server infrastructure components such and EJBs and RDBMS, whilst retaining the advantages of fast and easy web page design. Please see later section on Writing Custom Java Controllers under Advanced Topics.
Values of almost every page element in WebMaker can be dynamically specified. This makes it possible to assign values of field labels on the server at runtime. You may wish to load translation files that map field translations before displaying pages. This is handled through the standard binding mechanism. You will be prompted for a field label binding on the Data Bindings tab for example if you select a dynamic label option on the Field Details tab. This is a possible approach for applications that require small amounts of translations for specific fields or a small collection of pages.
If complete applications are required in multiple languages then WebMaker provides a mechanism that does not require upfront developer changes to enable translations. This can be achieved by sending a language URL parameter to WebMaker. WebMaker then checks for a translation file in XML format and maps field translations before sending the page to the client. This makes it possible to make applications multi-lingual with minimal changes and becomes a configuration task. Please see the Hyfinity FAQ for more details.
WebMaker provides graceful degradation of applications wherever possible and uses a range of innovative steps to provide a very similar experience of rich applications, with accessibility requirements. You can access these options on the Page Details tab within the Accessibility Options tab.
During development, the deploy process will deploy the relevant parts of the application on to the runtime server and you should be able to preview and run applications without any separate build or packaging requirements.
WebMaker applications can be packaged for deployment to test and production servers using the Publish link within the Application Map tab. Using the Publish feature you can deploy to different platforms and server configurations and by default options for publication to Tomcat and WAR files are included. You can define your own publication files for deployments to other platforms. Please see the Project Deployment and Publication section within the XDE User Guide for more details.
You can monitor applications using the Dashboard. The Dashboard is accessed from the link on the XDE Project screen. From the Dashboard you can track the message flows as well as the Application Configuration. In runtime scenarios the platform is set to static mode and logging is set to fatal level to maximise performance and minimise system resource usage. You can tailor these settings using the Application Configuration tab. On this tab you can use the Configure Morphyc Settings button to alter the platform startup mode and the pooling options. You can also use the Platform Logging Configure button to control the logging to a fine level of detail. Please see the Administration documentation for more details.
In this section we will cover some of the advanced WebMaker concepts that typically require more developer and administrator-oriented knowledge. You will also discover facilities to extend the functionality and behaviour of the underlying XPlatform that is part of Hyfinity's Morphyc Architecture, underpinning the runtime environment of WebMaker.
The discussions in the following sections rely on a more detailed understanding of the Morphyc Architecture and we will cover only the relevant parts that concern WebMaker applications. Please consult the architecture diagram in the next section for these advanced topics.
Deployed WebMaker applications flow through the XPlatform architecture, which contains a number of key components to provide a powerful distributed environment for SOA applications. For ease of understanding the key Request and Response stages have been labelled below.
WebMaker Runtime Components and Request and Response stages:
Incoming 1 - Action Mapping. The runtime platform processing starts when the XGate servlet receives a request from a client. Upon receipt XGate will attempt to map the requested action to a server Controller using the mapping.xml file. This file is located at webapps/doc and should be maintenance free.
Incoming 2 - XGate Custom Plugin. Once an action has been mapped XGate will search for any Custom Plugins that may be defined. These are custom Java classes and described in the xgate.xml file located at webapps/doc. If custom plugins are found then the incoming request message will be sent to the plugins. Once plugins have finished processing the resulting message will be forwarded to the View node for onward processing. An example plugin may call an LDAP server to obtain security credentials and provide this information as an XML fragment for example. This information can then be used within the Controllers to restrict access to remotes services, validate against remote services, control access to page menus, etc.
Incoming 3 - Data Binding. The next step binds the incoming name-value pairs to the XML instance document if one was provided and binding was requested.
Incoming 4 - View Node. This is the first native rules-based processing node of XPlatform and should be largely maintenance-free, although it has rules capabilities just like any other Controller and its behaviour can be modified if necessary. During the incoming request leg, the View node inspects the incoming message to determine the Controller name. It then uses this to forward the message to that controller for further processing. You may notice by this stage there is a default wrapper that has been applied by WebMaker. This is applied by XGate and should not require modification. This wrapper enables you to separate WebMaker and remote service-specific header information from the data/message payload information. Any information that was not bound will appear in the /mvc:eForm/mvc:Control section of the message. The other Fields indicate the action and the target controller and also the name of the next page. The page name may be changed by the Controller on the response leg, depending on the execution outcome.
Incoming 5 - Controller Logic. Once the request message reaches the controller you can process the message using any number of native XML operations such as copying, deleting, validating, transforming, etc., You can also use the Invoke Service operation to call remote services and other Controllers. These other controllers may be custom coded. See later. For a full list of available operations please see the RuleMaker User Guide.
Incoming 6 - REST, Remote Service Security and HTTP Programming. WebMaker separates the business application from the technical plumbing required to connect together a SOA application. This includes the transport requirements for communicating with remote services. There may be occasions when you need more detailed control of the underlying HTTP communication. This can be achieved using the XGate HttpHeader fragment.
Please see later section on REST for more details.
Incoming 7 - Access Services (including Proxy node) When a WSDL is parsed WebMaker automatically sets up an Access Service for each of the services defined in the WSDL. The access service also wraps request messages, calls the remote service, processes the response and unwraps the response ready for processing on the outgoing response leg. The proxy service shown simply acts as a placeholder for the remote service address. This occurs when a node is designated as a Remote Service Proxy in the deployment screen (Please see XDE User Guide for more details). Nodes defined as Remote Service proxies have no internal structure or rules capabilities. They simply become a configuration parameter at runtime. All pre and post processing for remote service calls should be performed in the Controller and, if the change applies to all operations of the remote service such as the caching and submission of security tokens, then the Access Service rules can be modified.
Outgoing 1 - Error Checking, Unwrapping, caching, etc. When a service call returns it will typically be wrapped and may include information that needs to be sent back with subsequent requests, such as record ids and security tokens, etc. The Access Service node can be used to handle such tasks. By default, rules for Fault checking and message unwrapping are generated by WebMaker when WSDLs are imported.
Outgoing 2 - Controller Logic This presents the opportunity for processing before the information is transformed for output to the next screen or other calls are made to other services. This is also the stage when you can set the page name for the next screen. This is the page name that will be used by the View node to locate the transformation to generate the next page. At this stage you should also ensure that the XML instance that was used for the Page Display Bindings is located in the right place to enable page transformation to perform the correct bindings. If the information is missing or in the wrong format then the screen with contain blank or incorrect data and structures.
Outgoing 3 - View Node In almost all cases this stage simply transforms the data returned by the Controller using the next page name to create the next page. You can add generic rules here to redirect to an error page or perform logs, etc. if there are errors present. If a translation parameter was provided during the request then the translations will be applied at this stage.
Outgoing 4 - XGate Custom Plugin At this stage you should write the output part of Custom Plugins if you decided to use one. The response will be forwarded to the plugin before being sent to the browser.
The image below shows the default rules that form part of the View Node. The first rule is activated during the incoming request leg of the message flow. This is used to locate and forward the request to the appropriate controller. The second rule is activated on the outgoing response leg, which essentially transforms the message response from the controller to create the XHTML. The third rule is the same as the second, but accounts for language translations. The view node is just like any other controller, which means you can add your own rules here if required. For example, you may decide to check for an error fragment and respond with a different page if errors are found. This can be done by simply changing the page name.
Please see section on Message Wrappers for a description of the message fragment shown on the left. The is the default WebMaker message wrapper used to organise information between the client and the WebMaker server environment.
The image below shows the default set of rules that are generated when a WSDL is imported. The import process generates two nodes, one called the Access Service and other known as the Proxy Service. The two nodes are often collectively referred to as the Proxy Service. The proxy node simply acts as the placeholder for the URI of the remote service and contains no structure or content. The Access Service contains the rules shown on the images below.
The first rule applies the SOAP Wrapper. This is then followed by a rule for each remote service operation. Towards the bottom, there should be three further rules generated by default. The first one handles the soap Fault fragment, the second one handles a soap response with no Header fragment and the third rule handles a soap response that contains a soap Header fragment. If a soap Header is returned the the Access Service will return the whole soap envelope back to the controller, otherwise it will return the contents of the soap Body only. You can change these rules as required.
Please see section on Message Wrappers for a description of the message fragment shown on the left. The is the default SOAP message wrapper used to organise information between the WebMaker server environment and remote service calls.
In the earlier section on the View Node you will notice a message fragment on the left. This was captured during the incoming request leg of the journey. You should notice that the contacts element, containing the posted information for a GetContacts operation request has been wrapped within the /mvc:eForm/mvc:Data section. This is the default message wrapper used by WebMaker. It can be changed if required, but should not be necessary. The /mvc:eForm/mvc:Control section of the message contains non-payload control information such as the name of the requested controller, the next page name, etc. One important point to note is that WebMaker will also place unbound form elements within this section. This may be because some bindings are invalid or designed intentionally to appear in the Control section.
Within each controller and also the View Node and the Access Service nodes you have full access to the wrapped information. The main information of interest typically is the payload contained within the /mvc:eForm/mvc:Data element. Once the message has flowed through the view node and the controller to the access service, it will be re-wrapped using a SOAP Wrapper by default. This is performed by transforming the contents of the /mvc:eForm/mvc:Data into /soap:Envelope/soap:Body. This transformation is achieved using file SOAP_Wrapper.xsl. You can modify this to suit your exact soap wrapping requirements.
The reverse wrapping and unwrapping is performed during the outgoing response leg of the message flow. Essentially the /mvc:eForm wrapper is used to wrap and provide a containing element for the unstructured data captured from the client pages and also to contain WebMaker domain-specific information during execution within XPlatform. The /soap:Envelope is used for SOAP and HTTP requests to remote services. These wrappers and the mappings between them can be altered, but should not be necessary is most cases.
The Morphyc Architecture has the capability to access REST services without any traditional programming. This can be achieved using an XML fragment, which is processed at runtime to define the location and transport of the remote service. This can be achieved using the normal rules mechanism within controllers.
The main orchestration action within logicsheets is the InvokeService action. When an InvokeService action is used to call a remote service, the remote service is typically identified by a static url, which is imported using the WSDL Import feature within XDE. The default service location information can be changed during deployment using the deployment screens, but there may be situations when URLs and HTTP header information needs to be changed as well as the payload. This can be achieved from within the rules environment without having to resort to 3GL programming or requiring knowledge of any low-level HTTP libraries.
Remote web services are typically represented by proxies within XPlatform and these proxies contain the actual physical URLs, imported from WSDLs. The access services that use these proxies make an InvokeService call via XGate, which manages remote communications within XPlatform. XGate packages the service request and returns a response. XGate will use the static URL created during deployment and use this as the destination of the remote service call.
During deployment, as well as indicating whether the transport is http|soap, you can indicate whether to allow dynamic service URIs and HTTP headers to be constructed.
An HttpHeader fragment can be used to dynamically set http header attributes and direct payloads to dynamically constructed URLs. The HttpHeader fragment will typically be created in an 'access service' calling a proxy to a remote URI. This fragment should be included in the request payload.
If this dynamic option is ticked then XGate will search for the HttpHeader fragment and parse it to create a URI dynamically, set the http attributes and send the payload. The HttpHeader will be removed after the request has been sent.
The following XML fragment can be sent within the payload to change the default request packaging behaviour:
<?xml version="1.0" encoding="UTF-8"?>
<xg:HttpHeader xmlns:xg="http://www.hyfinity.com/xgate">
<xg:url action="" merge_option="replace" request_method="GET">http://anyValidUrlString</xg:url>
<xg:params>
<xg:param name="command">login</xg:param>
<xg:param name="error_dest">client</xg:param>
</xg:params>
<xg:attributes>
<xg:attribute name="HTTPHeaderAttrib1">attribute value</xg:attribute>
<xg:attribute name="HTTPHeaderAttrib2">attribute Value</xg:attribute>
</xg:attributes>
</xg:HttpHeader>
url attributes
@action - If a non-empty string value is specified then this overrides the static action specified during deployment. If an empty string value is specified then this still overrides the static action that is specified during deployment and sets the action header attribute with an empty string. If this attribute is missing then the static action value specified during deployment will be used.
@merge_option - options are replace|append. When set to replace the static url specified during deployment will be replaced by the url constructed using this HttpHeader fragment. If the append option is specified then the static url supplied will be appended with the dynamic url constructed using this HttpHeader fragment.
@request_method - This can be any string value. If a value is not supplied or an empty string is supplied then the default will be POST. This default value will only be set if a static value was not set during deployment.
The params will be appended to the URL in name=value pairs separated by "&" after a "?" has been inserted between the url and the params. e.g. http://anyValidUrlString?command=login&error_dest=client
The attributes will be set in the request http header before a request is made to the url. The name attribute indicates the name of the http header attribute and the value is the value to be set for this header attribute. IMPORTANT! - Currently only two attributes can be specified for transport type soap. These must be name 'uid' and 'pwd'.
You can supply security information for remote services that require authentication using the optional security element within the HttpHeader fragment discussed within the section on REST, remembering to enable HTTP Header processing during deployment. The presence of the fragment during an Invoke Service operation will cause WebMaker to parse this fragment and automatically negotiate the security steps for the requested service. This feature utilises the Apache HttpClient security module and it is this module that will determine how to apply the supplied security credentials based on remote service responses. If you need to customise this further you will need to write custom controllers. If this is the case then please contact Hyfinity for further support.
<?xml version="1.0" encoding="UTF-8"?>
<xg:HttpHeader xmlns:xg="http://www.hyfinity.com/xgate">
<xg:url action="" merge_option="replace" request_method="GET">http://anyValidUrlString</xg:url>
<xg:params>
<xg:param name="command">login</xg:param>
<xg:param name="error_dest">client</xg:param>
</xg:params>
<xg:attributes>
<xg:attribute name="HTTPHeaderAttrib1">attribute value</xg:attribute>
<xg:attribute name="HTTPHeaderAttrib2">attribute Value</xg:attribute>
</xg:attributes>
<security preemptive="true">
<realm>authenticatingRealmOrDomainName</realm>
<host>hostNameRequiringAuthentication</host>
<port>portOnHostRequiringAuthentication</port>
<username>String</username>
<password>String</password>
<client>nameOfClientRequestingAuthentication</client>
</security>
</xg:HttpHeader>
@preemptive - This boolean attribute will determine whether WebMaker should precompose the necessary security tokens before first invocation of the service or wait until a service has responded after first invocation, providing details of how to construct the security token. This is useful when certain secure services degrade to a lower access level when security credentials are missing. For example, some services may assume guest access if credentials are missing, thus never returning an HTTP 401 code to indicate need for authentication.
realm - Name of the realm or NT domain.
host - Name of the host requesting authentication.
port - The port number on the host requesting authentication.
username - Username.
password - Password.
client - Name of the client machine requesting authentication.
There may be occasions when you need to write your own processing engines for the server-side controllers. This could be for a number of reasons. You may need to access external Java code or utilise more efficient 3GL algorithms for certain types of processing for example. Once written, it is possible to include these custom controllers within XPlatform, just like any other native controller, providing the ability to extend the platform. This facility is always available within XPlatform, but is especially relevant if you selected the Java option against the Controller Details within the FormMaker application map.
Creating Java Controllers
You can create a Java Controller by selecting Implementation Type of Java on the right hand panel of the Application Map tab, with a Controller selected. WebMaker will generate a Java Class with the Controller name specified in the Application Map.
Managing Controller Source Code
You can organise the source code for Java Controllers by using the Java Code Location and Package Name entries under Advanced Options on the left hand panel of the Application Map.
Controller Architecture
Before we start to explore the contents of Java Controllers, it is worth recapping on the WebMaker Runtime Architecture described earlier in this section. The diagram below provides a high-level view of this architecture, focusing on the data bindings and the flow of incoming and outgoing information between client and server.
WebMaker provides the ability to bind the data within a web page in two directions. When information is submitted from the browser, an arbitrary XML document structure can be populated with the information contained within the submitted XHTML form. When a page is sent to the browser, another arbitrary XML document structure on the server can be used to bind XML fields to XHTML fields on the web page. This bi-directional binding can be performed graphically within the FormMaker Data Bindings tab. Controllers on the server handle the requests and also compose the response structures that are then transformed by WebMaker to produce the response to the browser.
XML Controllers have a range of XML operations that can manipulate the request document and also produce the response. These controllers can also call other SOAP and REST services and lookup SQL databases to compose the response.
Java Controllers provide the ability to write Java code to perform the desired tasks on the server. What you do here is dependent on your application scenario, technology standards and architecture.
Whether you are using XML or Java Controllers, the information between the client and server is bound for you. Therefore, by the time you receive the information it will be in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<mvc:eForm xmlns="http://www.hyfinity.com/xplatform" xmlns:mvc="http://www.hyfinity.com/mvc" xmlns:xg="http://www.hyfinity.com/xgate">
<mvc:Control>
<Page xmlns="http://www.hyfinity.com/mvc">ContactDetails.xsl</Page>
<Controller xmlns="http://www.hyfinity.com/mvc">mvc-Contacts-JGetContactsList-Controller</Controller>
<action xmlns="http://www.hyfinity.com/mvc">getJContactDetails</action>
<unbound_param xmlns="http://www.hyfinity.com/mvc">value</unbound_param>
</mvc:Control>
<mvc:Data>
<GetContactRequest Successful="" Version="" xmlns="http://www.hyfinity.com/schemas/tutorial" xmlns:demo="http://www.hyfinity.com/schemas">
<Contact>
<ContactId>10346</ContactId>
</Contact>
</GetContactRequest>
</mvc:Data>
</mvc:eForm>
The response format will be the same and the complete wrapped document is transformed to produce the response pages, as defined within FormMaker. Please remember that any submitted elements that failed to bind will be placed under the Control element. Let's now return to an example Java Controller generated by WebMaker:
package com.hyfinity.controller.java;
import com.hyfinity.utils.xml.XDocument;
import com.hyfinity.xplatform.JController;
import java.util.Map;
import java.io.File;
public class JGetContactsList extends JController
{
/**
* Process the request for this controller, and return the response data needed
* to display the next screen.
* @param data The bound XML data submitted from the browser.
* @param control A name to value mapping of all the other (non bound) parameters submitted.
* @param action The name of the action called from the browser.
* @return The XML data needed to show the next screen.
*/
public XDocument handleRequest(XDocument data, Map control, String action)
{
/* Set the name of the next page to display. This is the same name as specified in the Application Map tab. */
setNextPage("ContactDetails");
/* Perform processing of your choice to compose the response document. This may include calls to other
* web services, databases, etc. In this scenario, a response fragment from the Contact web service is
* being parsed from the file system to create the Data element within the WebMaker wrapper. See the tutorials
* for more background information on the contacts web services.
*/
XDocument contactDetails = new XDocument(new File("c:\\myjprojects\\example\\GetContactResponse.xml"));
/* Return the response data, which will be wrapped for us to produce the full message format that will
* be transformed to produce the next screen.
*/
return contactDetails;
}
}
Within each Java Controller, it is the handleRequest method that needs to be implemented to perform the required functionality. (In this case, it is loading in some data from a file, and returning it.)
The data incoming parameter contains the XML contents contained within the Data element in the request message. This will be the 'GetContactRequest' information given the above example message. The XDocument object provides a wrapper around a standard W3C DOM, providing some convenience functions. Please refer to the JavaDoc for more details.
The control map provides a read-only view of the unbound parameters submitted from the page, that were therefore placed into the Control section of the XML message. This maps the parameter names to their values, and given the example message above, would just contain the 'unbound_param' entry.
The final parameter just contains the name of the action that was invoked from the page. This will be one of the names defined against the links on the Application Map
When finished the method needs to return the details needed to display the page, which must be in XML format. This information will be placed within the Data element of the full wrapped XML message returned from the controller.
The following is an example of the response message that has been prepared to be sent to the browser. This response message should resemble the same structure that was used for the Page Display Bindings within the FormMaker Data Bindings tab. You should also indicate the next page information in order to enable WebMaker to identify the transform to apply to the following message to produce the next page. The JController super class provides a helper method to do this, along with other useful functions. Please see the JavaDoc for more details.
In this scenario, a response fragment from the Contact web service is being parsed from the file system to create the Data element within the WebMaker wrapper. See the tutorials for more background information on the contacts web services. You can perform processing of your choice to compose the response document. This may include calls to other web services, databases, etc.
<?xml version="1.0" encoding="UTF-8"?>
<mvc:eForm xmlns="http://www.hyfinity.com/xplatform" xmlns:mvc="http://www.hyfinity.com/mvc" xmlns:xg="http://www.hyfinity.com/xgate">
<mvc:Control>
<is_script_enabled xmlns="http://www.hyfinity.com/mvc">true</is_script_enabled>
<Page xmlns="http://www.hyfinity.com/mvc">ContactDetails.xsl</Page>
<Controller xmlns="http://www.hyfinity.com/mvc">mvc-Contacts-JGetContactsList-Controller</Controller>
<action xmlns="http://www.hyfinity.com/mvc">getJContactDetails</action>
</mvc:Control>
<mvc:Data>
<GetContactResponse Successful="true" Version="1-0" xmlns="http://www.hyfinity.com/schemas/tutorial">
<Contact ContactId="10346">
<IdentificationDetails>
<Title>Mrs</Title>
<Forename>Catherine Anne</Forename>
<Surname>Franks</Surname>
<DateOfBirth>1968-01-02</DateOfBirth>
<Gender>Indeterminate</Gender>
<HomeAddress>
<HouseNameNo>564a</HouseNameNo>
<Street>Pellington Road</Street>
<Locality/>
<Town>Chester</Town>
<CountyArea/>
<Postcode/>
<Country/>
</HomeAddress>
</IdentificationDetails>
<PersonalDetails>
<MaritalStatus>d</MaritalStatus>
<NumberOfDependants/>
<CarRegistration/>
<Notes/>
<OtherInformation/>
</PersonalDetails>
<BusinessDetails>
<OrganisationName>Burchell</OrganisationName>
<NationalInsuranceNumber/>
<TaxReference/>
<Salary/>
<PaymentFrequency>W</PaymentFrequency>
<OtherInformation/>
</BusinessDetails>
<ContactNumbers>
<EmailAddresses>
<EmailAddress Preferred="yes" Use="home">
<Email>cathy.franks@example.com</Email>
</EmailAddress>
<EmailAddress Preferred="no" Use="work">
<Email>catherine.franks@hyfinity.com</Email>
</EmailAddress>
<EmailAddress Preferred="no" Use="">
<Email/>
</EmailAddress>
</EmailAddresses>
<TelephoneNumbers>
<TelephoneNumber Preferred="yes" Use="work">
<TelCountryCode>44</TelCountryCode>
<TelNationalNumber>121 456 7890</TelNationalNumber>
</TelephoneNumber>
<TelephoneNumber Preferred="no" Use="work">
<TelCountryCode>44</TelCountryCode>
<TelNationalNumber>121 456 5432</TelNationalNumber>
</TelephoneNumber>
<TelephoneNumber Preferred="no" Use="">
<TelCountryCode/>
<TelNationalNumber/>
</TelephoneNumber>
</TelephoneNumbers>
<FaxNumbers>
<FaxNumber Preferred="no" Use="">
<FaxCountryCode/>
<FaxNationalNumber/>
</FaxNumber>
<FaxNumber Preferred="no" Use="">
<FaxCountryCode/>
<FaxNationalNumber/>
</FaxNumber>
<FaxNumber Preferred="no" Use="">
<FaxCountryCode/>
<FaxNationalNumber/>
</FaxNumber>
</FaxNumbers>
</ContactNumbers>
</Contact>
</GetContactResponse>
</mvc:Data>
</mvc:eForm>
Compiling and Running Java Controllers
You can use a Java Development tool of your choice to author and compile the Java classes for each controller. You will need to ensure that the xplatform.jar file is on your classpath for the code to compile successfully. This jar is located within the c:\jprogramfiles\hyfinity\design\tomcat-design\common\lib directory of a standard WebMaker installation.
Once compiled, you can place the class within the J2EE container deployment path. For the default WebMaker installation and Example project this will reside in the directory c:\jprogramfiles\hyfinity\runtime\tomcat-runtime\webapps\Example\WEB-INF\classes. Please remember to use the full named package structure. Alternatively you can place your compiled classes within a JAR file in the jars directory as you would with any other Java web application.
Java docs
You can locate the Java docs under the documentation folder, which is located in c:\jprogramfiles\hyfinity\design\tomcat-design\webapps\documentation for the default installation. Alternatively, use the following link for the JController java doc.
If deployed correctly, you should be able to use the Runtime Dashboard to view the message flows in exactly the same way as for XML Controllers. This will also show the details of any errors if you Java Controller could not be found or called for any reason.
It is possible to process the incoming HTTP request before it reaches XPlatform and also to post-process the response after XPlatform processing has completed. You can utilise this feature in numerous scenarios. For example, you may wish to access LDAP information and insert a security fragment within the request message for example. Please contact Hyfinity for the API Javadocs if you need to develop Custom Plugins.