When installing MVC WebMaker, the installer should detect your existing installation, and you will be given the option to migrate your existing projects across to the new version.
If you wish to keep your existing projects it is important that this "migrate" option remains selected.
Then, during the installation process your old projects will be exported from the existing installation, and then imported into the new install. All the underlying project metadata will be automatically updated as needed depending on the version.
IMPORTANT: From version 3.1.2 all the Hyfinity webapp resources (css, javascript and images) will be automatically replaced within each project that is imported into the studio. If any of these files were changed in a project, then you will need to extract the changes and apply them to new project specific files. There is an FAQ on "overriding styling best practices".
When installing a Hyfinity WebMaker major release (v3, v3.1), you will be asked to select the licence file that should be used for the new installation. Minor update versions (v3.1.1, v3.1.2) do not require a new license key file.
If an existing installation has been detected, then it will default to using the licence key from that version, but it is very important that you select a licence file that is valid for the version being installed. Otherwise the project import step will fail and if you have selected to uninstall your existing version then your projects could be lost.
You should now be able to successfully deploy and run your existing applications.
There may however be some additional manual steps required, as detailed below if you are continuing to develop and extend projects. These are particularly important if you wish to make any changes to your project using the new releases capabilities.
STEP 1(a) - Updating 'Shared' Webapp Resources
Note: This step is only required to be performed if WebApp Resources have been setup to be shared across multiple projects. Most installations are not configured in this manner.
From MVC WebMaker 3.1 all the webapp resources (CSS files, JavaScript files, images, etc) are now included in the repository for each particular project, rather than in a separate location under Tomcat. When your existing projects are imported the webapp information will automatically be placed in the new location in the repository.
If your application consists of a number of projects that should share these resources, then you will now have a separate copy for each project. To resolve this, you may need to manually delete the 'webapp' directory in the repository for all the projects that do not need it, and then update the 'Preview' settings on the Application Map screen for these projects to point to the 'webapp' directory in the project that contains the master set
STEP 1(b) - Updating 'Project' Webapp Resources
Note: This step is required for standard projects not covered by 'shared' projects mentioned above.
Note: This step is not required for version 3.1.2 onwards. Step 2 is not required either - Jump to Step 3.
This step should only be performed if you are 100% sure that no Hyfinity WebMaker files have been changed. We would recommend as a minimum taking a backup of the project webapp directories, ideally comparing files to ensure changes have not been made to the hyfinity files.
If your projects have NOT altered any of the css, images or javascript (js) files that are shipped with Hyfinity software, then the three 'webapp' directories can be copied & replaced from the generic directory to your project directory.
This can be done by copying the three directories from the \design\repository\generic\mvc\generic\webapp directory into the specific directory for each of your projects. For example, if your project is called 'Example', and is under the 'mvcuser' workspace (previously known as user), then you will copy these files to the \design\repository\mvcuser\mvc\Example\webapp directory.
STEP 2(a) - Updated CSS and Image Files
Note: This step should be considered carefully if Step 1(b) has not been undertaken. We would recommend that this step is performed unless you do not intend to edit/develop the project further. However, there can be adverse impact of introducing the revised CSS.
Each WebMaker application makes use of a CSS and image files. If the standard Hyfinity versions are used, then the files can be replaced. If they are not, then the user will need to undertake an comparison and merging of changes. Great care should be taken if this approach is to be adopted. We would generally advise taking the new CSS and applying your specific changes to the old version, to the new version.
The following are some issues that may occur on web pages by using the new CSS for pages:
STEP 2(b) - Updated Palette Templates
If any of the following 'Composite Controls' have been used in a project then the content of the respective palette control resources will need to be copied across to the project webapp.
The appropriate palette Template resource directories will need to be copied from: \design\repository\generic\mvc\generic\paletteTemplates\...\ directory into the specific directory for each of your projects. For example, if your project is called 'Example', and is under the 'mvcuser' workspace (previously known as user), then you will copy these files to the \design\repository\mvcuser\mvc\Example\webapp directory.
STEP 2(c) - Updated JavaScript Files
Note: This step should be performed if the Step 1(b) has not been undertaken. We would recommend that this step is performed unless you do not intend to edit the project.
Each WebMaker application makes use of a set of JavaScript files to provide client side validation and other functionality. These scripts are often updated for each new release, and when using FormMaker, the pages will always be generated in accordance with the latest versions. Therefore you need to place the latest versions of these files into your project.
This can be done by copying every file from the \design\repository\generic\mvc\generic\webapp\js directory into the specific directory for each of your projects. For example, if your project is called 'Example', and is under the 'mvcuser' workspace (previously known as user), then you will copy these files to the \design\repository\mvcuser\mvc\Example\webapp\js directory.
Please note, that if you have made any changes to the Hyfinity supplied script files, then you will manually have to make these changes to the new versions, which is why we always recommend placing your script functions in separate files.
STEP 2(d) - Updated Dojo Version
Note: This step should be performed if the Step 1(b) has not been undertaken. We would recommend that this step is performed unless you do not intend to edit the project.
The version of the dojo toolkit provided with each WebMaker release is updated to match the latest version available. If the javascript files have been upgraded as a defined above, then the latest version of the 'dojo' directory will have been copied to your specific project webapp (within the repository) from: \design\repository\generic\mvc\generic\webapp\js\dojo
If you have made use of any other dojo dijit controls in your custom JavaScript functions, then please consult the Dojo website for details of any API changes that you may need to be aware of.
Note: Any of the dojo controls implemented within the palette controls for Version 3.1.* should be OK.
Note: Version 3.1.1 of WebMaker uses Dojo Version 1.3.1.
Note: Version 3.1.2 of WebMaker uses Dojo Version 1.5.0.
STEP 3(a) - Updated Skin and Script Includes
Note: This step is required for those upgrading to Version 3.1.1, but not if upgrading Version 3.1.1. to 3.1.2.
It is possible for there to be additional script files included in the new release, or the names to be adjusted. Therefore we would always recommend updating the scripts section of your skin file.
The 'demo_skin.xsl' file included in the \design\repository\generic\mvc\generic\XSL_pool directory will always contain the updated list. You should copy the details from the 'global_scripts' template and ensure these script tags are included in the same order in your specific project skin.
However, if you are using the demo_skin.xsl in your project, then this file will need to be replaced if it has not been changed. If it has been changed you will need to manually compare and incorporate the necessary changes.
STEP 3(b) - Updated Function Names
Note: This step is only required if upgrading from a version earlier than 3.1.
For WebMaker Version 3.1 the names of the script functions previously available have been updated. If you make use of any of these in your project you will have to update your code accordingly. These functions are now all contained within the hyf namespace to prevent the possibility of conflicts with any third party script functions.
Old Format New Format
WebMaker 3.1.1 introduced a number of helpful functions for making use of the built in validation capabilities. For more details please search for "validation"
STEP 4 - SQL Statement Changes
Note: This step is only required if upgrading from a version earlier than 3.1.
For WebMaker Version 3.1 the handling of SQL Statement actions has been changed slightly. Previously all successful statements were automatically committed, where as now you have to manually add a commit statement where needed to store your changes.
Any uncommitted changes will be rolled back when a set of rules have finished executing.
If you wish to keep your existing projects it is important that this "migrate" option remains selected.
Then, during the installation process your old projects will be exported from the existing installation, and then imported into the new install. All the underlying project metadata will be automatically updated as needed depending on the version.
IMPORTANT: From version 3.1.2 all the Hyfinity webapp resources (css, javascript and images) will be automatically replaced within each project that is imported into the studio. If any of these files were changed in a project, then you will need to extract the changes and apply them to new project specific files. There is an FAQ on "overriding styling best practices".
When installing a Hyfinity WebMaker major release (v3, v3.1), you will be asked to select the licence file that should be used for the new installation. Minor update versions (v3.1.1, v3.1.2) do not require a new license key file.
If an existing installation has been detected, then it will default to using the licence key from that version, but it is very important that you select a licence file that is valid for the version being installed. Otherwise the project import step will fail and if you have selected to uninstall your existing version then your projects could be lost.
You should now be able to successfully deploy and run your existing applications.
There may however be some additional manual steps required, as detailed below if you are continuing to develop and extend projects. These are particularly important if you wish to make any changes to your project using the new releases capabilities.
STEP 1(a) - Updating 'Shared' Webapp Resources
Note: This step is only required to be performed if WebApp Resources have been setup to be shared across multiple projects. Most installations are not configured in this manner.
From MVC WebMaker 3.1 all the webapp resources (CSS files, JavaScript files, images, etc) are now included in the repository for each particular project, rather than in a separate location under Tomcat. When your existing projects are imported the webapp information will automatically be placed in the new location in the repository.
If your application consists of a number of projects that should share these resources, then you will now have a separate copy for each project. To resolve this, you may need to manually delete the 'webapp' directory in the repository for all the projects that do not need it, and then update the 'Preview' settings on the Application Map screen for these projects to point to the 'webapp' directory in the project that contains the master set
STEP 1(b) - Updating 'Project' Webapp Resources
Note: This step is required for standard projects not covered by 'shared' projects mentioned above.
Note: This step is not required for version 3.1.2 onwards. Step 2 is not required either - Jump to Step 3.
This step should only be performed if you are 100% sure that no Hyfinity WebMaker files have been changed. We would recommend as a minimum taking a backup of the project webapp directories, ideally comparing files to ensure changes have not been made to the hyfinity files.
If your projects have NOT altered any of the css, images or javascript (js) files that are shipped with Hyfinity software, then the three 'webapp' directories can be copied & replaced from the generic directory to your project directory.
This can be done by copying the three directories from the \design\repository\generic\mvc\generic\webapp directory into the specific directory for each of your projects. For example, if your project is called 'Example', and is under the 'mvcuser' workspace (previously known as user), then you will copy these files to the \design\repository\mvcuser\mvc\Example\webapp directory.
STEP 2(a) - Updated CSS and Image Files
Note: This step should be considered carefully if Step 1(b) has not been undertaken. We would recommend that this step is performed unless you do not intend to edit/develop the project further. However, there can be adverse impact of introducing the revised CSS.
Each WebMaker application makes use of a CSS and image files. If the standard Hyfinity versions are used, then the files can be replaced. If they are not, then the user will need to undertake an comparison and merging of changes. Great care should be taken if this approach is to be adopted. We would generally advise taking the new CSS and applying your specific changes to the old version, to the new version.
The following are some issues that may occur on web pages by using the new CSS for pages:
- Label Background Container - With the introduction if +?+?++labelBackground+?+?+? and +?+?++groupLabelBackground+?+?+? containers for fields and Groups respectively, some previous layouts will have used 'css overrides' to try and mitigate limitations in styling control. It is likely that widths applied to label style overrides will need to be moved to labelBackground style overrides. If widths of 100% have been applied to overrides for the field defaultBackground, then they should be removed. These types of change are more likely if the user has used Grids to control layout rather than the more naturally dynamic vertical and horizontal groups. Controlling label and field widths should be applied to the 'background' container styles.[/*]
- Layout of labels and fields - Previously some fields had slightly different margin/padding layout depending whether they were in Vertical, Tables, Grids, etc. We have made this more consistent, but it does mean some look like they are spaced out more than the previous version.[/*]
- Force Table Layout - If a group had 'Force Table layout' checked, then a gray line border will not appear with the new CSS. If the border is still required, the user should append a further style name of 'outline' to the group style. [/*]
STEP 2(b) - Updated Palette Templates
If any of the following 'Composite Controls' have been used in a project then the content of the respective palette control resources will need to be copied across to the project webapp.
The appropriate palette Template resource directories will need to be copied from: \design\repository\generic\mvc\generic\paletteTemplates\...\ directory into the specific directory for each of your projects. For example, if your project is called 'Example', and is under the 'mvcuser' workspace (previously known as user), then you will copy these files to the \design\repository\mvcuser\mvc\Example\webapp directory.
- Editable Row - The 'EditableTable_resources' directory content (css, images, js) should be copied to the project webapp directory.[/*]
- Paging Table - The 'PagingTable_resources' directory content (css, images, js) should be copied to the project webapp directory. [/*]
- ResizablePanel - The 'ResizablwPanel_resources' directory content (css, images, js) should be copied to the project webapp directory.[/*]
- Treeview - The 'Treeview_resources' directory content (css, images, js) should be copied to the project webapp directory.[/*]
STEP 2(c) - Updated JavaScript Files
Note: This step should be performed if the Step 1(b) has not been undertaken. We would recommend that this step is performed unless you do not intend to edit the project.
Each WebMaker application makes use of a set of JavaScript files to provide client side validation and other functionality. These scripts are often updated for each new release, and when using FormMaker, the pages will always be generated in accordance with the latest versions. Therefore you need to place the latest versions of these files into your project.
This can be done by copying every file from the \design\repository\generic\mvc\generic\webapp\js directory into the specific directory for each of your projects. For example, if your project is called 'Example', and is under the 'mvcuser' workspace (previously known as user), then you will copy these files to the \design\repository\mvcuser\mvc\Example\webapp\js directory.
Please note, that if you have made any changes to the Hyfinity supplied script files, then you will manually have to make these changes to the new versions, which is why we always recommend placing your script functions in separate files.
STEP 2(d) - Updated Dojo Version
Note: This step should be performed if the Step 1(b) has not been undertaken. We would recommend that this step is performed unless you do not intend to edit the project.
The version of the dojo toolkit provided with each WebMaker release is updated to match the latest version available. If the javascript files have been upgraded as a defined above, then the latest version of the 'dojo' directory will have been copied to your specific project webapp (within the repository) from: \design\repository\generic\mvc\generic\webapp\js\dojo
If you have made use of any other dojo dijit controls in your custom JavaScript functions, then please consult the Dojo website for details of any API changes that you may need to be aware of.
Note: Any of the dojo controls implemented within the palette controls for Version 3.1.* should be OK.
Note: Version 3.1.1 of WebMaker uses Dojo Version 1.3.1.
Note: Version 3.1.2 of WebMaker uses Dojo Version 1.5.0.
STEP 3(a) - Updated Skin and Script Includes
Note: This step is required for those upgrading to Version 3.1.1, but not if upgrading Version 3.1.1. to 3.1.2.
It is possible for there to be additional script files included in the new release, or the names to be adjusted. Therefore we would always recommend updating the scripts section of your skin file.
The 'demo_skin.xsl' file included in the \design\repository\generic\mvc\generic\XSL_pool directory will always contain the updated list. You should copy the details from the 'global_scripts' template and ensure these script tags are included in the same order in your specific project skin.
However, if you are using the demo_skin.xsl in your project, then this file will need to be replaced if it has not been changed. If it has been changed you will need to manually compare and incorporate the necessary changes.
STEP 3(b) - Updated Function Names
Note: This step is only required if upgrading from a version earlier than 3.1.
For WebMaker Version 3.1 the names of the script functions previously available have been updated. If you make use of any of these in your project you will have to update your code accordingly. These functions are now all contained within the hyf namespace to prevent the possibility of conflicts with any third party script functions.
Old Format New Format
| [tr][td]submitForm(validate)[/td] | |
| [td]hyf.FMAction.handleFormSubmission({value: action} | {value: validate}); |
| If you do not want to specify an action (as was previously the case): | |
| hyf.FMAction.handleFormSubmission(null | {value: validate});[/td] |
| [/tr] | |
| [tr] | |
| [td]findErrors()[/td] | |
| [td]hyf.FMAction.getFormValidator().checkForm();[/td] | |
| [/tr] | |
| [tr] | |
| [td]showErrors(errors)[/td] | |
| [td]hyf.FMAction.getErrorDisplay().resetDisplay(); | |
| hyf.FMAction.getErrorDisplay().showErrors(errors);[/td] | |
| [/tr] | |
| [tr] | |
| [td]validateForm()[/td] | |
| [td]hyf.FMAction.getErrorDisplay().resetDisplay() | |
| var errors = hyf.FMAction.getFormValidator().checkForm(); | |
| hyf.FMAction.getErrorDisplay().showErrors(errors);[/td] | |
| [/tr] |
WebMaker 3.1.1 introduced a number of helpful functions for making use of the built in validation capabilities. For more details please search for "validation"
STEP 4 - SQL Statement Changes
Note: This step is only required if upgrading from a version earlier than 3.1.
For WebMaker Version 3.1 the handling of SQL Statement actions has been changed slightly. Previously all successful statements were automatically committed, where as now you have to manually add a commit statement where needed to store your changes.
Any uncommitted changes will be rolled back when a set of rules have finished executing.