SurgeWeb Advanced Customisation

It is strongly recommended not to change anything in the surgeweb/tpl directory. This page will show you how you can do advanced customisation without needing to modify the tpl directory.

You can enable the extension css and javascript instead. These will allow you to override any surgeweb core CSS declarations or replace any native surgeweb javascript functions. You can customise any core surgeweb javascript function. Either by replacing it or more likely "hook" them by providing your own intermediate level of functionality which then calls the core surgeweb code in order to do the core interface actions.

"I want to change logos, colours and 'look and feel' of the interface."

You probably should not be looking at the advanced customisation techniques but be looking at the standard customisation page. The admin interface surgeweb customisation page allows you to change much of the look and feel without needing to consider html, css, and javascript. Also you can use skins to define a set of styles to be applied to multiple domains

"Ok, but I really, really want to change more than that."

Below are the recommended ways of making these changes to keep your life easy during surgemail upgrades. If there is something you want to change that you cannot, please contact surgemail-support@netwinsite.com with a description of what you would like to be able to change and why.

If netwin staff are troubleshooting your system for surgeweb problems and advanced customisation has been applied, one of the first tests will be to test with customisation disabled. This will preferably be done using the surgemail.ini setting surgeweb_custom for this purpose, or if necessary by copying the original files back into the surgeweb/tpl directory.

Here is a list of things other admins have wanted to do. If you do them as described below they will remain intact on surgemail upgrades:

I don't want users to adjust their advanced preferences

The advanced options and customisation pane in the preferences will not be displayed if you add this to any config_*.dat file:

 lock_options_basic true

I want to hide advanced "disable smarts or restore older behaviour" preferences

Add this to any config_*.dat file:

 lock_options_advanced true
and the following to extend.css
 .nosmart{
 	display:none;
  }

Users should not be able to modify their reply name

To any config_*.dat file add:

 lock_name_auth true

Users should be able to modify their reply email address

By default users are not allowed to spoof their from header reply email addres. To allow users to set, add the following setting to the users' _user.dat file or to any config_*.dat file:

 allowed_from *
or
 allowed_from *@mydomain.com

I always want the quota displayed

A quota warning will be displayed if you go over 80%, this is normally hidden to keep the interface clean. This can be always shown by adding this to any config_*.dat file:
 always_show_quota true

Display filestore as well as / instead of photos button in application menu

In extend.css add the relevant style definitions below:

 #app_filestore{
 	display:block;
 }
 #app_photos{
 	display:none;
 }

Remove Calendar / Photos / Blogs Application menu buttons

Calendar and photos can be hidden by disabling surgeplus using the surgemail.ini setting:

 g_disable_surgeplus "TRUE"
or by using user_access settings
!surgeplus
Blogs can be hidden using the user_access setting
 !blogs

Remove the remember me login box on the front login page

In extend.css add:

 #remember_me{
 	display:none;
 }

I want the help links to point at my own website

Setup your own pages of the same name and point all the surgeweb help links at that using the follwoing setting in any config_*.dat file:

 help_url http://mywebsite.com

I want a shared addressbook to be displayed

A variety of options are available for shared addressbooks. Either Global / Domain surgeweb addressbooks or LDAP or Authentication database based addressbooks. These are configured using the abook page in the surgemail admin interface:
 abook name="Global" read="!*" write="!*" type=""
 abook name="Domain" read="!*" write="!*" type=""
 abook name="LdapAbook" read="*" write="" type="ldap"
 abook name="AuthentAbook" read="*" write="" type="auth"
 abook name="Surgeweb" read="*" write="" type=""

I do not want any shared addressbooks to be displayed

Make sure the users do not have access to any addressbooks you have defined in surgemail.ini. To remove the Global and Domain addressbooks set:
 abook name="Global" read="!*" write="!*" type=""
 abook name="Domain" read="!*" write="!*" type=""

I do not want to offer labels in surgeweb

Labels functionality can be disabled by adding this to any config_*.dat file:
 labels_disable true

I do not want to display any snippets

Message body snippets functionality can be globally / per domain disabled by adding this to any config_*.dat file:
 snippets_disable true

I want different / no default groups in the contacts management

The default groups can be defined using this setting in any config_*.dat file:
 contact_groups Friends,Family,Colleagues
or
 contact_groups Foo,Bar
or
 contact_groups

I want to remove the raw user.cgi settings

The raw user.cgi settings on the "Options - Preferences - Filtering and Spam Control" page already get hidden if g_user_access / user_access settings are used to disable spam handling. To always hide, add this to extend.css:

 .raw_user_cgi{
 	display:none;
 }

Remove surgeweb spam handling disabled warning

The warning "some SurgeWeb spam control options disabled by administrator" is displayed on the "Options - Preferences - Filtering and Spam Control" page if the recommended surgemail spam handling techniques have been disabled. If for example you have your own spam handlign technniques in place, this wanring can be removed by adding this to extend.css:
 #opt_fs_disabled_warn{
 	display:none;
 }

Remove processing actions on Filtering and Spam control Page

This functionality can be enabled / disabled using g_user_access / user_access / the authentication databse user_access fields and they will be removed from display in surgeweb:

 relevant fields: fwd, fdwonly, exceptions, friends, spam

Remove the processing actions link

To remove the "Check the delivery log for a record of processing actions" link on the "Options - Preferences - Filtering and Spam Control" page, add this to extend.css:

 #opt_fs_log{
 	display:none;
 }

Remove the display of running surgemail version

To remove the "Options - Preferences - Advanced" page current surgemail version, add this to extend.css:

 #opt_adv_version{
 	display:none;
 }

Modify the banner image in mobile interface

 config_domain.dat add:
      mobile_custom_banner true
 and you place your modified logo image in
      surgeweb/custom/banner_mobile.jpg
 or
      surgeweb/custom/your_domain/banner_mobile.jpg

Arbitrarily modify mobile template

Enable mobile customisation using config_*.dat setting of: (Surgemail 5.3c-24+)
 mobile_custom true
Then create _mobile_custom.htm file in surgeweb/custom (and optionally in surgeweb/custom/domain.com). This allows you to arbitrarily modify the icon url or completely override and replace the content on individual top level template pages.
eg.
 # modify the banner image url as we see fit if needed, here are two examples
 #||define((mobile_banner),concat((/whatever?domain=),domain_ex,(&img=banner_mobile.jpg)))||
 #||define((mobile_banner),(https://netwinsite.com/img2/logo_med_onwhite.png))||

 # Example of overriding the whole template output of any of the top level pages in
 # the surgeweb/tpl/mobile directory
 ||if(equal(page,(sw.htm)))||
 	Yes!! Own template output :-)

 #	Should base page content on the original file sw.htm in surgeweb/tpl/mobile directory
 #	Can even include a template from the original surgeweb/tpl/mobile directory if we want
  	||include||../tpl/mobile/_msgs.htm||

	</body>
	</html>
	||template_exit()||
 ||endif||
Note: This mechanism for template customisation without making changes to the tpl directory can be used on the html interface as well using the settings of "html_custom true" and "_html_custom.htm" file.

I want the change password button to go to my own interface

Enable extend.js and enable this code:
 # Hook the usercgi dialog function to do some of our own handling instead
 if(true){
     hook_user_cgi_dlg();
 }
 # Store original function and replace with our own one. In this case do our own action if it was the password button
 var user_cgi_dlg_orig;
 function hook_user_cgi_dlg()
 {
     user_cgi_dlg_orig=user_cgi_dlg;
     user_cgi_dlg=function(type){
         if (type=='password'){
             open_popup2('https://my.server.name/public/changepass.aspx');
             return;
         }
         user_cgi_dlg_orig(type);
     }
 }
 

I want to hide the change password button

There are two ways. Either set !pass in the accounts user_access settings in the authentication database, or add this to extend.css:
 #opt_gen_change_password{
 	display:none;
 }

I want my own link(s) to the right of the username at the top of the page

Add this to extend.js.
 var node=dge('link_bar').childNodes[2];
 var frag=document.createElement('span');
 frag.innerHTML=' <a href="https://netwinsite.com">MyLink</a> | ';
 node.parentNode.insertBefore(frag,node);

I want to customise the folder icon

Add an appropriate image to your custom directory and then add a rule with appropriate offsets to extend.css. (currently the default file you may want to base your icons on is surgemail\surgeweb\tpl\shared\img\vbtn_icons.gif)
 .folder_icon{
    background: url(vbtn_icons.gif?||vz||) no-repeat 0 -80px;
 }

I want to change the folder list text colors

This may yet be changed to simplify it but adding these to custom.css will allow you to customise this currently.
# Base folder name colours
 ul.ftree{
    color:blue;
 }

# Colors associated with folder list selection handling
 .ftree .selected, .ftree .hover_js, .ftree .hover_js a, .ltree .selected, .ltree .hover_js {
    color:blue;
 }
 ul.ftree .selected a {
    color:blue;
 }
 #folders .part_cursor:hover, #folders .part_cursor:hover a {
    color:blue;
 }

# Labels and Searches text color
 .green_text{
    color:blue;
  }

I want to hide the report via email button

To custom.css add: (Surgemail 5.0h-10+)
 .fault_report_button{
  	display:none;
  }

I want right column on login page too

To config_*.dat add: (Surgemail 5.2d-3+)
	rcol_login Some text
or iframe based:
	rcol_login iframe
	rcol_login_url https://netwinsite.com
and in extend.css customise rcol_login_outer and rcol_login_iframe for positioning etc as needed.

My security audit requires login page autocompletion to be disabled

To config_*.dat add: (Surgemail 5.3c-26+)
 disable_login_autocomplete true

I would like to add my own hints to the surgeweb hints

The surgeweb hints system (Surgemail 5.3i-67+) is easily customisable with your own hints. To do so you will need to do two things:
1) Define the actual hint strings in one of your lang.dat files (eg custom/lang.dat)
 st_hint_custom_01  Hint: The My Company mailserver documentation can be found <a href="http://mycompany.none/page.htm" target="popup">here</a> and is maintained by John Doe
 st_hint_custom_02  Hint: This rather important thing our My Company users should know about...
2) Define the strings id numbers you want to get shown using a setting in config_*.dat
 custom_hints_show 01,02
Note: a maximum of 32 custom hints are available and the numbers must be two digits (ie 1-9 are zero prefixed)

I would like to hide some / all of the hints

System hints can be individually disabled using the following config_*.dat setting, where the numbers refer to the hint numbers as defined in surgeweb/tpl/lang.dat:
 system_hints_disable 01,02,05
Disable the hints system completely using (surgemail 6.0b-4+) [and 6.0a3-3(patched)]:
 all_hints_disable true

I would like to customise the idle autologout

Idle autologout can be enforced for all users of a domain / globally using config_*.dat setting of: (surgemail 6.0b-4+)
 autologout_enforced true
Alternatively assign the default duration (in minutes) and default state for new users [on|off] using these config_*.dat settings:
 autologout_duration 30
 pref_autologout_type on

I would like to disable Extras tab

The extras tab in preferences (introduced surgemail 6.0b-5+) can be disabled in part or completely, at the surgeweb level using comma separated entries as follows [all|legal|notify|lists|import|alias] eg
 extras_disable all
or
 extras_disable legal,alias
None: Extras tab also only shows the relevant entries when allowed to as per user_access authentication database permissions

How do I know which server of a mirrorred pair am I connected to

You can use ||machine_name|| in the "login_post_comment" variable (all versions) or in the "footer" variable (surgemail version 7.2m-7+) to identify which host of a mirrorred pair you are connected to.

What else can I do with this?

Here is an example of a very different application menu. The menu has been moved to the topleft instead of bottom left and is image based. To try this, enable extend.css and extend.js, then uncomment this is code in extend.js:
 if(true){
     move_panel_to_top('app_menu')
     alternate_menu();
 }
Or alternatively here the creation of panels on the left say with your own content in it. Here are several examples from extend.js:
 #	New fancy panel at the bottom with title and body text. Again can have anything in it
 new_panel_fancy('My own panel header', 'Fancy panel body with anything in it','bottom');

 #	New fancy panel at the bottom with live maps as an example
 var content='<iframe id="a_map" src="http://wikimapia.org/s/#lat=-40.7805414&lon=173.8476563&z=4&l=0&m=a&v=1"
		 width="'+lc_width()+'" height="200" frameborder="0" style="background:||lpanel_color||"></iframe>';
 new_panel_fancy('Wikimapia!! <i><a href="http://wikimapia.com"
		 target="_popup">link</a></i>',content,'bottom',true);

 #	New fancy panel at the bottom with youtube content as an example
 var content='<object width="'+lc_width()+'" height="200"><param name="movie"
         value="http://www.youtube.com/v/Pfs4Rd5f_IQ&hl=en&fs=1"></param>'+
         '<param name="allowFullScreen" value="true"></param>'+
         '<embed src="http://www.youtube.com/v/Pfs4Rd5f_IQ&hl=en&fs=1"
         type="application/x-shockwave-flash" allowfullscreen="true"'+
         ' width="'+lc_width()+'" height="200"></embed></object>';
 new_panel_fancy('Youtube!!',content,'bottom',true);

Emergency disabling behaviour for performance reasons

Some of surgeweb's more cpu and disk io intensive smarts can be globally disabled.
Warning this should only be done for troubleshooting reasons generally - and probably only as a last resort if you have investigated all other sources diskio and cpu bottlenecks.
# Globally disable inbox caching. Anyone saving preferences with this enabled will set
# their account's inbox caching to disabled in their own preferences. This will remain
# disabled unless the user re-enables.
global_nocache true

# Globally disable new mail checks. Anyone saving preferences with this enabled will set
# their account's inbox caching to disabled in their own preferences. This will remain
# disabled and the user is not able to re-enable, so requires editing of _user.dat to
# re-enable new mail checks.
global_nocheck true



Anyway, as I said at the start of the page. Any customisation done this way will remain intact on surgemail upgrades. Please contact us on surgemail-support@netwinsite.com if you have something you feel you need to customise and currently cannot, explainng exactly what you want to do and why.

Marijn