Configuring Exponent

From ExponentCMS Docs

Configuring Exponent

This page contains a guide to Configuring your Exponent CMS website.

User Guides & Tutorials

This guide assumes some knowledge of Exponent. If you are new to Exponent, then you may want to view the Tutorials category for step-by-step guides. If you have a specific issue you need help with see the Frequently Asked Questions page.

Configuring Exponent

Below is an outline of the basic configuration required for an Exponent website. These will vary depending on individual site requirements, but this should be a good starting point. This guide assumes that you have selected to Install Example Content.

Configuration Settings

1. Login to your Exponent website and goto Admin Control Panel.
2. Use the Configure Site link to open the Configure Exponent page.
3. Click on the Edit link.
4. Set your General Site Configuration settings. Most can be left at default values, but the following should be set to your site's requirements:
   • Site Title — set the title which will appears on your site's pages.
   • Search Engine Keywords — set the meta keyword tags for your site.
   • Site Description — set the meta description tag for your site.
   • Default File Permissions and Default Directory Permissions — if you want to upload images and files, then these should be set to World Readable and Writable. See Fixing Images Forbidden Error below.
5. Set your SMTP Server Settings:
   • Tick Use PHP mail() function or enter your SMTP Server details. Please note that some spam filters block mail sent using the PHP Mail function, so it is safest to use your SMTP Server.
6. Set your Display Settings:
   • Theme — set the Theme you want to use for your site. You should always Preview a theme before changing your Site Configuration. See Previewing a Theme on the Installing Themes page.
   • Date and Time Formats — customise these to suit your needs. If you need a value which is not available in the pop-up, see Setting Date and Time Formats below.
7. Database Options — DO NOT change any of these settings unless you specifically wish to connect your Exponent installation to a new database. Modifying any of these settings may cause your Exponent website to quit working.
8. Search Engine Friendly URLs — the default setting should be left in place as these are not currently supported.
9. Site Maintenance Settings — the default settings should suffice.
10. When complete, click the Save button.

HTMLArea Toolbar Settings

The standard Exponent text editor is FCKEditor and only a few of the most used content editing icons are enabled by default. You can customise the icons for your site by:

1. Login to your Exponent website.
2. Goto Admin Control Panel.
3. Click on the HTML Area > Toolbar Settings link to load the HTMLArea Toolbar Settings page.
4. Click on the Edit icon link next to the Default configuration to load the Configuration Manager.
5. Use the controls to add or remove icons for various text editing functions.
6. When complete, tick the Activate box and click Save.
7. Go to a page on your website with a Text Module and click Edit to see your updated HTML Editor Controls.

See also Replacing or Upgrading FCKEditor below.

Enable Custom Modules

Exponent Modules must be enabled before they can be added to pages using the Container Module.

1. Login to your Exponent website.
2. Goto Admin Control Panel.
3. Click on the Extensions > Manage Modules link.
4. From the list of available Modules, activate the ones you want to use:
   • Click on the Activate All Modules link to enable all modules, or
   • Locate the specific Module you wish to use and click on it's Activate Module link.

For more info see the Installing Modules page.

Troubleshooting

Below are additional Configuration tips and tricks which address specific issues.

Fixing Images Forbidden Error

By default, Exponent blocks uploads. In order to upload images and other files you need to enable them and change your Exponent Configuration to make them world readable.

1. Set the permissions on your /files/ folder to 755. Please note that in some server configurations you may need to set the folder permission to 777.

    /files/                (folder including sub-folders)

2. Login to your Exponent site and goto Admin Control Panel > Configure Site > Edit.
3. Set Default File Permissions to World Readable and Writable.
4. Set Default Directory Permissions to World Readable and Writable.
5. Save your settings and you should now be able to upload images and other resources.

See also Forum Post: Image Upload Permission and Forum Post: Permissions Problems.

Advanced HTML Editor Controls

The default HTML Editor layout is not suitable for some themes. In order to change the appearance of the HTML Editor you need to modify the settings in the php file. See also HTMLArea Toolbar Settings above for standard layout options.

ALERT! If you modify the HTML Editor Controls file then it will be overwritten when you upgrade Exponent. Save a backup of any changes to your local computer.

Exponent Version 0.96.5

Edit the file:

/subsystems/forms/controls/htmleditorcontrol.php

Change the code (line 156):

<textarea id="<?php echo $name; ?>" name="<?php echo $name; ?>" style="width:100%" rows="24" cols="80">

to:

<textarea id="<?php echo $name; ?>" name="<?php echo $name; ?>" style="width:100%" rows="84" cols="80">

Exponent Version 0.96.6

Edit the file:

/exponent/subsystems/forms/controls/EditorControl/views/FCKEditor.tpl

Change the code (line 90):

oFCKeditor.Height= '300';

to:

oFCKeditor.Height= '600';

Or to whatever height in pixels which suits your website.

Customising FCKeditor

You can add your Exponent theme's CSS styles into FCKEditor so that users see text as it will appear on the site. You can further customise FCKeditor by adding CSS styles to the FCKeditor Styles dropdown menu so that users can format text. This can be particularly useful for positioning images and other elements via the editor.

ALERT! If you modify the FCKeditor CSS files then they will be overwritten when you upgrade Exponent. Save a backup of any changes to your local computer.

Customising FCKeditor CSS Styles

1. Edit the file external/editors/FCKeditor/editor/css/fck_editorarea.css.
2. Add your the formatting CSS from your Exponent theme's stylesheet to this file.
3. Don't add page layout CSS as this will be ignored.

Customising FCKeditor Styles Dropdown

1. Edit the file external/editors/FCKeditor/fckstyles.xml.
2. Add the CSS styles and classes in the order you want them to appear in the menu:

• Inline CSS styles:

<Styles>
	<Style name="Image on Left" element="img">
		<Attribute name="style" value="padding: 5px; margin-right: 5px" />
		<Attribute name="border" value="2" />
		<Attribute name="align" value="left" />
	</Style>
	<Style name="Custom Bold" element="span">
		<Attribute name="style" value="font-weight: bold;" />
	</Style>
	<Style name="Custom Italic" element="em" />
	<Style name="Title H3" element="h3" />
	<Style name="Custom Ruler" element="hr">
		<Attribute name="size" value="1" />
		<Attribute name="color" value="#ff0000" />
	</Style>
</Styles>

• CSS classes styles (format these via your theme's stylesheet):

<Styles>
	<Style name="Small Text span" element="span">
		<Attribute name="class" value="smalltext" />
	</Style>
	<Style name="Small Text div" element="div">
		<Attribute name="class" value="smalltext" />
	</Style>
	<Style name="Grey Text span" element="span">
		<Attribute name="class" value="greytext" />
	</Style>
</Styles>

Refreshing FCKeditor

Once you have completed editing your FCKeditor CSS files:

1. Open FCKeditor in your browser by editing a page on your site.
2. Do a shift+refresh to load the new CSS.

Please note that you may need to load the edited files into a browser window and hit refresh. In some cases you may need to logout of Exponent, close your browser, and then restart your session for the new styles to take effect.

Replacing or Upgrading FCKEditor

To upgrade your installed version of FCKEditor or replace it with another text editor such as TinyMCE or Xinha follow the instructions below.

Upgrading FCKEditor

Follow these instructions to upgrade your installed version of FCKEditor:

1. Download the latest version of FCKEditor from fckeditor.net.
2. Uncompress the FCKEdtior software archive and upload it to your web server.
3. Make a backup of your existing FCKEditor folder in case something goes wrong:

    /external/editors/FCKeditor

4. Replace your existing FCKEditor folder with the new version of the software:

    /external/editors/FCKeditor

That's it. For more information visit the FCKEditor Documentation guide at wiki.fckeditor.net.

Replacing FCKEditor with TinyMCE

Follow these instructions to install TinyMCE as your default HTML editor:

1. Download the latest TinyMCE package from Exponent Sourceforge Downloads page or from tinymce.moxiecode.com.
2. Uncompress the TinyMCE software archive and upload it to your web server in the folder:

    /external/editors/tinymce

3. Go to your Exponent website's Administration Control Panel.
4. Select Configuration > Configure Site.
5. Click the Edit link.
6. In the General Site Configuration section, use the HTML Editor drop-down to select TinyMCE.

   Please Note: If TinyMCE does not appear in the drop-down then check that you have installed it properly.

7. Save your new Configuration.

TinyMCE should now be the default editor for your website. For more information visit tinymce.moxiecode.com.

Replacing FCKEditor with Xinha

Follow these instrauctions to install Xinha as your default HTML editor:

1. Download the latest Xinha package from Exponent Sourceforge Downloads page or from xinha.webfactional.com.
2. Uncompress the Xinha software archive and upload it to your web server in the folder:

    /external/editors/xinha

3. Go to your Exponent website's Administration Control Panel.
4. Select Configuration > Configure Site.
5. Click the Edit link.
6. In the General Site Configuration section, use the HTML Editor drop-down to select Xinha.

   Please Note: If Xinha does not appear in the drop-down then check that you have installed it properly.

7. Save your new Configuration.

Xinha should now be the default editor for your website. For more information visit xinha.webfactional.com.

Setting Date and Time Formats

ALERT! If you modify the Date Format file then it will be overwritten when you upgrade Exponent. Save a backup of any changes to your local computer.

If the built-in date and time formats are not suitable for your configuration (i.e. you need European or Asian dates), then you can edit or add settings by modifying the following files:

/conf/data/time_format.dropdown           (file)
/conf/data/datetime_format.dropdown       (file)
/conf/data/date_format.dropdown           (file)

Add Dates as required:

%a %d %b %Y      (Mon 25 Dec 2004)

Date Codes

%A	Monday
%a	Mon
%B	November
%b	Nov
%e	1
%D	11/01/04
%d	01
%m	11
%Y	2004
%y	04

Time Codes

%l	hour (12 cycle)
%H	hour (24 cycle)
%M	mm minute
%P	am/pm
%T	time in hh:mm:ss

For more information see PHP Manual : Date and Time Functions.

Show PHP Errors

ALERT! You should only Show PHP Errors on a development website. Never do this on a live site or your users will see the error messages as they browse!

If you are having problems with your Exponent website and are unable to locate the problem, then you should switch on display of PHP errors, which will display PHP execution errors on each page of your website.

To do this, edit file:

exponent_version.php                 (file)     (NOT pathos_version.php)

Change the line:

define('DEVELOPMENT',0); // CHANGE FOR DIST

to:

define('DEVELOPMENT',1); // CHANGE FOR DIST 0=off 1=on

• See Exponent How Do I — My page is coming up blank. How can I see what is wrong?

Change Address State Length

ALERT! If you modify the Address Tables files then they will be overwritten when you upgrade Exponent. Save a backup of any changes to your local computer.

By default Exponent saves the state field in the User Address Subsystem and the Address Book Module in the US Short Form of only 2 characters length (i.e. NY for New York). For international users and some US users this is not suitable so it is necessary to change the database tables.

Change State Length in the User Address Subsystem

The User Address Subsystem is used when registering Users on an Exponent website. You can change the state length as follows:

1. Modify the Database

1. Open your Database Administration application, such as phpMyAdmin.
2. Load the Exponent Database which holds the data for your website.
3. Select and load the user_address table (usually exponent_user_address).
4. Tick the box next to the field state.
5. Click the Drop (red X) link.
6. When prompted, confirm the table modification.

ALERT! DO NOT DROP the entire user_address table or you will lose the login data for your site!

2. Modify the Database Definition File

1. Open the file datatypes/definitions/user_address.php:
2. Change line 37 from:

'state'=>array(
   DB_FIELD_TYPE=>DB_DEF_STRING,
   DB_FIELD_LEN=>2),

To:

'state'=>array(
   DB_FIELD_TYPE=>DB_DEF_STRING,
   DB_FIELD_LEN=>100),

3. Install Database Tables

1. Login to your website and go to the Admin Controls.
2. Click on the Install Tables link.
3. You should get the result user_address > Altered Existing Table.

You can verify this by returning to phpMyAdmin and view the user_address table to see if the 100 character state field has been added.

4. Modify the Edit Profile view

1. Open the file subsystems/lang/eng_US/subsystems/users/profileextensions/addressextension_contact.php:
2. Change:

'state'=>'State',
	'zip'=>'Zip Code',

To:

'state'=>'State/County',
	'zip'=>'Post Code',

Note: You should also modify the Address Book Module (see below).

Change State Length in the Address Book Module

The Address Book Module can be added to any page of an Exponent website. You can change the state length as follows:

1. Modify the Database

1. Open your Database Administration application, such as phpMyAdmin.
2. Load the Exponent Database which holds the data for your website.
3. Select and load the addressbook_contact (usually exponent_addressbook_contact).
4. Tick the box next to the field state.
5. Click the Drop (red X) link.
6. When prompted, confirm the table modification.

ALERT! DO NOT DROP the entire addressbook_contact table or you will lose the addresses already saved with the Address Book Module!

2. Modify the Database Definition File

1. Open the file datatypes/defititions/addressbook_contact.php:
2. Change line 46 from:

'state'=>array(
   DB_FIELD_TYPE=>DB_DEF_STRING,
   DB_FIELD_LEN=>2),

To:

'state'=>array(
   DB_FIELD_TYPE=>DB_DEF_STRING,
   DB_FIELD_LEN=>100),

3. Install Database Tables

1. Login to your website and go to the Admin Controls.
2. Click on the Install Tables link.
3. You should get the result addressbook_contact > Altered Existing Table.

You can verify this by returning to phpMyAdmin and view the addressbook_contact table to see if the 100 character state field has been added.

4. Modify the Edit Address view

1. Open the file subsystems/lang/eng_US/datatypes/addressbook_contact.php:
2. Change:

'state'=>'State/Province',

To:

'state'=>'State/County',

Note: You should also modify the User Profile Address (see above).

Getting Started Resources

• www.exponentcms.org
• About Exponent
• Exponent Download
• Exponent Download SourceForge
• Download Themes
• Download Modules
• Download Language Packs
• Installation Tutorial
• Upgrade Tutorial