Adding defaultConfig documentation to public api

3 files changed, 115 insertions, 2 deletions

diff --git a/api/dwb-js.7 b/api/dwb-js.7
index 9a323d9f..19635a6d 100644
--- a/api/dwb-js.7
+++ b/api/dwb-js.7
@@ -2,12 +2,12 @@
 .\"     Title: dwb-js
 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
 .\" Generator: DocBook XSL Stylesheets v1.77.1 <http://docbook.sf.net/>
-.\"      Date: 11/22/2012
+.\"      Date: 11/23/2012
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "DWB\-JS" "7" "11/22/2012" "\ \&" "\ \&"
+.TH "DWB\-JS" "7" "11/23/2012" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -3304,6 +3304,8 @@ The configuration for extensions is in \fB$XDG_CONFIG_HOME/dwb/extensionrc\fR an
 .sp
 Every extension must implement one function named init that takes one argument, the config for the extension\&. The function should return true if the extension was successfully loaded, false otherwise\&. Every extension also may implement a function end that will be called when an extension is unloaded\&. If an extension registers to signals and binds shortcuts the extension should unregister all signals and unbind all shortcuts in this function\&. init and end should be returned from the extension\&.
 .sp
+Additionally the returned object can also have an defaultConfig\-property, the value will be passed to extensions\&.getConfig before calling the init function\&.
+.sp
 .it 1 an-trap
 .nr an-no-space-flag 1
 .nr an-break-flag 1
@@ -3328,6 +3330,8 @@ function loadStatusCallback(w) {
   \&.\&.\&.
 }
 return {
+  defaultConfig : { foo : 37 },
+
   init : function (config) {
     if (config\&.foo > 36) {
       bar(config\&.foo);
@@ -3339,6 +3343,7 @@ return {
 
     return false;
   },
+
   end : function () {
     unbind("dobar");
     signals\&.disconnectByFunction(loadStatusCallback);
@@ -3373,6 +3378,45 @@ return {
 .RE
 .\}
 .RE
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBPublic api\fR
+.RS 4
+.sp
+Extensions that provide a public api can use provide or replace using the name of the extension\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+var myPublicFunction = function()
+{
+  \&.\&.\&.
+};
+
+return {
+  init : function(config)
+  {
+    provide("myExtensionName",
+    {
+      config : config,
+      method : myPublicFunction
+    });
+  },
+  end : function()
+  {
+    replace("myExtensionName");
+  }
+};
+.fi
+.if n \{\
+.RE
+.\}
+.RE
 .SH "SEE ALSO"
 .sp
 \fBdwb\fR(1) \fBdwbem\fR(1)
diff --git a/api/jsapi.7.txt b/api/jsapi.7.txt
index 86cfff58..8031c4a2 100644
--- a/api/jsapi.7.txt
+++ b/api/jsapi.7.txt
@@ -1684,6 +1684,9 @@ the extension should unregister all signals and unbind all shortcuts in this
 function.
 init and end should be returned from the extension.
 
+Additionally the returned object can also have an +defaultConfig+-property, the
+value will be passed to extensions.getConfig before calling the init function.
+
 ==== Example
 
 A extension called *foobar* in *$HOME/.local/share/dwb/extensions/foobar*:
@@ -1700,6 +1703,8 @@ function loadStatusCallback(w) {
   ...
 }
 return {
+  defaultConfig : { foo : 37 },
+
   init : function (config) {
     if (config.foo > 36) {
       bar(config.foo);
@@ -1711,6 +1716,7 @@ return {
 
     return false;
   },
+
   end : function () {
     unbind("dobar");
     signals.disconnectByFunction(loadStatusCallback);
@@ -1730,5 +1736,35 @@ return {
 };
 --------
 
+==== Public api
+
+Extensions that provide a public api can use provide or replace using the name of the extension. 
+
+====
+[source,javascript]
+--------
+var myPublicFunction = function() 
+{
+  ...
+};
+
+return {
+  init : function(config) 
+  {
+    provide("myExtensionName", 
+    {
+      config : config, 
+      method : myPublicFunction
+    });
+  },
+  end : function() 
+  {
+    replace("myExtensionName");
+  }
+};
+--------
+====
+
+
 == SEE ALSO
 *dwb*(1) *dwbem*(1)
diff --git a/api/jsapi.txt b/api/jsapi.txt
index 36824f2d..44ebcea0 100644
--- a/api/jsapi.txt
+++ b/api/jsapi.txt
@@ -2709,6 +2709,9 @@ the extension should unregister all signals and unbind all shortcuts in this
 function.
 +init+ and +end+ should be returned from the extension.
 
+Additionally the returned object can also have an +defaultConfig+-property, the
+value will be passed to extensions.getConfig before calling the init function.
+
 .Example
 
 A extension called *foobar* in +$HOME/.local/share/dwb/extensions/foobar+.
@@ -2725,6 +2728,8 @@ function loadStatusCallback(w) {
   ...
 }
 return {
+  defaultConfig : { foo : 37 },
+
   init : function (config) {
     if (config.foo > 36) {
       bar(config.foo);
@@ -2736,6 +2741,7 @@ return {
 
     return false;
   },
+
   end : function () {
     unbind(bar);
     signals.disconnectByFunction(loadStatusCallback);
@@ -2756,5 +2762,32 @@ return {
 --------
 ====
 
+Extensions that provide a public api can use provide or replace using the name of the extension. 
+
+====
+[source,javascript]
+--------
+var myPublicFunction = function() 
+{
+  ...
+};
+
+return {
+  init : function(config) 
+  {
+    provide("myExtensionName", 
+    {
+      config : config, 
+      method : myPublicFunction
+    });
+  },
+  end : function() 
+  {
+    replace("myExtensionName");
+  }
+};
+--------
+====
+
 
 // vim: set ft=asciidoc: