Current lineage:

1. Documentation

Easy Edit Suite - Offline Install Guide

This guide will help you install the Easy Edit Suite on your Squiz Matrix System. This is an 'offline' version of the full install guide available online. Extra steps are required to enable Edit+ on top of the standard EES install. This guide is current for EES version 1645 and above.

This guide assumes that Squiz Matrix is installed in the following location /var/www/ - please make adjustments to commands as required.

Upgrading Existing Installs

If you have already installed the Easy Edit Suite on your system and require information on upgrading your version, refer to the Upgrade and Compatibility Guide chapter online.

Downloading the Easy Edit Suite to your Server

If you are reading this then we can safely assume you have the EES tarball unpacked somewhere, but here are the instructions to get latest tarball online anyway.

Running the following commands will download a copy of the latest stable version of the Easy Edit Suite using wget and unpack it 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

$ wget http://matrix.squizsuite.net/ees.tar.gz

$ tar -zxf ees_[version].tar.gz

$ rm ees_[version].tar.gz

If you are not using the command line you can download EES from the Squiz Suite website.

For older versions of the Easy Edit Suite, refer to the Upgrade and Compatibility Guide chapter online.

Changing Global Preferences

The Easy Edit Suite requires that the WYSIWYG Style - Body Type option be set to iFrame. Please note that this change will not affect current WYSIWYG usage.

To set this option:

1. Click on the System Configuration button on the top right hand corner of the Administration Interface - a drop-down list will appear under this icon. From this list select Global Preferences. The Global Preferencesscreen will appear.
2. Acquire the lock(s) on the Global Preferences screen and locate the WYSIWYG Content Type Preferences section, as shown in the figure below.

   
   The WYSIWYG Content Type Preferences section of the Global Preferences screen

3. In the Body Type field of the WYSIWYG Style options, select iFrame from the drop-down list, as highlighted in the figure above.
4. Click Commit to save this change.

The Javascript API

A Javascript API asset needs to be created for the Easy Edit Suite 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 in the Asset Map and select New Child -> Web Services -> JavaScript API.
2. Enter the name Easy Edit Suite  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 Denyfor Public Permissions.
5. Apply Read Permission to the UsersandUser Groupsthat will have access to the Easy Edit Suite.
6. Click Commit to save this change.

Configuring the Javascript API

On the Details screen of the Easy Edit Suite  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 the Easy Edit Suite. This should include the root nodes of any assets that are to be editable on the Easy Edit Suite 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 Core , Linking , Permissions , Workflow , Traversing and Metadata sections.

Once you have made these changes, click Commit.

Tip: Keep a note of the API Keythat 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 the Easy Edit Suite will require their URLs to be applied to various locations. This will ensure that there are no cross domain conflicts with the EES JavaScript calls to the Javascript APIasset.

Upon first installing the Easy Edit Suite and/or adding new Site assets to use the Easy Edit Suite, 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. Please note that if your EES 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 Siteis http://www.example.com, you would apply this URL to the Designs Folderas http://www.example.com/_designs and to the Web Services Folderas http://www.example.com/_web_services.

Constructing the Configuration File

The Easy Edit Suite assumes the presence of a configuration file containing JSON. A template of this configuration file can be found in <easy_edit_system_root>/Examples/EasyEditConfigSample.js .

To set up an editable configuration file inside your system, locate an accessible location inside Squiz Matrix.

1. 
   The configuration file

   Create a JS Fileasset, naming it EasyEditConfig, as shown in the figure on the right.
2. Edit the file and save the content sourced from the EasyEditConfigSample.js file.
3. On the Permissionsscreen, acquire the lock(s) on the page and, under the Read Permissions section, select Denyfor Public Permissions.
4. Apply Read Permission to the Usersand User Groupsthat will have access to the Easy Edit Suite.
5. Change the status of the file to Live.

Tip: Go to the Web Pathsscreen of the file and take note of the URL displayed there as you will need it later in this guide. This path will vary depending on the location of the file in the system. If this file has been created underneath the system's Media Folder, as per this example, its URL will be in the format /_media/EasyEditConfig.js.

Configuration Options

You can set a number of configuration options on the Easy Edit Suite's 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.
• baseSiteUrls : this option allows you to specify an array of base site URLs for the Easy Edit Suite. Please note that, for the majority of systems, this configuration will not be necessary. 
• JSAPI -> key: this option must contain the API Keyof the Javascript API, as shown in the figure below. This key is obtained on the details screen of your Easy Edit Suite  Javascript API. If the API Key at any time changes, the configuration file will need to be updated.          

  
  Setting the API Key in the configuration file

• Suffixes: a representation of the suffixes found in the Squiz MatrixSystem Configurationmenu. If these suffixes are not using the system defaults, the values should be reflected in this option.
• cascadeThreshold: at times, the Easy Edit Suite 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 the Easy Edit Suiteis 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 whenEdit Modeis initially loaded. For example, setting this option to content will load the Contentscreen when Edit Modeis first accessed. By default, this option is set to details (the Details screen).
• showDifferencesInPreviewMode: when the Easy Edit Suiteis in PreviewMode, an asset that has a Statusof Safe Edit can compare its content against the Liveversion 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 Livebutton will be shown, allowing users to manually enable the content comparison. For more information, refer to the The Easy Edit Suitechapter 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 Finderbefore 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 0  will remove pagination from the Asset Finderand display all child assets, irrespective of the amount.
• cacheManagerDefaultExpiry: certain information in the Easy Edit Suiteis 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 Thumbnailsettings 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 .  

Adding the Easy Edit Suite to your Design's Parse File

To use the Easy Edit Suite on a Site, the Parse Fileof the Site'sDesign 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.

   
   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="exit_area" design_area="exit" print="no"></MySource_AREA>
   
   <MySource_AREA id_name="nested_EES_code" design_area="nest_content" print="no" />
   
   <MySource_AREA id_name="simple_edit_EES" design_area="show_if">
   
   <MySource_SET name="condition" value="simple_edit_mode" />
   
       <MySource_THEN>
       
           <!DOCTYPE html>
           <html lang="en">
               <head>
                   <meta charset="utf-8" />
                   
                   <!-- EES install and implementation help: http://manuals.matrix.squizsuite.net/ees/chapters/installation -->
                   
                   <!-- The title tag is dynamically replaced by EES code, see your EES config.js file to customise -->
                   <!-- Related install step: http://manuals.matrix.squizsuite.net/ees/chapters/installation/#Constructing-the-Configuration-File-->
                   <title>Loading Easy Edit Suite...</title>
                   
                   <!-- Use a nested standard page (set to raw html) for custom CSS and JS file references. Avoids editing design file. -->
                   <MySource_PRINT id_name="nested_EES_code" />
                   
               </head>
               <body></body>
           </html>
           
           <MySource_PRINT id_name="exit_area" />
           
       </MySource_THEN>
       
   </MySource_AREA>
   

5. Click Commit to save this change.

Setting Up the EES Styles and Scripts Nested Standard Page

To setup the Easy Edit Suiteon a Site, an EES Styles and Scripts Standard Pagemust now be created.

Setting the Raw HTML DIV

The content of this Standard Pagewill contain the Easy Edit Suite code, along with any other custom CSS styles and JavaScript code.

This Standard Pageis then nested in the Design of your Site.

1. Create a new Standard Pagecalled EES Styles and Scripts .
2. Make the Standard Page asset Livewith public read access.
3. On the Edit Contents screen, edit the properties of the default WYSIWYG Editor Content DIV, changing the Presentation and Content Typesto Raw HTML, as shown in the figure to the right.
4. In the new Raw HTML Division, add the following:

   <!-- Easy Edit CSS  -->
   <link href="/__data/ees/easyedit.min.css" rel="stylesheet" media="screen" />
   
   <!-- Squiz Matrix / Easy Edit JS API (replace with correct file path to JS API within web services folder, file path may vary per implementation) -->
   <!-- Related install step: http://manuals.matrix.squizsuite.net/ees/chapters/installation#The-Javascript-API-->
   <script src="/_web_services/xxxx.js"></script>
   
   <!-- Easy Edit Configuration (replace with correct file path, file path may vary per implementation) -->
   <!-- Related install step: http://manuals.matrix.squizsuite.net/ees/chapters/installation#Constructing-the-Configuration-File-->
   <script src="/path/to/eesconfig/xxxx.js"></script>
   
   <!-- Easy Edit Core Scripts (path to install directory within data/public/)  -->
   <script src="/__data/ees/easyedit.min.js"></script>
   

5. Edit the URL under the heading Squiz Matrix / Easy Edit JS API. Ensure this path matches the location of the JS API asset you created earlier.
6. Edit the URL under the heading Easy Edit Configuration. Ensure this path matches the location of your EES configuration file asset.

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

7. On the Details screen of the base level (direct children) Customisation(s)of your Site'sDesign, customise the nested_ees_code design area.

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

8. On the Details screen of the customised design area, select the EES Styles and Scripts Standard Pageasset in the Nested Asset field.

   
   Nesting the EES Styles and Scripts Standard Page

   The Print setting on theCustom Styles and Scripts design area should be set to No .

9. Apply the Design Customisation to your Site.

Setting the Easy Edit Suite Login Design

A Login Designis available for the Easy Edit Suiteto maintain a consistent look and feel for users.

To apply the Login Design:

1. Right click on the Site that you have configured the Easy Edit Suitefor and select Settings.
2. Acquire the lock(s) on the Settings screen and locate the System Defined Login Design section, shown in the figure below.

   
   The System Defined Login Design section

3. Select the Change button in the New? field (titled Change? if a Login Design is already applied).
4. Locate the ees_login_design asset (located in the System Design Folder), right click on it and select Use Me. 
5. Click Commit to save this change.

Removing the Easy Edit Suite from a Design

To remove the Easy Edit Suitefrom a Design:

1. Acquire the lock(s) on the Edit Parse Filescreen of the Designfile.
2. Remove the Exit Design Areafrom the top of the parse file and click Commit. This will remove references to the EES in the parse file of the Design.
3. Acquire the lock(s) on the Detailsscreen of the Designfile.
4. In the No Frames in Simple Edit Interfacefield, select Noand click Commit.

The Easy Edit Suitewill now be removed from your Design.