====== Customizing ======

<note warning>This page is for 1.x phpfreechat versions. For 2.x versions, check the [[:documentation:|documentation]]</note> 


phpFreeChat was developed with an aim of simplicity and flexibility.

Setting it up is relatively simple. All parameters are centralized in an array and passed as parameters on the instantiation of the phpFreeChat object.

===== Customization of the overall appearance (colors, sizes ...) =====

You need to create a new theme (for example ''mytheme'') :
  - Create a directory: ''phpfreechat/themes/mytheme/''
  - Create a new CSS stylesheet: ''phpfreechat/themes/mytheme/style.css.php''
  - Now insert CSS rules into this file, for example, to change the date/hours color to red: <code css>span.pfc_heure, span.pfc_date {
      color: red;
    }</code>
  - Setup the "theme" parameter in your chat script:<code php>$params["theme"] = "blune";</code>

As an examples, see these demos: [[http://www.phpfreechat.net/src/1.x/demo/demo28_blune_theme.php|1]], [[http://www.phpfreechat.net/src/1.x/demo/demo28_mini_blune_theme.php|2]]



===== Customization of the smileys list =====

Follow the above instructions for the theme creation. Then I suppose you have a directory "phpfreechat/themes/mytheme/".

  - Create a new smileys directory: "phpfreechat/themes/mytheme/smileys/"
  - Insert ping, jpeg or gif smileys images in the folder for example : "smiley1.png", "smiley2.gif", and "smiley3.jpg"
  - Create a file "phpfreechat/themes/mytheme/smileys/theme" and enter the keyboard to image mapping smileys description, for example :<code>
smiley1.png :) :-)
smiley2.gif :( :-(
smiley3.jpg :D :-D :o)</code> Each line begins with the image filename followed by the list of the string characters to replace by that image. Only use spaces to separate the smileys string matches.
  - Setup the "theme" parameter in your chat script:<code php>$params["theme"] = "mytheme";</code>

As an examples, see these demos: [[http://www.phpfreechat.net/src/1.x/demo/demo11_famfamfam_smiley_theme.php|1]], [[http://www.phpfreechat.net/src/1.x/demo/demo12_phoenity_smiley_theme.php|2]], [[http://www.phpfreechat.net/src/1.x/demo/demo17_cerutti_smiley_theme.php|3]], [[http://www.phpfreechat.net/src/1.x/demo/demo18_phpbb2_smiley_theme.php|4]]


===== Customization of the nick list =====

Each nicks in the list can be customized individually thanks to the [[:parameters#nickmeta|nickmeta]] parameter. These methods make possible to customize easily the nickname list:
  * ''buildNickItem_create_image(nickid)'': can be used to customize the little image near the nickname
  * ''buildNickItem_modify_nick_style(nickid, span)'': can be used to customize the nickname style

__Example__: in your theme create a file ''customize.js.php'' with the following content <code javascript>
pfcClient.prototype.buildNickItem_modify_nick_style = function(nickid, span) {
  span.style.color = this.getUserMeta(nickid, 'mycolor');
}

pfcClient.prototype.buildNickItem_create_image = function(nickid, span) {
      var className = (! is_ie) ? 'class' : 'className';
      var myicon = this.getUserMeta(nickid, 'myicon');
      var img = document.createElement('img');
      if (myicon)
        img.setAttribute('src', myicon);
      else
        img.setAttribute('src', this.res.getFileUrl('images/user.gif'));
      img.style.marginRight = '5px';
      img.setAttribute(className, 'pfc_nickbutton');
      return img;
}
</code>
This example will colorize the nick with the color given in the "mycolor" nickmeta. And the icon will be the one given in "myicon" nickmeta.

===== Customization of the "whoisbox" =====

The "whoisbox" is the small popup which shows the user's nick, a link to create a private chat, and all the extra nickmeta.

Thanks to these method, it is possible to customize the "whoisbox" content:
  * ''updateNickWhoisBox_ignored_field(k)'' : returns true if the "k" usermeta should be hidden
  * ''updateNickWhoisBox_append_html(nickid, div)'' : can be used to append data to the whoisbox (just before the private message link)
  * ''updateNickWhoisBox_prepend_html(nickid, div)'' : can be used to prepend data to the whoisbox (before any other usermeta)

__Example__: to add an avatar, just create the ''customize.js.php'' in your theme with this content <code javascript>
pfcClient.prototype.updateNickWhoisBox_ignored_field = function(k)
{
      return ( k == 'nickid' ||
               k == 'nick' || // useless because it is displayed in the box title
               k == 'isadmin' || // useless because of the gold shield icon
               k == 'floodtime' ||
               k == 'flood_nbmsg' ||
               k == 'flood_nbchar' ||
               k == 'avatar'
               );
}
    
pfcClient.prototype.updateNickWhoisBox_append_html = function(nickid, div)
{
    var className = (! is_ie) ? 'class' : 'className';
    
    // append the avatar image
    if (this.getUserMeta(nickid,'avatar'))
    {
      var img = document.createElement('img');
      img.setAttribute('src',this.getUserMeta(nickid,'avatar'));
      img.setAttribute(className, 'pfc_nickwhois_avatar');
      div.appendChild(img);
    }
}
</code>
Then the shown avatar will taken from the "avatar" usermeta. A such example is available online on the [[http://www.phpfreechat.net/src/1.x/demo/demo50_customized_usermetadata.php|demo50]].

===== Write a new command =====

A command is a php class. So, to write your own command, you need to write a new php class (as an example look at the "src/commands/nick.class.php" file).

Each command class inherit from a virtual "pfcCommand" class. This virtual class define the command interface. Currently the only virtual method to implement is: "function run(...)"

You have some API you can use to write your command:

  * pfcResponse (see "src/pfcresponse.class.php")
  * container (see "src/pfccontainer.class.php")
  * tools (see "src/pfctools.php")

FIXME

As an examples, have a look to this demo: [[http://www.phpfreechat.net/src/1.x/demo/demo64_customized_command.php|1]] (try to type "/roll 2d6")

===== Write a new proxy =====

A phpfreechat proxy is a class that will be instantiated each time a command is run. The proxy can stop and modify the handled commands. It can also create and run new commands. Thanks to the proxies, the chat default behavior can be customized a lot.

To start understanding the proxy mechanism, have a look to the easier proxy: [[http://phpfreechat.svn.sourceforge.net/viewvc/phpfreechat/trunk/src/proxies/log.class.php?view=markup|the log proxy]]. This proxy write down in a file all the posted message on each channels.

===== Write your own container =====

FIXME

As an examples, have a look to the default [[http://phpfreechat.svn.sourceforge.net/viewvc/phpfreechat/trunk/src/containers/file.class.php?view=markup|file container source code]] or to the [[http://phpfreechat.svn.sourceforge.net/viewvc/phpfreechat/trunk/src/containers/mysql.class.php?view=markup|mysql container source code]].