ZIKULA UPGRADE INSTRUCTIONS
===========================

Support and help with upgrading to this version can be obtained from the
forums at http://community.zikula.org/


Server Consideration
--------------------

- Zikula requires PHP 5.3.2 or greater.

- Please make sure the php.ini file has date.timezone set to a valid timezone 
  like UTC, GMT+5, Europe/Berlin.  If this is not set, Zikula will not function
  correctly.

- Ensure your server has PCRE with unicode support enabled.


Requirements
------------

This upgrade can only be performed on a Zikula Core 1.2.x installation.  If you
are on a lower version, you must first upgrade sucessfully before proceeding to
this upgrade.


Before you upgrade
------------------

There are several issues to contend with before you begin the upgrade process. These
are things that must be performed on your working 1.2.x installation before unpacking
the upgrade files.

Theme naming considerations
---------------------------
   Themes must start with a capital letter and must not contain an underscore character _
   If you need to rename your theme, please follow the following steps:

  - Change your theme to different theme in Zikula's administation.

  - Rename your theme folder with a capital letter.  If you are on a Windows machine,
    please note that Windows does not care about casing so you have to first
    rename the folder in two steps like this:

         mytheme => mythemeX

    and then

         mythemeX => MyTheme

    If you are on a linux or mac system, you can rename directly.

  - Edit the version.php of the theme to reflect the new name.

  - Switch back to your theme and make any adjustments to your site as necessary.


Module considerations
---------------------

  Make sure all your modules are compatible with Zikula 1.2.x and have been completely
  converted to 'Gettext'.  Modules that are not will not function in Zikula 1.3.

  Zikula 1.2.x compliant modules will work in Zikula Core 1.3.x

  If you use 'menutree', please delete the module files entirely as the functionality
  is now available in the Core as standard.

  Make a backup of your files and database once you are ready to make the upgrade.


Prepare your existing installation
----------------------------------

  - If you use login by email address, you must change the login method to
    login by username in the administration panel.  You will be required to
    login using your administration username.  Make sure you know it.

  - config.php has introduced legacy modes, please make sure this is not disabled
    before you attempt the upgrade.

  - Before unpacking *any* files, delete the following directories:

      - system/
      - themes/
      - includes/
      - pnTemp/
      - modules/Profile (if it exists)
      - modules/legal   (if it exists)

    saving the stuff that you may have inside pnTemp like file uploads.

  - Unpack the Zikula installation files.

  - Copy back your default theme for your site.  If you forget this stage, you
    will be unable to proceed with the upgrade.

  - Upload all files from the package you downloaded, copying over your files.
    Manually edit the NEW `config/config.php` with your database credentials as plain
    text; 1.3 version do not use encoded values. Please be aware the `config.php`
    is quite different so please make sure you merge in the differences from the old
    config.php to the new one. To make this easy pay close attention to lines:

           $ZConfig['System']['installed']
           $ZConfig['System']['prefix']
           $ZConfig['DBInfo']['databases']['default']*

    Do not change the following lines.

           $ZConfig['System']['temp']

  - As an optional consideration, because of the many changes between 1.2 and 1.3
    the upgrade process might be easier if you temporarily remove all the modules
    except Legal and Profile from modules/ before you run the upgrade.php. After 
    the upgrade you can add the modules back and then upgrade each module as 
    required from inside the Zikula Administration -> Extensions Manager.

    Please note the Legal and Profile modules must be the new versions, you must
    definitely delete the old Profile and Legal modules before you copy over the 
    new versions (same goes for any 1.3 compliant module).


Run the upgrade
---------------

WARNING - the moment you run `upgrade.php`, preparitory changes will be made the
the database for the 1.3 upgrade.  Your system will no longer function until you
then manually complete the remaining step.

Run the upgrade.php from the browser `http://example.com/upgrade.php`
Simply follow the instructions - this will involve chosing language, entering
your administrator login and pressing next a few times.

All database changes that are necessary will be done automatically.
At the end you will be redirected to your admin panel.

Post upgrade notes
------------------

If you use the Menutree module please note the following:
The Menutree functionality has been ported into the Zikula Core, but this is not
to be considered the same as the Menutree module because implementation in the
Zikula Core is substantially different so the upgrade process will not 'import'
the configurations from your Menutree module: they should be recreated manually.

You need to recreate all the menu blocks links too, because the standard changed from:

    {module:function&param1=value1&param2=value2:TYPE}

to

    {module:TYPE:function:param1=value1&param2=value2}

Please note that once you have successfully upgraded, you should follow the steps
in UPGRADING_THEME to refactor your theme to the new standards.  There are only
a few changes to make, but you will benefit from all the new features by doing
so.  Until you complete this, certain things may not work as expected.

If you have any startmodule settings, please visit the Settings module and make
sure you explicitly set 'starttype' and 'startfunc'.


Hooks
-----

There are now two kinds of module, 'legacy' meaning modules that comply with
Zikula 1.2.x gettext standards, and those which are written specifically for
Zikula 1.3.x, these are called 'native'.

Zikula Core 1.3.x contains a new hook system.  Legacy modules can only talk with
legacy hook modules.  Native hook modules can only communicate with other native
modules.  We recommend you use modules native to Zikula Core 1.3.  If you upgrade
from a module that was legacy, it will disconnect from the old hooks system.
This will be reported after the upgrade.

Congratulations! Your upgrade is complete. We hope you enjoy using this new
Zikula Core version. If you have any comments, please use the feedback forum on
http://community.zikula.org.
