Changes

<div class="CHAPTER">

<div class="CHAPTER">

=Getting to know how to customize the SME Server=

==Getting to know how to customize the SME Server==

Once you have studied the architecture of the SME Server, it is best to try to make some small customizations to become comfortable with the concepts. The number one rule to remember is: customizations always involve <span class="emphasis">''adding''</span> files to the server, rather than modifying existing files. This is very important, as it enables customizations to be easily packaged, and mixed and matched. The unique architecture of the SME Server enables virtually anything to be customized by adding a file in the correct location.

Once you have studied the architecture of the SME Server, it is best to try to make some small customizations to become comfortable with the concepts. The number one rule to remember is: customizations always involve <span class="emphasis">''adding''</span> files to the server, rather than modifying existing files. This is very important, as it enables customizations to be easily packaged, and mixed and matched. The unique architecture of the SME Server enables virtually anything to be customized by adding a file in the correct location.

----

----

==Exercise 1: Changing a configuration template==

===Exercise 1: Changing a configuration template===

Let us say that you wish to customize your server so that it runs a specified program every twenty minutes. To simplify the problem, let us assume that this program simply adds a line of dots to the log file (<tt class="FILENAME">/var/log/messages</tt>), i.e.:

Let us say that you wish to customize your server so that it runs a specified program every twenty minutes. To simplify the problem, let us assume that this program simply adds a line of dots to the log file (<tt class="FILENAME">/var/log/messages</tt>), i.e.:

----

----

==Exercise 2: The magic of templates==

===Exercise 2: The magic of templates===

For the next exercise, let us build on the first one. You have already created an exciting (o.k. not that exciting) new capability - the ability of the server to write dots into the log file. Let us now take advantage of the fact that the template processor can fill in values from the configuration database.

For the next exercise, let us build on the first one. You have already created an exciting (o.k. not that exciting) new capability - the ability of the server to write dots into the log file. Let us now take advantage of the fact that the template processor can fill in values from the configuration database.

----

----

==Exercise 3: Using events and actions==

===Exercise 3: Using events and actions===

In the SME Server, <span class="emphasis">''events''</span> are like <span class="emphasis">''callbacks''</span> in a programming language. The system signals an event whenever something interesting happens (e.g. a user is added, the IP address changes, etc.), which automatically executes all programs in the event directory. Therefore, any applications which need to know when a certain event is happening simply create a symbolic link from the event directory to a <span class="emphasis">''handler''</span> program, which will get executed whenever the event occurs.

In the SME Server, <span class="emphasis">''events''</span> are like <span class="emphasis">''callbacks''</span> in a programming language. The system signals an event whenever something interesting happens (e.g. a user is added, the IP address changes, etc.), which automatically executes all programs in the event directory. Therefore, any applications which need to know when a certain event is happening simply create a symbolic link from the event directory to a <span class="emphasis">''handler''</span> program, which will get executed whenever the event occurs.

----

----

==Exercise 4: Adding new configuration database parameters==

===Exercise 4: Adding new configuration database parameters===

New system configuration parameters can be spontaneously invented and added to the configuration database at any time. For example, let us return to our earlier exercise and parameterize the time interval for the log messages by introducing a new parameter called <tt class="FILENAME">LogInterval</tt>.

New system configuration parameters can be spontaneously invented and added to the configuration database at any time. For example, let us return to our earlier exercise and parameterize the time interval for the log messages by introducing a new parameter called <tt class="FILENAME">LogInterval</tt>.

----

----

==Exercise 5: Adding a user interface screen==

===Exercise 5: Adding a user interface screen===

Let us add a nice user interface screen to adjust the logger interval. Create a new file called <tt class="FILENAME">/etc/e-smith/web/functions/loggerdemo</tt>, with the following contents:

Let us add a nice user interface screen to adjust the logger interval. Create a new file called <tt class="FILENAME">/etc/e-smith/web/functions/loggerdemo</tt>, with the following contents:

----

----

===Adding localizations===

====Adding localizations====

The SME Server is designed to support localization into any language. This is done by small files which describe the mapping from the upper case tags (seen above) to the appropriate words for the local language. Enter the following into <tt class="FILENAME">/etc/e-smith/locale/en-us/etc/e-smith/web/functions/loggerdemo</tt>

The SME Server is designed to support localization into any language. This is done by small files which describe the mapping from the upper case tags (seen above) to the appropriate words for the local language. Enter the following into <tt class="FILENAME">/etc/e-smith/locale/en-us/etc/e-smith/web/functions/loggerdemo</tt>

----

----

==Exercise 6: Adding a new event type==

===Exercise 6: Adding a new event type===

Let us continue building on this example. Let us say that you want to add a hook to the logger demo, enabling other third party applications to receive a notification whenever the logger settings are changed. We need a new event type for this. Let us create a new event called <var class="LITERAL">loggerdemo-update</var><nowiki>:</nowiki>

Let us continue building on this example. Let us say that you want to add a hook to the logger demo, enabling other third party applications to receive a notification whenever the logger settings are changed. We need a new event type for this. Let us create a new event called <var class="LITERAL">loggerdemo-update</var><nowiki>:</nowiki>

----

----

==Exercise 7: Thought experiment - adding a new server application==

===Exercise 7: Thought experiment - adding a new server application===

You have now learned most of the machinery required for integrating a new server application into the SME Server. Consider a hypothetical chat server, with a configuration file called <tt class="FILENAME">/etc/chatserv.conf</tt>.

You have now learned most of the machinery required for integrating a new server application into the SME Server. Consider a hypothetical chat server, with a configuration file called <tt class="FILENAME">/etc/chatserv.conf</tt>.

----

----

==Customization guidelines==

===Customization guidelines===

When creating applications:

When creating applications: