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”}