PLEASE READ ALL OF THIS UPGRADE.txt BEFORE UPGRADING OR USING AN EXISTING 
XARAYA INSTALLATION

Ensure you check the VERSION CHANGES at the end of this file in case you need 
to update themes, templates or other areas in existing sites.

If you are creating a new Xaraya installation, please read INSTALL.txt


You are Upgrading to Xaraya: adam_baum 1.2.0-rc1
============================================
Xaraya is an Open Source web applications framework. Xaraya started out as a 
fork of PostNuke (http://www.postnuke.com).

It has had a complete re-write from the ground up since it's beginnings.

Xaraya provides significant enhancements and functionality over it's 
predecessors and is in active, on-going development.

Xaraya provides a stable and secure core, with a function rich API and 
powerful templating engine in place for third-party developers.

If you would like to help develop this software, please visit our homepage at 
http://www.xaraya.com, or send email to info@xaraya.com.

You can also visit us in channel #support or #chat, on our IRC 
Server irc.xaraya.com.

PREPARE TO UPGRADE
==================
    * Check the VERSION CHANGES at the end of this file and make note of any 
      template or site changes you may need to make

    * Backup the existing Xaraya installation & database

    * Log in to your existing Xaraya site with administration rights.

    * Ensure you protect any custom content or themes you have in
      - <xarroot>/var/ subdirectories
      - <xarroot>/themes/
      Be sure to check the upgrade changes between versions (see below)
      to ensure you update any custom templates if needed

    * Make a backup

    * Replace all existing Xaraya files, directories, and modules
      with the new Xaraya files EXCEPT:
       -  <xarroot>/var/config.system.php
       -  files below the var directory which may contain data from your site
        (typically for uploads, workflow processes, images etc)

      Make sure you check the release changes to see if you need to
      update the config.system.php file, or any changes in the var 
      subdirectories with new content of changes.

    * Make a backup (yes, we know this was already mentioned two times)

    * With "replacing" we mean DELETE all old files and copy the new ones in.
      Do not overwrite the old files with the new ones. THIS IS IMPORTANT.

      The existing <xarroot>/var/config.system.php must be retained;
      the upgrade script reads database settings from this file.
      However, you should check for any config.system.php.dist file changes
      and update your existing config.system.php file if necessary.

    * Check permissions and ownership of the new files

    * Make sure you have cleared all your cache files in
      <xarroot>/var/cache/templates and <xarroot>/var/cache/rss

    * In the browser window where you are logged in as administrator,
      point your browser to upgrade.php in your root directory and run this 
      script.  For example, http://www.mywebsite.com/upgrade.php.

    * Carefully read and follow the instructions in the upgrade script.

    * After the upgrade has completed, remove upgrade.php and install.php
      from your web directory

    * Ensure that <xarroot>/var/config.system.php has appropriate permissions.
      for security, and is read only

    * Go to Admin->Modules->View All.
      Upgrade all required modules that show the status of UPGRADE.
      Remember to Activate them after upgrade if required.

    * Clear your xarcachemanager output cache files, if you use xarcachemanager

Check the COMMON UPGRADE PROBLEMS at the end of this file if you are
experiencing upgrade difficulties.

Adding a locale (language and encoding):
---------------------------------------
- If you wish to add an additional locale for your Xaraya installation,
  download your preferred locale from 
  http://www.xaraya.com/downloads/languages.  For example: es_ES.utf8

- Unpack the new locale to the Xaraya directory at var/locales

  NOTE: If you have var/locales/es_ES.utf8 directory
        already present after installation, delete it!
        It only contains installer translations.

- Create the directory var/locales/es_ES.utf8/php

- Make this directory writeable for the web server process

- Set the site encoding to es_ES.utf8 in the
  Base - Modify Config - Languages and Locales - Default Locale setting.

- If you need an additional locale with an encoding different
  from UTF-8 please read this document
  http://www.xaraya.com/index.php/documentation/539

- If you had translations files in utf-8 format you need
  to copy translations files for your theme and modules to the new locale,
  else you should connect to our support for help with
  converting it to XML format.
  We store translations in XML format with UTF-8 encoding only.


Please visit the #xaraya.support channel for information on converting to 
Xaraya from CMS applications such as PostNuke, Joomla or PHP-Nuke.


VERSION CHANGES - Please check and update your installation where necessary
===============

   Template Changes between versions (please check your modules and theme 
   overrides for these)
   ----------------------------------------------------
   .9.10.0 -> .9.11.0
          modules/xarbb/xartemplates/user-newreply.xd : the input form
          includes an additional hidden input field for header[itemtype]

   .9.11.0 -> .9.12.0
          templates must validate as XML, i.e. you need to replace all
          & with &amp; etc.

   .9.12.0 -> .9.13.0
       1) in articles, fields of type Calendar (other than pubdate) are
          no longer pre-formatted in the view and display functions, so
          you should now use xarLocaleGetFormattedDate('long',$myfield)
          and xarLocaleGetFormattedTime('long',$myfield), or for custom
          formats xarLocaleFormatDate('...',$myfield) in those templates
       2) in comments, blocks/latestcommentsblock.xd and
          user-displayall.xd the variable $comment['daychange'] is no
          longer supported; array $commentlist is now an array of arrays.
          $commentlist[$daylabel] is the array of all comments posted on 
          $daylabel.

   1.0.0-RC1 -> 1.0.0-RC2
          uiscrub scenario integration - please check your templates!

   1.0.0-RC2 -> 1.0.0-RC3
       1) the templates for DD properties have been moved as follows :
          * modules/dynamicdata/xartemplates/admin-showinput-[property type].xd
            -> modules/[module]/xartemplates/properties/showinput-[property type].xd
          * modules/dynamicdata/xartemplates/admin-validation-[property type].xd
            -> modules/[module]/xartemplates/properties/validation-[property type].xd
          * modules/dynamicdata/xartemplates/user-showoutput-[property type].xd
            -> modules/[module]/xartemplates/properties/showoutput-[property type].xd
          * modules/dynamicdata/xartemplates/admin-showhidden.xd
            -> modules/dynamicdata/xartemplates/properties/showhidden.xd
          * modules/dynamicdata/xartemplates/user-label.xd
            -> modules/dynamicdata/xartemplates/properties/label.xd
       2) the templates for DD objects have been moved as follows :
          * modules/dynamicdata/xartemplates/admin-objectform.xd
            -> modules/dynamicdata/xartemplates/objects/showform.xd
          * modules/dynamicdata/xartemplates/admin-objectlist.xd
            -> modules/dynamicdata/xartemplates/objects/showlist.xd
          * modules/dynamicdata/xartemplates/user-objectdisplay.xd
            -> modules/dynamicdata/xartemplates/objects/showdisplay.xd
          * modules/dynamicdata/xartemplates/user-objectform.xd
            -> modules/dynamicdata/xartemplates/objects/showview.xd

          DD object templates can now be overridden with show*-[objectname].xd
          in the DD xartemplates/objects directory and/or in your own module

       3) All properties previously in includes/properties have been moved
          to their respective module 'xarproperty' directory:
          -> modules/[module name]/xarproperties
       4) Further scrubbing of templates - - please check your templates.

   1.0.0-RC3 -> 1.0.0-RC4
          the input template for the DD SubForm property type
          now uses a field prefix for all input fields

   1.0.0-RC4 -> 1.0.0

   1.0.0 -> 1.0.1

   1.0.1 -> 1.0.2

   1.0.2 -> 1.1
       1) Roles module was split into Registration module, Authentication and 
          Roles. There are now default login templates in Authsystem module.
          Registration contains registration links.
       2) The Dashboard template now uses the page template dashboard.xt by 
          default instead of admin.xt, but can be specified. This config var 
          has moved to Themes module.  The admin.xt page template is now able 
          to be overridden using usual xaraya override logic, and can be used 
          to customize specific admin module pages.
       3) The Adminpanels module has been removed. You may have to make 
          changes for specific blocks that have also been moved:
          a) adminmenu block and waiting content block:
             - any instances in templates should now be changed to
             'base' module instead of 'adminpanel' in the block tags
             - make sure you copy any templates from your theme in the
               themes/yourtheme/modules/adminpanel[/blocks] to themes/yourtheme/modules/base[/blocks]
          b) waiting content block:
             you will need to hooks for example, articles to base module 
             rather than to adminpanels module
       4) The country listing dynamic data property has been updated to store 
          the id rather than the name in the country list. You may need to 
          override the showinput-countrylist property template to continue 
          using name as the value if you have been using this property.

   1.1.0 -> 1.1.1

   1.1.1 -> 1.1.2 
         1) Example exception override templates using Authsystem Login exception as an example
         2) Update templates for roles and email validation process templates

   1.1.2 -> 1.1.3

   1.1.3 -> 1.1.4

   1.1.4 -> 1.1.5
       1) base/xartemplates/admin-modifyconfig.xd: Show an Indicator if Default 
          Module is missing
       2) dynamicdata/xartemplates/admin-privileges.xd: Preserve the Parent 
          Privilege Parameter in Wizards
       3) dynamicdata/xartemplates/objects/showform.xd: add an error class to 
          the wrapper of a dynamic data property if that property is in error
       4) installer/xartemplates/admin-choose_configuration.xd: Radio Buttons 
          for "Choose a Configuration" form
       5) installer/xartemplates/admin-create_administrator.xd: 
          a) Don't translate install time constants.  Database password field 
          is not masqueraded any more to not fire browsers 'Store Passwords' 
          dialog.
          b) Suggesting a true invalid email adress for admin with a non 
          existing TLD.
       6) installer/xartemplates/admin-phase4.xd:
          a) SQLite is now the default database if avaiable.
       7) installer/xartemplates/admin-phase5.xd: Duplicate Upgrade Warning
       8) privileges/xartemplates/admin-modifyprivilege.xd: 
          a) Allow labels in Instance Dropdowns
          b) The instance delivering queries are allowed to have a second 
          column with a 'title' for the item.
       9) privileges/xartemplates/admin-newprivilege.xd: 
          a) Allow labels in Instance Dropdowns
          b) The instance delivering queries are allowed to have a second 
          column with a 'title' for the item.
       10) roles/xartemplates/admin-showusers.xd: Remove call to tree.css in 
          roles
       11) roles/xartemplates/user-user_menu_form.xd: Default size for email 
          fields is 30 characters.
       12) themes/xartemplates/user-usermenu_form.xd: If theme directory and 
          name are not identical, default theme moduservar fails to load 
          selected theme because themes/[theme name]/xarversion.php not found:  
          Xaraya expects this moduservar to be the theme directory, not name... 
          changed to store directory rather than name.
   1.1.5 -> 1.2.0
       1) All core module templates now have extensions of .xt instead of .xd
       2) var/messaging/mail/*.xd and var/messaging/roles/*.xd templates
          are renamed to *.xt

   DB Changes between versions
   ----------------------------------------------------
   .9.0.0 -> .9.0.2 Small article and permissions changes.
   .9.0.2 -> .9.0.3 Added syndication block for RSS output.
   .9.0.3 -> .9.0.4 Small changes to article masks
   .9.0.4 -> .9.0.5 Changes to the privileges.
            Removal of the old waiting content ideas
            for new and improved version.
   .9.0.5 -> .9.0.6 None
   .9.0.6 -> .9.1.0 None
   .9.1.0 -> .9.1.2 None
   .9.1.2 -> .9.1.3 None
   .9.1.3 -> .9.1.4 None
   .9.1.4 -> .9.7.0 Various mod and configure mod changes
        to core module.  Various Time functions
        upgraded.
   .9.7.0 -> .9.8.0 None
   .9.8.0 -> .9.9.0 None
   .9.9.0 -> .9.10.0 New index on module states table
   .9.10.0 -> .9.12.0 None
   .9.13.0 -> 1.0.0 None
     1.0.0 -> 1.0.1 None
     1.0.1 -> 1.0.2 None
     1.0.2 -> 1.1.0  _admin_menu table was dropped
                     AdminPanel module is dropped
                         - adminpanel menu block is moved to Base.
                           In your templates, update any attribute values of 'adminpanels' to 'base'.
                           This includes eg adminpanel blocks such as Compact Menus tags should be changed
                           to use base module. Any theme overrides in your adminpanel blocks directory
                           should be moved to base blocks.
                         - waiting content menu block is moved to Base
                     Dashboard module var setting is moved to Themes module.
                     dashboard.xt is the default name for dashboard page template.
                     admin.xt page template is automatically used for admin theme if it exists.
                     Module Overview modvar setting has been removed and deprecated.
                     Country List dynamic data property changed the input template to use ID for value instead of name.
                         - If you are using this, retain your Base module property Country List input
                           and output templates. Rename with an extension of .xt and use these
                           as 'override templates' in your theme.
     1.1.0 -> 1.1.1 None
     1.1.1 -> 1.1.2 Running upgrade will add the following in your database:
                    Registration of new timesince tag in Base module
                    Setting of default registration module
                    Setting new user dynamic variables defaults - usertimezone, usersendemail
     1.1.2 -> 1.1.3 None
     1.1.3 -> 1.1.4 None
     1.1.4 -> 1.1.5 None
     1.1.5 -> 1.2.0 Registration of new js-plugin, js-framework, and js-event tags in Base Module
		    Modvars added to store JS frameworks, plugins, default framework, 
		    and autoload setting in Base Module.
		    Setting of BlockLayout Version Number as config var following addition of xarcore constant.
      
   ----------------------------------------------------


Common Upgrade Problems
==========================

* If you are getting errors after upgrade, clear your template
   and rss cache files (and adodb if relevant).
  Clear your xarcachemanager output cache if you have the module installed.

* If you are having difficulty accessing a module, check to see if it
   needs upgrading, and also ensure it is activated if required

* If you are using a default theme, ensure it is active and also
  does not need upgrading.

* The <xarroot>var/cache/rss and <xarroot>/var/cache/templates directories
  need to be writable and executable

