Best Practices for Spaces Upgrades

This document outlines best practices for updating your Spaces plugin to a new version

Upgrade Steps

Note: These steps assume that a previous version of Spaces has already been installed on the site. If this is not the case, then follow the installation instructions on this page.

Upload the Plugin

For external clients, it is customary to install and upgrade Spaces through the WordPress plugin interface.

1. Navigate to the website’s WordPress CMS admin dashboard and log in.

2. Check which version of Spaces is being replaced by navigating to the Spaces global settings page. The simplest upgrade procedure will be for versions marked "RC.XX", where XX is some version number. Certain older installations may be running earlier "Beta" versions that require a few extra steps.

   1. If the version name includes "Beta," then the Engrain plugin may have to be removed before the upgrade. (See below.)
   2. If custom colors are selected, check that there are more than three color fields. If there are only three color fields, then you will have to select a new set of custom colors after the upgrade is complete, or have a designer do it for you.

3. Navigate to Plugins > Installed Plugins, and check for the following:

   1. Advanced Custom Fields ("ACF") should be installed, and activated, and at least version 6.
      1. 
   2. Timber Library should be at least version 1.23.0. Alternatively, there may be a "Timber (Engrain)" plugin present with a version marked 2.0.0; this is acceptable. If neither is present, obtain and install the Timber (Engrain) plugin files in Steps 4 and 5.
   3. If a plugin named "Engrain" is present, this must be removed before upgrading Spaces, as the newer versions subsume the Engrain plugin's functionality. At this time, deactivate the old Spaces version, then deactivate and remove the Engrain plugin.

4. If you have not already done so, obtain the most up-to-date plugin files, through one of two means:

   1. If ACF and Timber both have acceptable versions, then you only need the lates version of Spaces itself. You can download the latest version of Spaces here.
   2. If ACF or Timber has a lower version than required, procure the latest version of spaces-package.zip from your implementation specialist. Extract the file's contents to obtain the following:
      • advanced-custom-fields-pro
      • timber-engrain
      • ecs-spaces

5. Add upgraded plugins using the procedure below. Upgrade ACF first (if necessary), then Timber (if necessary), then Spaces itself. The steps are as follows, with images for the Spaces upgrade:

   1. Navigate to Plugins > Add New, then click on the Upload Plugin button. A button marked "Choose File" will appear. Click on it to open a file selection dialog, allowing you to select a compressed plugin file for importation.
      1. 
   2. Navigate to the ZIP archive of the plugin you wish to install (ACF, Timber, or Spaces), and select it. Once you do, the file name will be displayed next to the "Choose File" button. Click "Install Now" when ready.
      1. 
   3. Wordpress will attempt to install the plugin. If you are uploading an updated version of a plugin that already exists, it will present you with a screen showing the two different versions, and giving you the option to replace the existing version of the plugin with the new one, or to cancel the installation of the new files. Click "Replace current with uploaded" to proceed.
      1. 
   4. Once the installation is complete, activate the plugin.

6. Once the procedure in Step 5 has been completed, you can proceed to the next phase of the upgrade. If any unexpected problems occurred, contact a dev for assistance.

🚧

It is recommended to first test any updates for plugins, themes, and WordPress on a staging version of your site before applying them to the live production site, if possible. Additionally, ensure you create a backup that can be restored before updating any plugin or theme.

Update Global Settings

1. After the installation is confirmed, navigate to the Global Settings page under the Spaces menu items. (Clicking on the top level Spaces menu item will generally suffice.)
   1. 
2. Click the Update button to refresh styles and initialize any new fields.
   1. 
3. As noted in Step 3, Section III of the plugin update procedure above, some older sites may have been using very old versions of Spaces that only allowed three custom colors. When upgrading to more advanced versions with more custom color options, it will be necessary for the user to switch to the default color scheme, or to select new custom colors. If unsure which colors to use, contact a designer for assistance.

Import SightMap Data

1. Go to Spaces > Assets, and click on the name of the asset in the index to view its details.
   1. 
2. Click the Update button once. Wait for the page to refresh.
   1. 
3. Click the Clear Spaces Data Cache button. A notification banner will appear at the top of the page when the process is complete.
4. Select Import SightMap Data. The entire import process should take approximately five minutes, depending on the number of floor plans and units.
   1. 
5. An email will be sent to the site administrator once the process is complete.
6. If you have multiple Spaces Assets, repeat steps 1-4 for each one.

At this stage, your Spaces should be successfully upgraded to the latest version.

Common Issues and Resolutions

Color Selections and CSS Issues:

If the front-end of your site does not appear as expected, double-check the customization values entered in the CMS. Ensure that each color code begins with a # symbol (e.g., #ffffff for white).

Virtual Tour Issues

If you are unable to select a Virtual Tour Group or Unit Description Group, please contact support to request that this feature be enabled for your account.