A gconf schema is a special gconf key that sets the type and default value for some other gconf key. They are stored in the gconf database under the /schemas directory.

You will need to create a gconf schema for you module. This is needed at least to integrate your module within the framework. By means of this schema your module could be instanced. So the first thing you should do is to associate the given name for your module and its proper perl module. Let's look at an example to clarify this idea a little further.

Say we have a module called foobar, and the implementation for this module lies in EBox::Foobar. Your gconf schema would look something like this:

<gconfschemafile>
<schemalist>
	<schema>
		<key>/schemas/ebox/modules/global/modules/foobar/class</key>
		<applyto>/ebox/modules/global/modules/foobar/class</applyto>
		<owner>ebox</owner>
		<type>string</type>
		<default>EBox::Foobar</default>
		<locale name="C"/>
	</schema>
</schemalist>
</gconfschemafile>

Once you have done this, anytime you instance the module foobar using the method modInstance from EBox::Global, it will know that it has to load and instance the class EBox::Foobar.

my $foobar = EBox::Global->modInstance('foobar');
$foobar->some_method();

Gconf schemas become useful to establish default values. These values will be used by the system when the user has not set a value for the corresponding key.

There is an obvious scenario in which you might be interested in using this feature. This is when your module is installed for the first time, it could come in handy to set default values for your initial configuration.

Let's illustrate this with a simple example. Imagine you are providing a module to manage a HTTP proxy. One of the configurable parameters is the listening port. You want the user to have the capability to change it, but also you wish to provide 3128 as an initial value. Gconf schema is the right place to do it. For this example we would use the key /schemas/ebox/modules/proxy/port.

<schema>
	<key>/schemas/ebox/modules/proxy/port</key>
	<applyto>/ebox/modules/proxy/port</applyto>
	<owner>ebox</owner>
	<type>int</type>
	<default>3128</default>
	<locale name="C"/>
</schema>

It is likely your module configuration depends on some other modules. If this occurs to your module, you will be interested in being notified anytime that there is a change in any of the modules you depend on.

Continuing with the example used earlier, consider you want to configure the proxy for listening solely on the internal interfaces. The network module is the one which deals with the network interfaces. So at the time of generating the configuration for the proxy we will ask the network module for the network interfaces configured as internal. This raises an obvious issue, your module should regenerate its configuration whenever the internal interfaces change, that is, when the network module's configuration is changed.

In order to express this relationship of dependence we will use your module's gconf schema as follows:

<schema>
	<key>/schemas/ebox/modules/global/modules/proxy/depends</key>
	<applyto>/ebox/modules/global/modules/proxy/depends</applyto>
	<owner>ebox</owner>
	<type>list</type>
	<list_type>string</list_type>
	<default>[network]</default>
	<locale name="C"/>
</schema>

The above snippet tells the module global that proxy depends on network. This way, global will run the method _regenConfig from EBox::Proxy when the network module's configuration changes.