Site-wide customizing - ECB - the Emacs Code Browser
Description: ECB - the Emacs Code Browser

Previous: setq or customize, Up: General aspects

#### 7.1.2 Site-wide customizing of ECB

If you are the administrator for an Emacs-site, means you are responsible for the basic customization of a lot of Emacs users, then you maybe need a way to customize Emacs and ECB without changing everyones `.emacs`-file and normally you will do this with the file `site-start.el`. You can customize all options of ECB in a central `site-start.el` (even the options mentioned above!) but you MUST NOT do this via `setq` but you have to use a mechanism like the following1!

This section describes two methods how to pre-customize ECB site-wide. The elisp-code contained in the following two subsections has to be copied to the file `site-start.el` before it can be used.

But ensure for both methods that you customize the options with the correct lisp format. Read carefully the docstrings of the options you want to customize from within Elisp-code!

##### 7.1.2.1 Storing all option-settings in the users custom-file

The mechanism described here defines all site-wide-settings in a file `site-lisp.el` but stores the values in the users `custom-file` which is probably `.emacs`!

First two helper functions are needed, namely `customize-option-get-value` and `customize-save-variable-save` whereas the latter one sets the value for an option via the customize-mechanism (and is therefore allowed for the setq-forbidden options!) but only if the option has no saved value until now (i.e. the user has not saved this option for future sessions until now)

       (defun customize-option-get-value (option type)
         "Return the value of a customizable option OPTION with TYPE, where TYPE
       can either be 'standard-value \(the default-value of the defcustom) or
       'saved-value \(the value stored persistent by the user via customize)."
         (let ((val (car (get option type))))
           (cond ((not (listp val)) val)
                 ((equal 'quote (car val)) (car (cdr val)))
                 (t (car val)))))

       (defun customize-save-variable-save (option value &optional override)
         "Calls `customize-save-variable' with OPTION and VALUE if OPTION is a
       custom-type and if OPTION has no saved-value until now.
       If OVERRIDE is a function or lambda-form then it is called with two arguments:
       - OLD-SAVED-VAL: The saved value of OPTION
       - NEW-VALUE: see argument VALUE.
       OVERRIDE is only called if OPTION has already a saved-value. If OVERIDE
       returns not nil then `customize-save-variable' is called for OPTION with VALUE
       even if OPTION has no saved-value until now."
         (and (get option 'custom-type)
              (or (not (get option 'saved-value))
                  (and (functionp override)
                       (funcall override
                                (customize-option-get-value option 'saved-value)
                                value)))
              (progn
                (message "Overriding saved value for option %s with %s" option value)
                (customize-save-variable option value))))

With `customize-save-variable-save` all ECB-options can be site-wide pre-customized like follows:

       (customize-save-variable-save 'ecb-show-tags
                                     '((include collapsed nil)
                                       (parent collapsed nil)
                                       (type flattened nil)
                                       (variable collapsed name)
                                       (function flattened name)
                                       (rule flattened name)
                                       (section flattened nil)
                                       (def collapsed name)
                                       (t collapsed name)))
       (customize-save-variable-save 'ecb-font-lock-tags t)
       ;; add here more options of ECB it you want

##### 7.1.2.2 Using a special setq for site-wide settings

The mechanism above saves the pre-customized values always in the users `custom-file` (probably `.emacs`). If this is not preferred, then you can use the following mechanism but of course the offered `setq-save` is only allowed for options which are not setq-forbidden (see setq or customize).

The mechanism below does not change the users `custom-file`. This mechanism is needed especially if ECB should be autoloaded and all site-wide settings should first loaded when ECB is activated by the user. This can be achieved for example via2:

       (require 'ecb-autoloads))
       (eval-after-load "ecb"
         '(require 'site-ecb))

In such a situation the whole `custom-file` of a user is mostly loaded before ECB is activated and therefore before the site-wide-settings are loaded. So the users own customizations are loaded before the site-wide ones.

The `setq-save`-mechanism described below prevents the users own customisations contained in his `custom-file` from being overridden by the site-wide setq-settings. If `setq` would be used for the site-wide settings then in an autoload-situation the site-wide settings would override the users-settings and this should not be done!

First two helper-macros are needed:

       (defmacro custom-saved-p (option)
         "Return only not nil if OPTION is a defcustom-option and has a
       saved value. Option is a variable and is literal \(not evaluated)."
         `(and (get (quote ,option) 'custom-type)
               (get (quote ,option) 'saved-value)))

       (defmacro setq-save (option value)
         "Sets OPTION to VALUE if and only if OPTION is not already saved
       by customize. Option is a variable and is literal \(not evaluated)."
         `(and (not (custom-saved-p ,option))
               (set (quote ,option) ,value)))

With `setq-save` all “not-setq-forbidden”-ECB-options can be site-wide pre-customized like follows:

       (setq-save ecb-tree-indent 4)
       (setq-save ecb-tree-expand-symbol-before t)
       (setq-save ecb-primary-secondary-mouse-buttons 'mouse-1--mouse-2)

#### Footnotes

[1] At least for the options for which `setq` is explicitly forbidden, but it is recommended to use always such a mechanism

[2] The file `site-ecb.el` contains all site-wide settings for ECB