Setting up member only rooms.

In this tutorial we will show you how to set up rooms that are only available (or visible) in the member areas of your site.
hi
This is acheived by disabling/hiding the rooms from within the FCChat configuration. WordPress and Joomla users will access the FCChat configuration through their dashboards. Otherwise, the configuration will be accessed directly through the FCChat/config/config.js file. The three fields that apply are:


// CHAT ROOM PARAMS
	disabled_rooms:[],
	disabled_room_msg:"You must be a member to enter this room.",
	hidden_rooms:[],

disabled_rooms and hidden_rooms may each contain a comma separated list of rooms that are to be “deactivated” for non members. The difference between the two fields is that disabled rooms will still be visible to users in non member areas of your site- they just won’t be accessible.

You add some rooms to either list by entering the name of the room you wish to deactivate.

For example:

disabled_rooms:[‘The Lobby’,’Help Desk’],

This will disable the rooms The Lobby and Help Desk.

Once you have added some rooms to either the disabled_rooms or hidden_rooms list, these rooms will be inaccessible, by default, on all pages of your site. The next step, therefore, will be to activate the rooms on the member pages of your site.

Now, FCChat does not know where your member only pages or private pages are, so you will have to “tell” it. In order to do this, you will have to go to each of your member pages and insert a little code into the page, letting the chat know not to disable the room on that page.

The code must be placed on the page after the FCChat configuration has loaded. Usually, placing it before the closing </head> tag will suffice. The purpose of the code is override the hidden_rooms or disabled_rooms fields in order to remove the room from the disabled or hidden rooms list. Continuing with the example from above, let’s say now, that on a particular page, you wish to activate both ‘The Lobby’ and ‘Help Desk’.

You would insert the following code into the page:


<SCRIPT type="text/javascript">
FCChatConfig.disabled_rooms=[];
</script">

Basically, this just clears out the disabled_rooms list on that page, thereby making the rooms active again.

If you wanted to activate only ‘The Lobby’ but leave the ‘Help Desk’ inactive, you would alter the above code as follows:


<SCRIPT type="text/javascript">
FCChatConfig.disabled_rooms=['Help Desk'];
</script">

As you can see, only ‘Help Desk’ will be disabled on this page.

{“id”:”memberrooms”,”topic”:”Setting up member only rooms”}

Importing user profiles

This tutorial will show you how to import your user profiles into FCChat.

In FCChat, each user is automatically given a default profile page; however, this profile is not linked to or integrated with any external source.

If you have integrated your pre-existing user accounts with the chat. (See the User Guide’s section on account integration), you may wish to link your user’s pre-existing profiles as well.

In order to do this, you must edit the field import_profiles in the FCChat configuration.

You will enter into the import_profiles field the url of the page that will generate the profile. The URL needs to be constructed in such a way so that the user’s name can be appended to it. The page will take the user’s name and output the user’s profile accordingly.

Once you have done this, the chat will no longer use the default profile pages. Instead, when you click on profile, in the user’s dialog box, you will be taken to the page you specified in the import_profiles field.

For example, PHPBB profile pages can accept the user’s name as a parameter in the querystring, so in order to link your chat users to their PHPBB profiles, you would set import_profiles to
http://MYPHPBBFORUM/memberlist.php?mode=viewprofile&un=.

Of course, you would replace MYPHPBBFORUM with the path to your forum. When the profile is fetched, FCChat will automatically append the user’s name to the end of the URL, so that the “un=” part will become “un=USERNAME”, where USERNAME is the name of the particular user.

Unlike PHPBB (unfortunately), many systems do not have a default means of obtaining the profile directly from the user’s name. In this case you must create a script which will accomplish this task.

You will create the script so that it can accept the user’s name (in the querystring, for instance). Then, using that information, it will output the profile, or perhaps redirect to the profile page. The exact code required to write the script is system specific and outside the scope of this tutorial.

Place the script on your site, and link to it using the import_profiles field. Again, keep in mind, when setting up the URL to your script, that FCChat will append to this URL the user’s name.

{“topic”:”Importing user profiles”}

Custom Buttons for the Toolbar

This tutorial will show you how to add custom buttons to the FCChat Toolbar. With these buttons, you can add a like box, a twitter feed, or a search engine to the toolbar. You may also create buttons that add specialized functionality to your site, like a recent topics button, a website store button, etc.

There are 3 types of buttons that you can add:

1) Buttons that open a dialog box in the toolbar.
2) Buttons that open another page on your site.
3) Buttons that open a popup window.

Each button you add consists of 2 main elements – an icon, and some text. Both the icon and text are optional. You are responsible for providing the content page that the buttons link to.

We will begin by showing you how the “Like button” and the “Search” button that appear on the home page of this site (www.fastcatsoftware.com) were created. Both of these buttons are of the type 1 variety (above). We will then show you how to create type 2 and 3 buttons.

The first step in creating a custom button is to add the button code to the custom_buttons field in the FCChat Configuration. If you are using WordPress or Joomla, you will place your button code in the textarea provided on the configuration page. For all other installations, you will be editing the FCChat/config/config.js file directly. In this case, you will place your code between the braces of the

custom-buttons:{
},

field.

After creating the button code, you will then add the button to the toolbar_items field, also found in the FCChat Configuration. We will cover the syntax required to add the button to the toolbar_items list later, but first, lets take a look at generating the button code.

Google Search Button

Here is the button code for the Google search button that appears on our home page:

googlesearch:{
	menu_item:{
		width:85,
		icon:"http://www.fastcatsoftware.com/FCChat/current_skin/wp_search.png",
		text:"Search"
	},
	dialog_box:{
		width:450,
		height:350,
		title:"Search Fastcatsoftware",
		iframe_src:"http://www.fastcatsoftware.com/search.html"
	}
}


You would place this code in the custom_buttons field mentioned above. The syntax for the button code is Javascript object literal notation. I mention this because the syntax must be correct in order for the button to be displayed properly. Incorrect syntax may generate an error which will prevent the toolbar from showing up. This is especially true with regard to the placement of commas. Notice that each item in a list has a comma after it, except for the last one. Failure to place commas in the appropriate places can cause the toolbar to crash on some browsers. You must take the same care in placing quotation marks around values which require them.

That being said, let’s get back to what the code above does. Notice, first of all, that the code begins with word googlesearch. This is the name of the button, and you can basically name it anything you like. We could have called it goooglebutton or thegooglethingy, etc. (One caveat: letters, numbers, and underscores are allowed in the button name, but no spaces.)

The other fields in the button code define the appearance and behavior of the button. Some of these fields are required and some are optional. Let’s review what each of these fields accomplishes.

The menu_item section

Each button you create must have a menu_item section. The menu_item section provides FCChat with the information it needs to render the button in the toolbar. Within the menu_item section you may have the following fields:

width (required) The width, in pixels, of the button.

icon (optional) An image for your button. Enter the full URL to the button image file. It will be rendered as a 16X16 pixel image by default (this can be changed). This field is optional, and you may remove it from your button code if you wish.

text (optional) The text for your button. This field is optional, and you may remove it from your button code if you wish.

Here are some additional fields which you may want to add to the menu_item section.

icon_css (optional) A list of CSS properties (ie icon_css:”border:1px solid red;top:5px;left:20px;”) that can be used to alter the location, size, and display properties of the icon.

text_css (optional) A list of CSS properties (ie text_css:”font-family:arial;color:blue;”) that can be used to alter the location, size, display properties of the text.

The dialog_box section

Since the googlesearch button is a type 1 button (it opens a toolbar dialog box), it must contain a dialog_box section. You will omit the dialog_box section when coding type 2 and 3 buttons. The dialog_box section contains the following fields:

width (required) The width in pixels of the dialog box.

height (required) The height in pixels of the dialog box.

title (required) The title of the dialog box.

iframe_src (required) The URL of the page that should be rendered inside the dialog box. For our googlesearch button, we have set up an html page on our site with the Google Site Search function embedded in it (http://www.fastcatsoftware.com/search.html). We use the iframe_src parameter to link that page to our button’s dialog box.

Adding the like button

Now that we have seen the code for the Google search button, lets go ahead and add a second button – the like button – to the custom_buttons field.

The custom_buttons field now looks like this:

     googlesearch:{
	menu_item:{
		width:85,
		icon:"http://www.fastcatsoftware.com/FCChat/current_skin/wp_search.png",
		text:"Search"
	},
	dialog_box:{
		width:450,
		height:350,
		title:"Search Fastcatsoftware",
		iframe_src:"http://www.fastcatsoftware.com/search.html"
	}
    },
    like:{
	menu_item:{
		width:65,
		icon:"http://www.fastcatsoftware.com/FCChat/current_skin/facebook.png",
		text:"Like",
	},
	dialog_box:{
		width:320,
		height:330,
		title:"Our Friends on Facebook",
		iframe_src:"http://www.facebook.com/plugins/likebox.php?href=http%3A%2F%2Fwww.facebook.com%2Ffastcatsolutions&width=300&height=290&colorscheme=light&show_faces=true&border_color&stream=true&header=true&appId=204858386287047"
	}
    }

The like button contains pretty much the same fields as the googlesearch button. Notice that the iframe_src field now points to the URL for like box plugin, and that the width and height have been adjusted to conform to the dimensions of the like box.

Notice also, in the code above, that, at the very end of the googlesearch button code, there is now a comma, but at the end of the like button code (because it is last in the list) there is no comma. Every button you add must end in a comma except for the last one. I cannot stress this enough, because if you don’t put the commas in the right places, you will have major problems.

Adding the buttons to the toolbar

Ok, we are done creating the button code for our two buttons, but they are not going to show up in the toolbar yet. This is because we have not added them to the toolbar_items list. Let’s do that now.

The toolbar_items field is in the FCChat Configuration, right next to the custom_buttons field we have just finished editing. To add the buttons, you will insert custom_buttons:googlesearch and custom_buttons:like into the list, like this:

Before:

[“fullpage:logo”,”friendscenter”,”social_media:social_media”]

After:

[“fullpage:logo”,”custom_buttons:like”,”custom_buttons:googlesearch”,”friendscenter”,”social_media:social_media”]

You can place the buttons anywhere in the list. That is the order they will appear in the toolbar. The syntax for inserting buttons is always custom_buttons: followed by the name of the button, which is set when you create the button code.

Here is what the two buttons now look like when viewing the toolbar:

Custom buttons in toolbar

Each button opens its own dialog box. Here is what you may see after clicking the search button:

Custom search dialog

Creating type 2 and type 3 buttons

Now we will show you how to create buttons that link to another page or open a pop-up window.

Let’s start by creating a Main Page button. Here is the button code:


main:{
	menu_item:{
		width:80,
		text:"Main Page",
		href:"http://www.fastcatsoftware.com",
		newtab:true
	}
}

This button opens the main page of our site (in this case www.fastcatsoftware.com). We have omitted the icon field from this button, so only a text link will be displayed.

newtab (which is an optional field) is set to true, so that when you click on the button, the link will open in a different tab. Without the newtab parameter, the link would open on the same page.

href points to the URL that the button links to.

Let’s say that you want a button that opens up a pop-up window. Maybe a login button, or something.

Here is the code for that:


login:{
	menu_item:{
		width:75,
		text:"Sign in",
		href:"Javascript:void(0)",
		onclick:"window.open ('http:/MYLOGINURL','mywindow','menubar=1,resizable=1,top=300,left=300,width=350,height=250');"
	}
}

The onclick parameter holds the script to be executed when the button is clicked, in this case we are opening a pop-up.

The href parameter is set to Javascript:void(0) to suppress the buttons default behavior when clicked.

{“topic”:”Custom buttons for the toolbar”}

Quickstyling

This is a tutorial on quickstyling, which is a method of customizing the FCChat widget.

First, locate the quickstyling field in your FCChat configuration. It may appear slightly differently depending on whether you are editing the config.js file directly, or using the configuration page in your dashboard; but, at any rate, it should look something like this:

quickstyling:{
	alldomains:{
		widget:{
			background_css:"",
			width_prop_offsets:"0:0:0", //title : buttons : info box
			height_offset:0, 
			text_top_offset:0, 
			height_prop_offsets:"0:0:0", //title : buttons : info box
			width_offset:0, 
			logo_top_offset:0,
			logo_left_offset:0,
			logo_css:"",
			title_css:"",
			full_page_button_css:"",
			off_button_css:"",
			infobox_css:"",
			base_font_css:"",
			title_font_css:"",
			alert_css:"",
			link_css:"",
			link_hover_css:"",
			link_disabled_css:"",
			info_css:""
		},
		toolbar:{
			background_css:"",
			divider_css:"",
			width_prop_offsets:"0:0:0", //info box : buttons : minimized
			text_top_offset:0, 
                        off_button_left_offset:0,
			base_font_css:"",
			alert_css:"",
			link_css:"",
			link_hover_css:"",
			link_disabled_css:"",
			info_css:""
		},
		dialog:{
			border_css:"",
			title_background_css:"",
			title_css:"",
			link_css:""
		},
		application_window:{
			frame_color:"",
			title_css:""
		},
		full_page_css_obj:{
		}
	}		
}

The purpose of the quickstyling section is to allow you to quickly change the appearance and layout of your FCChat widget, without having to edit the style templates, or use the Template overrides API. Of course, quickstyling does not offer the level of control available in the later two methods, but it should be sufficient to meet the customization needs of most sites.

Edting the Fields

All the fields above that end with css take css style properties, for example:

background_css:”background-color:green;border:1px solid gray;”

If you are not familiar with css properties, here’s a good site to get started: www.w3schools.com/cssref/default.asp.

The fields that end with offest take numerical values, for example:

width_offset:20, or width_offset:-20,

Offsets add or subtract quantities from the default values. The second example above would subtract 20 from the default width.

width_proportion_offsets and height_proportion_offsets are special fields. They take three numerical values separated by colons.

Example: width_proportion_offsets:”10:-10:20″

These fields allow you to increase/decrease the dimensions of the embedded widget and toolbar, as the diagrams below illustrate.

For the widget…


And for the toolbar…

Another special field is full_page_css_obj, which takes css properties in json format, as shown below:

full_page_css_obj:{
     "background:color":"green",
     "border":"1px solid gray",
     "font":"12px arial"
}

Examples

Instead of going over what each individual field in the quickstyling section represents, we will provide you with some complete examples of the types of customizations you can make with quickstying, and you can use these as a springboard to create your own customizations.

Toolbar styling

First, we will change the styling of the toolbar by altering the toolbar section of the quickstyling code as follows


toolbar:{
	background_css:"background-color:lightgray;border: 1px solid gray;-webkit-box-shadow:none;box-shadow:none;", 
	divider_css:"background-color:gray;",
	width_prop_offsets:"50:50:50", //info box : buttons : minimized
	text_top_offset:0, 
        off_button_left_offset:0,
	base_font_css:"color:#444444;",
	alert_css:"color:red;",
	link_css:"color:blue;",
	link_hover_css:"color:purple;",
	link_disabled_css:"color:#bbbbbb;",
	info_css:"color:#444444;"
},

And here is the result:

Notes about this example:

All the CSS properties should end in a semicolon.

The background_css field is used to change the toolbar’s color and border. The shadow around the toolbar has been removed using this field.

The color of text has been changed. The default color is now dark gray (#444444). Link color has been changed to blue.

We have only changed the text color in this example, but you may change the size, font, and other properties as well. If you change the font size, you may find that the vertical alignment is a bit off. To correct this, change the value of text_top_offset. In addition, you may need to shift the off button over a bit. To do this, change the value of off_button_left_offset.

width_prop_offsets has been set to “50:50:50″. This inceases the width of the infobox, buttons section, and minimized toolbar by 50 pixels each. Here is a picture of what the toolbar now looks like in the minimized state:

Widget styling

Next, let’s change the styling of the widget by altering the widget section of the quickstyling code as follows


widget:{
	background_css:"background-color:#666666;border:4px solid lightblue;",
	width_prop_offsets:"0:0:0", //title : buttons : info box
	height_offset:0, 
	text_top_offset:0, 
	height_prop_offsets:"50:50:50", //title : buttons : info box
	width_offset:50, 
	logo_top_offset:0,
	logo_left_offset:0,
	logo_css:"display:none;",
	title_css:"left:10px;",
	full_page_button_css:"",
	off_button_css:"",
	infobox_css:"",
	base_font_css:"color:white;",
	title_font_css:"color:white;",
	alert_css:"color:pink;",
	link_css:"color:white;",
	link_hover_css:"color:yellow;",
	link_disabled_css:"color:#dddddd;",
	info_css:"color:lightblue;"
},

The result:

Explanation:

The background_css property is used to change the widget’s color and border.

The widget was widened by setting width_offset:50,

The color of text has been changed. The default color is now white. Text which displays info about the state of the chat is lightblue. We have only changed the color in this example, but you may change the size, font, and other properties of the text as well.

height_prop_offsets has been set to “50:50:50″. This inceases the height of the title, buttons, and infobox section by 50 pixels each. If the widget was configured for a horizontal layout (for instance, when using the template: widget_default_header.js), we would have wanted to change the width_prop_offsets instead.

The image for the logo has been hidden. This was achieved by setting logo_css:”display:none;”,. Also, the title text’s left property has been changed: title_css:”left:10px;”, to compensate for the absence of the logo.

Dialog and application window styling

Next up, we will add a little styling touch to the dialogs and application windows, by editing the dialog/application_window portion of the code. There aren’t a whole lot of options here, so if you need greater control over the styling of these elements, you will have to use one of the other styling methods, mentioned at the beginning of this tutorial. Here’s the code:


dialog:{
        border_css:"border:2px solid purple;",
	title_background_css:"background-color:purple",
	title_css:"color:yellow;",
	link_css:"color:yellow;"
},
application_window:{
	frame_color:"purple",
	title_css:"color:yellow;"
},

The result:

Explanation:

frame_color is a special field, in that it does not take a full CSS property. Instead it takes a single html color or color code.

Styling the full page chat

Finally, you can add some styling touches to the full page chat window by editing the full_page_css_obj field.

full_page_css_obj:{
     "background:color":"green",
     "font":"12px arial"
}

Explanation:

The style properties that you add to full_page_css_obj will be applied to the document body. This basically allows you to change the properties of the page background, and the style of the Welcome/Loading message. Here we are changing the background color of the page to green, and the font to 12px arial.

{“topic”:”Quickstyling”}

Changing the location (URL) of the Full Page Chat

In this tutorial, we show you how to change the url of the Full Page Chat. To use this tutorial, your must have php enabled on your site. This tutorial applies to version 3.0 and later.

The default location of the full page chat is something like

http://yoursite.com/wp-content/plugins/fcchat/html/chat/index.html

(and here we are using a WordPress site as the example).

The problem is that this exposes a long and ugly URL to the user. Wouldn’t it be better if the Full Page Chat URL was something more intuitive, like

http://yoursite.com/chat/

So how do you get from the nasty URL to the nice one? Here are the steps:

1) Create a folder named chat in the root of your site.

2) Copy the file ../fcchat/html/chat/index.php to the newly created chat folder.

3) Open the file you just copied with a text editor. Find the line that says:

$FCCHAT_BASE_URL=”http://YOURDOMAIN.COM/FCChat/”;

Edit this variable so that it contains the full path to the fcchat folder on your site. Given the example above. this would yield:

$FCCHAT_BASE_URL=”http://yoursite.com/wp-content/plugins/fcchat/”;

4) Finally, go to the FCChat configuration, and set the variable full_page_url to point to the location of your chat, in this case: http://www.yoursite.com/chat/

(You may omit index.php from the path as long as your server has been configured to recognize index.php as a default document. If not, you must append the filename to the path, ie. http://www.yoursite.com/chat/index.php)

{“topic”:”Changing the location of the full page url”}

Run FCChat as a Pop up Window.

UPDATE: As of version 3.0, the pop-up window has been eliminated in favor of the full page chat.

FCChat can be run as both an in-browser window, and as a pop-up window.

The pop-up window option is available from the options dialog:

In addition, it is posible to launch the chat directly into a popup window, when you press the “Open ChatCenter” button on your chat widget.

To enable this mode, go to the configuration file, FCChat/config/config.js and set the following option:

//Window modes
 popup_window_on_open:true, //Default in-browser window

{“topic”:”Run FCChat as a popup window”}

Using Template Overrides

This tutorial will show you how to use the Template Overrides API to make customizations to FCChat’s language and style templates. These customizations will be permanent, in the sense that they will persist from one version of FCChat to the next.

For WordPress, Joomla 1.6+, Drupal 7+, and PhpBB 3+ users, the template overrides function is located in the FCChat Settings page of your dashboard. You enter your overrides in the text-box which is marked, “Template Overrides”.

For all other users, the template overrides should be placed in the file global_config.js. Please read Using the Global Configuration File before continuing with this tutorial.


OK, now lets begin talking about the template overrides API

The first thing you need to know is that there is a small set of functions that you will use to make your customizations. And here they are:

setOption
mergeOption
mergeBlock
getCSSProp

The second thing you need to know is how to specify the option you want. We will go over that first, and then come back to the topic of using the functions above.

Referencing template options

In order to change an option within the template files, you need to determine which option it is that you want to change, and how to properly “address” that option.

You will need to open up the template file, with a text editor, and examine it’s contents. The style template files are located in the fcchat/styles/ folder, and the language templates, in the fcchat/languages/ folder.

Below is an excerpt from the style template: widget_default_sidebar.js. This template contains many of the styling options for the embedded widget box that appears in your sidebar. Notice that the option css has been highlighted in orange. This option controls the left/right positioning of the “On/Off” button on the widget box. The question now is – how do you reference this option in order to edit it?

FCChatConfig.styles.widget={
		control:{
			top:0, //for absolute positioning
			left:310, //"     "
			width:190,
			height:180,
			align_dialogs:true,
			css:"background-color:#eeeeee;-moz-border-radius: 5px;-webkit-border-radius: 5px;border-radius:5px;",
			logo:{
				top:10,
				left:10,
				css:""
			},
			title_box:{
				top:7,
				left:30,
				width:160,
				height:27,
				css:"background-color:transparent;",
				text:{
					css:widget_base_font+";font-weight:bold; font-size:13px;color:#777777;"
				}
			},
			status:{
				css:""
			},
			buttons:{
				top:35,
				left:10,
				width:180,
				height:30,
				default_css:widget_base_font+";text-decoration:none;",
				states:{
					link_css:"color:rgb(22, 125, 200);",
					hover_css:"color:darkblue;",
					disabled_css:"color:#aaaaaa;"
				},
				full_page_button:{
					css:""
				},
				on_off_button:{
					css:"margin-left:40px;"
				}
			},
			info_box:{
				top:65,
				left:10,
				width:180,
				height:120,
				css:"background-color:transparent;",
				linebreak:"
", text:{ css:widget_base_font, alert_css:widget_base_font + "font-weight:bold;color:green;", info_css:widget_base_font+"color:#444444;" } } },
In order to refer to this option, you must follow the “path” to the option, which has been highlighted in yellow. You create the full name of the option by piecing together all the parts of the path, and separating the parts with dots, like this:

FCChatConfig.styles.widget.control.buttons.on_off_button.css

If you want to change the value of this option to say, 20px, you can do something like this:

setOption("FCChatConfig.styles.widget.control.buttons.open_chat_button.left","margin-left:20px;");

Lets say that you want to change the background color of the widget box. You will reference the style attributes for the widget like so:

FCChatConfig.styles.widget.control.css

And you could do something like this, to change the background color to blue:

mergeOption("FCChatConfig.styles.widget.control.css","background-color:blue");

Using the template override functions

Now that you know how to reference the different options within a template, we will begin to talk about the 4 functions that I showed you in the beginning of the tutorial.

First off is setOption(option,value).

This is the simplest of the functions. It is used to alter the value of a single option. Some examples:

setOption("FCChatConfig.styles.widget.control.top",20);
setOption("FCChatConfig.styles.widget.control.buttons.states.link_css","color:blue");
setOption("FCChatConfig.txt.t1","visitor"); //language template

Next we have mergeOption(option,value).

mergeOption is used to merge (or combine) new values with the existing values of an option. To see this in action, let’s look again at one of the previous examples:

mergeOption("FCChatConfig.styles.widget.control.css","background-color:blue;");

The css option, as you can see from the excerpt above, contains quite a few css properties, but here, we only want to change the “background-color” property. mergeOption accomplishes this. When used with an option that contains a string of CSS properties, mergeOption updates the specified property, or properties, while leaving the others intact.

When used with an option that contains a numerical value, mergeOption adds or subtracts a specific quantity from the value. For instance,

mergeOption("FCChatConfig.styles.widget.control.left",100);

would add 100 to the current value of the option.

DO NOT use mergeOption when you simple want to replace a value, use setOption instead.

Third on the list of functions is mergeBlock(obj1,obj2).

mergeBlock is used to merge a whole block of options into an existing block. This option is for advanced users, or users with a strong familiarity with scripting and such. If you don’t fully understand what the merge is going to do, I recommend against using this option, because you could easily change options you did not intend to change. Also, use this function sparingly, as it makes your templates less flexible with regard to future updates.

Here is an example of how it works:

You set up a block of options, formatted in the exact same way as the template block you are trying to change, and insert your changes. In the following example, we are setting up a block in order to shift the widget box buttons over by 5 to the left. (Refer to the excerpt above for the original block):

var buttons={
    open_chat_button:{
	top:5,
	left:10
    },
    on_off_button:{
	top:5,
	left:140
    }
};

Next you call mergeBlock to merge the block with the existing block within the template, like this:

mergeBlock("FCChatConfig.styles.widget.control.buttons",buttons);

Notice that I did not include the “states” or “default_css” parts of the original block in my update block. It is not necessary to include all parts of the original block in your updates. You need only include those parts you with to change. In fact, including the top parameter in my block is a mistake, since I did not want to change its value. It should be removed and the block should be as follows:

var buttons={
    open_chat_button:{
	left:10
    },
    on_off_button:{
	left:140
    }
};

The mergeBlock function is basically just a wrapper for jQuery.extend(true,obj1,obj2), so you can refer to jQuery’s documentation for more info about the merging operation.

Lastly, there is the getCSSProp(option,prop,[true]) function.

This one is used to retrieve a single property from an option containing a string of css properties.

getCSSProp("FCChatConfig.styles.widget.control.topband.css","background-color");

The function, as used above, would return the value of the “background-color” property. If we go back to the excerpt in the beginning of the tutorial, the value returned would be “gray”.

The optional third argument of the function, when set to true, tells the function that we are requesting the numerical part of a property, like “10px”.

getCSSProp("FCChatConfig.styles.widget.control.css","border-radius",true)

This would return 5. Without the true part, the function would return “5px”.

A final example

We finish with an example of using the above functions in the Template Overrides textbox of your FCChat Settings Page (or alternatively, in the fcchat_template_overrides.js file):

/*Overrides the ChatCenter Window background color*/
setOption("FCChatConfig.styles.chat_window.frame.background_color","purple");
/*Elongate the toolbar by 100px, but only if the chat 
toolbar item is less than 550px.*/
if(FCChatConfig.styles.widget.toolbar_item.width<=550){
/*Add 100px to the default toolbar item width*/
mergeOption("FCChatConfig.styles.widget.toolbar_item.chatcenter_layout.width",100);
/*Ha ha. This is to show that you can mess up and enter a bad option 
and nothing will happen.*/
setOption("FCChatConfig.styles.widget.toolbar_item.hamburger.fries",100);
/*Add 100px to the default value of open_chat_button.left
*commented out
*mergeOption("FCChatConfig.styles.widget.toolbar_item.chatcenter_layout.open_chat_button.left",100);
*/
/*Add 100px to the default value of off_button.left
*commented out
*mergeOption("FCChatConfig.styles.widget.toolbar_item.chatcenter_layout.off_button.left",100);
*/
/*Set up a block*/
var layout={
    open_chat_button:{
        left:505
    },
    off_button:{
        left:600
    }
};
/*Merge the block above with the template. Pushes the Open Chatcenter 
and Off button 100px to the left.*/
mergeBlock("FCChatConfig.styles.widget.toolbar_item.chatcenter_layout",layout);
/*A shortcut name for the toolbar_item*/
var fctoolbar="FCChatConfig.styles.widget.toolbar_item.chatcenter_layout";
/*These last three merges add 100px to the default 
values of the options below.*/
mergeOption(fctoolbar + "info_box.css","width:" + (getCSSProp(fctoolbar + "info_box.css","width",true)+100) + "px;");
mergeOption(fctoolbar + "status.css","left:" + (getCSSProp(fctoolbar + "status.css","left",true)+100) + "px;");
mergeOption(fctoolbar + "divider.css",";left:" + (getCSSProp(fctoolbar + "divider.css","left",true)+100) + "px;");
} /*This complete the elongation of the toolbar by 100px.*/

I hope this helps you understand a bit more how to use the Template Overrides function. If you have questions or comments, leave them below, or contact me at support@fastcatsoftware.com

{“topic”:”Using template overrides”}