Upgrading kiwitrees

Kiwitrees will need upgrading 4 to 6 times each year.

Upgrade kiwitrees

The standard way to upgrade kiwitrees to a new version is very simple. You should upgrade whenever a new version is made available. Even minor kiwitrees version updates usually contain a significant number of bug fixes as well as interface improvements and program enhancements. Registered users will be notified whenever an update is available.

  1. As a precaution, it is always a good idea to back up your kiwitrees database before proceeding with an upgrade. A useful tool to simplify this process is the kiwitrees module “Database backup“.
  2. Download the latest version of kiwitrees available from here.
  3. While you are in the middle of uploading the new files a visitor to your site would encounter a mixture of new and old files. This could cause unpredictable behaviour or errors. To prevent this put your site into “maintenance mode”. Go to Administration > Site administration > Site configuration, tick ‘yes’ by Site maintenance and save. While you continue with the next step, leave your browser open at that page.
  4. Unpack the ZIP file on your desktop computer, and upload all the files to your web server, overwriting the existing files.
  5. When everything has been copied (and do check this as some FTP software can miss a few files) go back to your open browser tab (from 3. above) and click on Dashboard > Home. This is an important step in most upgrades and should be done before you disable the site maintenance setting. Most upgrades will include automatically deleting old files, and some will need database changes. These are triggered by visiting the dashboard home page. This will generally take less than one second.
  6. Now you can check your site is still working correctly. Review the main pages and look for anything obviously wrong. Take special note of any changes or new additions described on this site and our news letter/email and see if any of those need configuring.
  7. Once you are happy the upgrade is OK, return to Administration > Site administration > Site configuration, tick ‘no’ by Site maintenance and save. Your users can now access the site and enjoy the new features!
GENERAL NOTE: Depending on the changes in the new files, your browser configuration and possibly other factors, it is always wise to clear both the kiwitrees cache and your browser cache immediately after the upgrade is completed. The kiwitrees cache can be cleared simply by going to Administration > Site administration > Clean up data directory and deleting the cache.

NOTE for anyone using custom code (modules, themes, etc. not supplied in the kiwitrees download package). It is very likely your custom code will not work when you upgrade kiwitrees. Therefore you should disable all custom code before you apply the upgrade. Disable custom modules, switch over to a standard theme, and remove any code “hacks”. Once the upgrade is complete and you are satisfied your site is fully operational contact the source of those modules or themes for a new version.

NOTE for Macintosh users. Step 4 assumes you are using a copy tool that merges directories rather than replaces them. (Merge is standard behaviour on Windows and Linux.) If you use the Macintosh Finder or another similar tool to perform step 3, it will replace your configuration, media and other directories with the empty/default ones from the installation. This would be very bad (but you did take a backup in step 1, didn’t you!). Further details and recommendations for suitable tools can be found by searching google.com

Version specific upgrade instructions

There are no special requirements if you are upgrading from any version in the 3 series. Just follow the steps above. But if you are upgrading from a version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

Useful information

  1. This version has a complete upgrade to the messaging system, including the removal of the internal messaging system. As part of the upgrade, the system will change any user’s accounts set to use “Kiwitrees uses internal messaging” to “Kiwitrees sends emails”.
  2. Any messages previously stored in the internal messaging system will NOT be deleted. They remain in the same “xxx_message” table of your database, but will no longer be accessible other than by directly accessing the database. You can choose whether to retain or delete that table at any time.
  3. Changes to the census assistant may result in some minor changes to the way existing census transcriptions (shared notes) are displayed compared to new ones. If you prefer to change the old ones to match the new that can be done in most cases using the Batch update (search and replace) tool. This includes the more significant change for the UK 1939 Register from RESI tags to CENS tags.

*WARNING*

This upgrade will DELETE the complete folder “kiwitrees/modules_v3” that was rendered obsolete at the earlier (3.3.0) upgrade if you haven’t already removed it manually. Before you start this upgrade you MUST ensure any files or data you need to keep or transfer to the new folder “kiwitrees/modules_v4” are moved out of modules_v3, or backed up in some way.

Examples of such files could include images uploaded using the WYSIWYG editor (the ckeditor module) and stored in its uploads folder (“modules_V3/ckeditor/kcfinder/uploads/image“); custom copies of standard modules; or your own custom modules.

Version 3.3.0 includes many more changes than any other recent upgrade. As a result, the upgrade process is a little more complex than usual and includes a complete replacement of all modules, in a new “modules_v4” folder. The old “modules_v3” is not removed in this process so you will not accidentally lose any customisations. It will be removed at the next upgrade though. Before starting it is more important than ever that you read and follow the general upgrade instructions above and also note carefully the following additional considerations.

  • Minimum requirements for kiwitrees have changed. The minimum version of PHP is now 5.6.0, and the maximum is 7.0. PHP 7.1 is not yet fully tested. Version earlier than 5.6 “might” work OK but cannot be guaranteed, and cannot be supported. If you need to change your version of PHP, do so before you upgrade, but AFTER you switch your site to “maintenance mode”. This will prevent your users (and search engines)  from experiencing fatal errors they do not understand.
  • If you have any custom modules (in the folder “modules_v3”) these can be safely left there until later in the process. The upgrade process will NOT lose the data stored for such modules. It will still be there when you put the modules back later.
  • It is ABSOLUTELY ESSENTIAL that if you use any custom theme files (mystyle.css, myheader.php, mytheme.php, myfooter.php) or any other custom files (other than complete modules) of any kind,  these files are REMOVED BEFORE you start the upgrade process. If you miss any, you will get a fatal error “403 ACCESS FORBIDDEN” when you try to re-start your upgraded site.
  • Now you can safely proceed with the upgrade as described in points one to seven above.
  • Once your site upgrade finishes do not forget to
    • clear and refresh your browser cache (so any display style changes are actioned)
    • review your Administration > Modules > Manage modules list and delete the ones highlighted in red (Click on the red text to delete). These are modules no longer required, and this time there will be a large number of them! BUT DO NOT DO THIS UNTIL YOU ARE ABSOLUTELY SURE ALL PAGES ARE WORKING CORRECTLY.
    • while reviewing the modules list, check that the ones you need are all enabled. It is likely that the new and replaced  “Report” modules will need to be enabled
    • unset “Maintenance mode”
  • Once your site is back up and running correctly, but still without your custom modules and files, you can proceed to make a simple change to your customisations, then re-instate the files.
    • In each file near the top, just below the copyright statement, look for a block of code like
      if (!defined('WT_WEBTREES')) {
      header('HTTP/1.0 403 Forbidden');
      exit;
      }

      Simply change “WT_WEBTREES” to “WT_KIWITREES”, save your file, and upload it back to its original location.

    • For your custom modules, the change is the same but you will probably only find that section of code in files named “module.php”. Once that change is made copy your custom module(s) to the new “modules_v4” folder.
  • If you have transferred all custom modules or had none, and you are satisfied your site is working OK, you may now (optionally) remove the no-longer used “modules_v3” folder and all its contents. If you don’t feel any need to remove it now, it will be automatically removed as part of the next upgrade in a couple of months time.

The upgrade to 3.2.3 from 3.2.2 should be quite straightforward. However there are some NEW options which will make the upgrade even smoother than before, so I do recommend you read the general upgrade instructions (above) carefully before you start. By that I mean read the top section of this page and follow the NEW steps carefully. These are different to the steps you would have read for earlier upgrades.

If you are upgrading from any version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

The upgrade to 3.2.2 should be straightforward with no special actions required.

After the upgrade to 3.2.2 you should review your menu settings for charts and lists. These can now be configured to restrict access to different member roles. If you use the “Research links” sidebar module you will also need to reset your list of preferred links for that.

  • First visit Administration > Modules > Manage modules and ensure the charts and lists you want to use are all enabled. You can simplify this process by clicking on the table headers to sort each type to the top of the list.
  • Then visit Administration > Modules > Charts and Administration > Modules > Lists in turn to set your preferred access restrictions for each menu item.
  • To reset links for the “Research links” module visit it;s configuration screen at Administration > Tools > Research links select the links you want and click “save”.

If you are upgrading from any version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

There are no special requirements if you are upgrading from any version later than 3.0.0. but you are likely to find initially that you have no menus displayed. To fix this login (if necessary set your browser URL to your-domain/login.php to do this), and visit the administration pages. Just visiting there is sufficient to complete the upgrade process and allow the menus to display normally again. If you cannot access log in at all, simply delete the folder /modules_v3/menu_calendar/ from your server. That is the one causing this issue.

After upgrading from any version to 3.2.1 there are two changes you need to be aware of:

  • The “Calendar” menu item no longer exists. Its sub-menu items have been moved to the “Lists” menu group, and the Day, Month, Year alternative displays combined into a single page. This is a) in preparation for making all menu sub-items fully configurable (next release), and b) to reduce the growing number of main menu items.
  • The group of edit links at the base of the Families tab of individual’s pages have been moved to the main menu Edit drop-down group. This makes these edit options available from ANY of the Individual page tabs and is more consistent with the general use of the “Edit” main menu item throughout the system.

Examples of these changes can be seen on the “Changes” list page.

There are no special requirements if you are upgrading from any version later than 3.0.0

If you are upgrading from any version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

After upgrading from any version to 3.2.0 there are a couple of things to be aware of:

  • The changes affect a lot of files, and all the themes, So it is even more important this time that you thoroughly clear your browser cache before trying to use your site after the upgrade. If you see anything that doesn’t “look right”, it will almost always mean you need to clear that cache 🙂
  • Like most new modules on existing sites, the new Resources menu is not enabled automatically. Details for setting it up are on the Resource menu FAQ page, in the paragraph titled “Configuration”.
  • Two modules, the Changes report and the Individual report are removed in this version (replaced by new versions under “Resources”). In Administration > Modules > Manage modules you will see beside each of these the red warning: “This module cannot be found. Delete its configuration settings.” Click on that text to complete the remove of these modules.
  • You should read the blog post about the new tabbed edit screens before using your upgraded site, so as not to be too surprised at this very different operation.
  • You may want to review the Research links configuration (Administration > Tools > Research links) if you have it enabled. At least one new link has been added. You will need to enable it here if you want to use it. Perhaps a good time to review your list of links anyway)

There are no special requirements if you are upgrading from 3.1.0 or even 3.0.0. But if you are upgrading from any version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

Some users have reported seeing an error message like this immediately after the upgrade, either on screen (if PHP error reporting is enabled on your server) or in the kiwitrees error log):

Notice: Undefined index: characterOrder in /xxxxxxxxxxxxxxxx/kiwitrees/library/WT/I18N.php on line 276

This is a temporary error that can either:

  1. be ignored. It will disappear when the kiwitrees cache is updated (roughly every two hours), or
  2. you can clear it by deleting the cache. Go to Administration > Clean up data folder > delete the “cache” folder, then refresh your browser window.

There are no special requirements in this case. But if you are upgrading from any version earlier than 3.0.0, then you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

Kiwitrees 3.0.0 is a major update including a number of changes that affect the way you have viewed and managed your site. The basic upgrade process is exactly the same as normal (see above), but once completed there are a couple of additional steps and some possible issues to be aware of. This is not a complete list of changes, just those that might cause concern during the upgrade. The full change list is available here.

  1. If your site includes any custom or old un-modified modules, these may cause a fatal error with a message like
    Fatal error: Class XXXXXXX_WT_Module contains 1 abstract method and must therefore be declared abstract or implement the remaining methods (WT_Module_Menu::MenuType) in /var/www/vhosts/YOUR-DOMAIN/httpdocs/modules_v3/XXXXXX/module.php on line XXX
    
    Fatal error: Call to a member function getClientIp() on a non-object in /var/www/vhostsYOUR-DOMAIN/includes/session.php(328) : runtime-created function on line 1 

    This is because all modules that create menu items now require a simple statement describing the ‘type’ of menu they are. The options are ‘main’ for the main header menu and ‘other’ for the smaller menu group containing ‘languages, favourites, login, etc.. To fix these errors you just need to add the following code, using either ‘main’ or ‘other’, into the module.php file of the offending module(s):

    // Implement WT_Module_Menu
    public function MenuType() {
    	return 'main';
    } 
  2. Some users have found that after the upgrade they have no menu items at all, and no link to login or reach the administration area. If this happens to you try one or both of these URL’s:
    1. your domain/admin.php If you are logged in this will get you straight to the administration screens.
    2. your domain/login.php This will get you to the login page. Once logged in you can use 1 (above) to access the administration pages

    Once you reach the administration pages use Administration > Modules > Manage modules to enable the menus you require, and Administration > Modules > Menus to give them the correct access levels and positions along the menu bar(s). You might find it useful to initially enable ALL modules, then disable any you subsequently decide not to use.

  3. The greatest change in this version is the complete removal of “My page”. This has involved some re-location of menu items. Ones like “My account, My individual record, Logout, and Administration” that used be part of the My page menu can now be found under your name in the top or ‘other’  menu  group.
    upgrade - admin-access

    click to enlarge

  4. Also resulting from the removal of “My page” is the introduction of it’s replacement, the “widget bar”. This new feature appears on all pages except the “Home” page when users are logged in. It is displayed or hidden by using a new button on the left-end of the main menu. It’s content is managed by users with the role family tree manager or site administrator from the administration pages.
    upgrade - widget

    click to enlarge

    When you first upgrade you will not see this feature until you have set it up. That requires the following steps:

    1. Go to Administration > Modules > Manage modules
    2. Click on the column header “Widgets” twice to bring all the new widget modules to the top of the list. These are the same ones previously available on My page except for a couple not suitable for a side bar (like “charts”).
      upgrade - widget-enable

      click to enlarge

    3. Tick “enable” for each of these you want to use. It is not advisable to try and use too many as they are positioned in a single vertical column which would become unmanageable. Just select perhaps four or five that provide the information you regularly use. Save your selection
    4. Note that the above list of widgets includes one new module called “Quick links”. At present this contains links to My account, My pedigree, My individual record, and Administration.It is recommended (but not compulsory) you include this in your widget bar for convenient navigation. I hope in future to expand the use of this to allow any link to be added to or removed from this module, in much the same way as favourites are added and removed.
    5. Now go to Administration > Modules > Widgets. Here you can refine the access level of each widget, and change their display order (move them up or down). Complete these setting by clicking ‘save’.
  5. A number of themes have been removed from this release following a user survey regarding which were popular and used. The removed ones are Clouds, FAB, Minimal, and Simpl_grey. If you or your users had any of these set as their default they will revert to the kiwitrees theme. This can be changed at Administration > Family trees > your family tree > Theme tab.
  6. The use of themes has been simplified. It is no longer possible for individual users to set their own tree, nor is there any site default theme. There is now only a single place to select a theme to be used for each family tree: Administration > Family trees > your family tree > Theme tab ( or the widget module “Theme select” which does the same thing). If that is not set the display will default to the kiwitrees theme.
    upgrade - theme_select

    click to enlarge

  7. Simpl_menu2. This add-on has now been included in the core code under the module name “extra menus”. The old module will still work, but only if you first amend it’s module.php as described in point 1.(Fatal error) above. However, you are recommended to transfer your simpl_menu2 settings across to the new module to avoid future upgrade complications. The change of module name does ensure your settings will be intact after the upgrade, so you only need to copy them to the new module within the administration pages. Then you can physically delete the old module from your server.
  8. Once all of the above is completed you are likely to have a number of modules appearing in the Administration > Modules > Manage modules list with the warning “This module cannot be found. Delete its configuration settings”. Once you are satisfied any settings you need to copy have been done click on that warning to complete the removal of the old module from your system.

There are no special requirements in these cases.

If you want to upgrade from any version of webtrees older than 1.4.4 the instructions are the same with one key exception. Before upgrading delete ALL the contents of the folder /modules_V3/ckeditor/. This is to accommodate the different file structure of this latest version of the CKEditor WYSIWYG editor. This is not necessary if upgrading from kiwitrees 1.4.4.0, or webtrees 1.4.5.

If you have already upgraded to webtrees 1.5, 1.6, or 1.7 series and want move to kiwitrees you will need to make changes to the database structure. If you need help with this please contact me.

 



Have your say!

Have your say!