Edit+ Installation Guide for Matrix 5.2 - 5.3

Last Updated: 05 Dec 2016

This guide will help you install Edit+ on your Squiz Matrix System.

This guide is current for Squiz Matrix version 5.2 to 5.3.

Install Guides for Older Versions

The table below contains archived PDF files for previous versions of the Easy Edit Suite/Edit+ install guide.

EES/Edit+ Versions Squiz Matrix Compatibility Archived Install Guides
435 to 833 3.28.0 to 3.28.9 Install Guide for EES Phase 1 and 2 (PDF)
1081 to 1141-3 4.4.1 to 4.8.1 Install Guide for EES Phase 3 (PDF)
1645 to 1.5.0 4.6.6 to 4.18.9 Install Guide for EES Phase 4 (PDF)
5.0 to 5.1 5.0 to 5.1 Install Guide for Matrix 5.0 - 5.1

Downloading Edit+ to your Server

This guide assumes that you have installed Squiz Matrix into /var/www/ - please make adjustments to commands as required. It also assumes you have downloaded and placed a copy of the Edit+ package into the /var/www/matrix/data/public directory on your server.

Running the following commands will navigate you to the correct directory and unpack Edit+ in to the matrix/data/public folder. The downloaded file will contain a version number, so be sure to replace [version] with the current version number in the commands below.

$ cd /var/www/matrix/data/public
$ tar -zxf edit-plus-[version].tar.gz
$ rm edit-plus-[version].tar.gz

After running these commands, you should have a new directory called ees.

The Javascript API

Javascript API asset needs to be created for Edit+ to communicate with the Squiz Matrix system.

Creating the Javascript API and Setting Permissions

To create the Javascript API:

  1. Right click on the Web Services Folder, or any Site Asset with a URL applied, in the Asset Map and select New Child -> Web Services -> JavaScript API.
  2. Enter the name Edit+ for the asset and click Commit.
  3. Right click on the Javascript API and select Permissions.
  4. Acquire the lock(s) on the page and, under the Read Permissions section, select Deny for Public Permissions.
  5. Apply Read Permission to the Users and User Groups that will have access to Edit+.
  6. Click Commit to save this change.
Configuring the Javascript API

On the Details screen of the Edit+ Javascript API, change the following fields:

  • Status: set the Status of the Javascript API to Live.
  • Root Nodes: select the Site assets that are to use Edit+. This should include the root nodes of any assets that are to be editable on Edit+ that may not be located under a Site, such as File or Image assets    linked under the Media Folder.
  • Allow Attributes on Create: select Yes.
  • Return JSON: select Yes.
  • Ignore Permissions: select No.
  • Use Enhanced JS API: select Yes.
  • Allow Batching Requests: select Yes.
  • Enable all the API functions in the following sections:    
    • Core
    • Linking
    • Permissions
    • Workflow
    • Traversing
    • Metadata
    • Google Analytics
    • System Information
    • Form Questions

Once you have made these changes, click Commit.

Tip: Keep a note of the API Key that is displayed on this screen while you are editing. You will need it later in the installation process.

Applying URLs

Each Site with a unique URL that is to use Edit+ will require their URLs to be applied to various locations. This will ensure that there are no cross domain conflicts with the Edit+ JavaScript calls to the Javascript API asset.

Upon first installing Edit+ and/or adding new Site assets to use Edit+, check the following:

  • The new URL(s) has been applied to the Site asset.
  • The new URL(s) has been applied to the Designs Folder . Please note that if you are using an alternate design configuration to control your Site's design, then ensure the new URL(s) are applied to the relevant parent asset instead.
  • The new URL(s) has been applied to the Web Services Folder (if used). Please note that if your Edit+ Javascript API is not located under the Web Services Folder, you will need to apply the URL(s) to the relevant parent asset instead.

Tip: Remember to maintain the URL format of system folders when applying the URL of your Site. For example, if the URL of your Site is http://www.example.com, you would apply this URL to the Designs Folder as http://www.example.com/_designs and to the Web Services Folder as http://www.example.com/_web_services.

Constructing the Configuration File

Edit+ assumes the presence of a JSON formatted configuration file. A template of this configuration file can be found in <site_domain>/__data/ees/Examples/ConfigurationFile.js.

To set up an editable configuration file inside your Squiz Matrix system, locate an accessible location where the same URL as used on your Site Asset is applied.

  1. The Edit  Config File
    The configuration file

    Create a JS File asset, naming it EditPlusConfig, as shown in the figure on the right.
  2. Edit the file and save the content sourced from the ConfigurationFile.js file in the Examples folder.
  3. On the Permissions screen, acquire the lock(s) on the page and, under the Read Permissions section, select Deny for Public Permissions.
  4. Apply Read Permission to the Users and User Groups that will have access to Edit+.
  5. Change the status of the file to Live.

Tip: Take note of the asset ID of the EditPlusConfig JS File asset as you will need it later in this guide.

Configuration Options

You can set a number of configuration options on the Edit Plus configuration file:

  • debug: set this option to either true or false to tell the system if it is allowed to perform debugging operations. If this option is set to true, debugging information will be logged to web developer diagnostic tools (e.g.    FireBug's    console tab).
  • titleBar: this text will be shown in the title bar of the browser. Use the keyword replacement @asset_name@ to use the name of the asset in the title bar.
  • lockRefreshInterval: this option determines how often the system should re-acquire locks for the currently active screen. The default value for this option is 120 seconds, the system default. This should be altered to match the current system's lock refresh interval,    if    it has been changed.
  • JSAPI -> key: this option must contain the API Key of the Javascript API, as shown in the figure below. This key is obtained on the details screen of your Edit+ Javascript API. If the API Key at any    time    changes, the configuration file will need to be updated.                  

    Setting the API Key
    Setting the API Key in the configuration file

  • cascadeThreshold: at times, Edit+ will warn editors if they are about to affect a large number of assets. This number is determined in this option. A high value will result is less warnings for users but could potentially results in users unwittingly cascading changes    across    large sections of the system, resulting in failed actions or stale hipo jobs.
  • overlayTimeout: when the loading animation is presented to an editor, it is generally waiting on a response back from the server. The action the editor is performing may result in a failed request on the server (due to memory exceeding, execution timeouts, database errors etc.). This    option    sets a timeout (in seconds) after which a warning will be displayed to the editor informing them that their request may have failed. Editors will have the option to continue with the request or cancel the request, which will reload the current asset in the editing interface.
  • defaultMode: this option allows you to specify the default mode to display when Edit+ is first loaded. The options available are either edit (Edit Mode) or preview (Preview Mode). By default, this option will be set to edit.
  • defaultScreen: this option allows you to set the default edit screen to display when Edit Mode is initially loaded. For example, setting this option to content will load the Content screen when Edit Mode is first accessed. By default, this option    is    set to details (the Details screen).
  • showDifferencesInPreviewMode: when Edit+ is in Preview Mode, an asset that has a Status of Safe Edit can compare its content against the Live version of the asset. This configuration option allows you to enable this comparison    when    an asset is in Preview Mode. By default, this option disabled, meaning that a comparison will not automatically be displayed for Safe Edit assets. Instead, a Compare to Live button will be shown, allowing users to manually enable the content comparison. For    more    information, refer to the Edit+ chapter in this manual.
  • assetFinderLocations: this option allows you to specify an array of custom root nodes to be listed on the Asset Finder. For more information on this option, refer to the Asset Finder chapter in this manual.
  • assetFinderMaxAssets: this option allows you to specify the number of children to display under each asset in the Asset Finder before pagination occurs. By default, this option is set to 100 assets, meaning that only up to 100 assets will be displayed as children    of    each asset in the Asset Finder. Assets with more than 100 children will provide users with pagination tools to display any remaining children. Setting this field to will remove pagination from the Asset Finder and display all child assets, irrespective    of    the amount.
  • cacheManagerDefaultExpiry: certain information in Edit+ is cached to improve performance. This configuration option allows you to set the expiry time (in minutes) for information stored in cache. By default, this option is set to 2 minutes.
  • useThumbnail: this option allows you to enable the Thumbnail settings on the Details screen of assets. If this option is set to false, the Thumbnail section will not be displayed and these settings will not be    available    to users. By default, this option is set to true.
  • allowFutureStatusChange: this option allows you to enable the Future Status settings on the Details screen of assets. If this option is set to false, the Future Status section will not be displayed and these settings will not    be    available to users. By default, this option is set to true.
  • showChildrenOnLinkingScreen: this option allows you to enable the Direct Children settings on the Linking screen of assets. If this option is set to false, the Direct Children section will not be displayed and these settings will not    be    available to users. By default, this option is set to true.
  • enableSiteEditing: this option allows you to enable the editing of Site Assets within Edit+. See the Site Asset chapter for more information.

Adding Edit+ to your Design's Parse File

To use Edit+ on a Site, the Parse File of the Site's Design must be edited.

To do this:

  1. Locate the Design of the Site in the Asset Map. Right click on the Design and select Details.
  2. Acquire the lock(s) on the Details screen. Locate the Details section of the screen and in the No Frames in Simple Edit Interface field, select Yes, as shown in the figure below. Click Commit to save this change.        

    Setting the No Frames Option on the Design
    The No Frames in Simple Edit Interface field

  3. Right click on the Design and select Edit Parse File. Acquire the lock(s) on the page.
  4. At the very top of the parse file, before any other code, add the following:
    <MySource_AREA id_name="edit_plus_exit_area" design_area="exit" print="no"></MySource_AREA>
    <MySource_AREA id_name="edit_plus_token" design_area="csrf_token" print="no"></mysource_area>
    <MySource_AREA id_name="edit_plus_nested_content" design_area="nest_content" print="no" />
    <MySource_AREA id_name="edit_plus_show_if" design_area="show_if">  
       <MySource_SET name="condition" value="simple_edit_mode" />  
       <MySource_THEN>        
          <!DOCTYPE html>    
          <html lang="en">      
          <head>        
             <meta charset="utf-8" />        
             <title>Loading Edit Mode...</title>        
             <MySource_PRINT id_name="edit_plus_nested_content" />      
          </head>      
          <body>        
             <mysource_print id_name="edit_plus_token" />      
          </body>    
       </html>        
       <MySource_PRINT id_name="edit_plus_exit_area" /></MySource_THEN>
    </MySource_AREA> 

    The csrf_token design area and print tag are only required for systems where SQ_CONF_ENABLE_CSRF_TOKEN_REQUEST is set to 0 in the main.inc file of the      Squiz Matrix installation. If this design area is not present, you may get prompted with an CSRF Token error when trying to load the Edit+ interface. For more information, please consult your Server Admin.

  5. Click Commit to save this change.

Setting Up the Edit+ Code Nested Standard Page

To include Edit+ on a Site, an Edit+ Code Standard Page must now be created.

Changing the Content Type of the WYSIWYG DIV
Setting the Raw HTML DIV

The content of this Standard Page will contain the Edit+ code, along with any other custom CSS styles and JavaScript code.

This Standard Page is then nested in the Design of your Site.

  1. Create a new Standard Page called Edit+ Code and make it Live.
  2. On the Permissions screen, acquire the lock(s) on the page and, under the Read Permissions section, select Deny for Public Permissions.
  3. Apply Read Permission to the Users and User Groups that will have access to Edit+.
  4. On the Edit Contents screen, edit the properties of the default WYSIWYG Editor Content DIV, changing the Presentation setting to Raw (no formatting) and the Content Type setting to Raw HTML, as shown in the figure to the right.
  5. In the new Raw HTML Division, add the following:
    <!-- Edit+ CSS  -->
    <link href="/__data/ees/easyedit.min.css" rel="stylesheet" media="screen" />
    <link href="/__data/ees/Viper/viper.css" rel="stylesheet" media="screen" />
    
    <!-- Edit+ JS API -->
    <script src="./?a=XXXX"></script>
    
    <!-- Edit+ Configuration -->
    <script src="./?a=XXXX"></script>
    
    <!-- Edit+ Core Scripts  -->
    <script src="/__data/ees/easyedit.min.js"></script>
    <script src="/__data/ees/Viper/viper.js"></script>
  6. Edit the src attribute for the <script> tag under the heading Edit+ JS API. Replace "XXXX" with the Asset ID of the JS API asset you created earlier.
  7. Edit the src attribute for the <script> tag under the heading Edit+ Configuration. Replace "XXXX" with the Asset ID of your Edit+ configuration file asset.        

    Tip: You can use this Standard Page to add custom CSS styles and JavaScript code to override existing Edit+ styles, for example, use different screen tab background images, toolbar button images etc. For more information, refer to the CSS Customisation and JavaScript Plugins chapters in this manual.

  8. On the Details screen of the base level (direct children) Customisation(s) of your Site's Design, customise the edit_plus_nested_content design area.        

    Tip: If there are no existing Customisations on your Design, create a new Design Customisation on the Customisations screen.

  9. On the Details screen of the customised design area, select the Edit+ Code Standard Page asset in the Nested Asset field.        

    Nesting the Edit  Code Page
    Nesting the Edit+ Code Standard Page

    The Print setting on the edit_plus_nested_content design area should be set to No.

  10. Apply the Design Customisation to your Site.

Removing Edit+ from a Design

To remove Edit+ from a Design:

  1. Acquire the lock(s) on the Edit Parse File screen of the Design file.
  2. Remove the whole Edit Plus Exit Design Area from the top of the parse file and click Commit. This will remove references to Edit+ in the parse file of the Design.
  3. Acquire the lock(s) on the Details screen of the Design file.
  4. In the No Frames in Simple Edit Interface field, select No and click Commit.

Edit+ will now be removed from your Design.

The Latest

Let Us Know What You Think

Let us know if you spot any errors or if you have any ideas on how we can improve the Matrix Community Website.

Contact Squiz for Demo

Let us show you the true power of Squiz Matrix by giving you a personalised demonstration.