Apache OpenOffice Wiki - User contributions [en]

Documentation/DevGuide/ProUNO/Bridge/Value Objects

2011-03-29T10:37:40Z

Jl:

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2c=block
|ABridgeSvcMgr=block
|ABridgeTM=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Bridge/Client-Side Conversions
|NextPage=Documentation/DevGuide/ProUNO/Bridge/Exceptions and Errorcodes
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/Bridge/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Value Objects}}
==The Automation Value Object==
The object can be obtained from any uno object by calling the Bridge_GetValueObject on it. It holds a value and a type description, hence it resembles a UNO any or a VARIANT. A Value Object can stand in for all kinds of arguments in a call to a UNO method from a automation language. A Value Object is used when the bridge needs additional information for the parameter conversion. This is the case when a UNO method takes an any as argument. In many cases, however, one can do without a Value Object if one provides an argument which maps exactly to the expected UNO type according to the default mapping. For example, a UNO method takes an any as argument which is expected to contain a short. Then it would be sufficient to provide a Long in Visual Basic. But in JScript there are no types and implicitly a four byte integer would be passed to the call. Then the any would not contain a short and the call may fail. In that case the Value Object would guarantee the proper conversion.

A Value Object also enables in/out and out parameter in languages which only know in-parameters in functions. JScript is a particular case because one can use Array objects as well as Value Objects for those parameters.

A Value Object exposes four functions that can be accessed through <code>IDispatch</code>. These are:
<source lang="idl">
void Set( [in]VARIANT type, [in]VARIANT value);
</source>
Assigns a type and a value.
<source lang="idl">
void Get( [out,retval] VARIANT* val);
</source>
Returns the value contained in the object. Get is used when the Value Object was used as inout or out parameter.
<source lang="idl">
void InitOutParam();
</source>
Tells the object that it is used as out parameter.
<source lang="idl">
void InitInOutParam( [in]VARIANT type, [in]VARIANT value);
</source>
Tells the object that it is used as inout parameter and passes the value for the in parameter, as well as the type.

When the Value Object is used as in or inout parameter then specify the type of the value. The names of types correspond to the names used in UNO IDL, except for the “object” name. The following table shows what types can be specified.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Name (used with Value Object)
!UNO IDL
|-
|char
|char
|-
|boolean
|boolean
|-
|byte
|byte
|-
|unsigned
|unsigned byte
|-
|short
|short
|-
|unsigned short
|unsigned short
|-
|long
|long
|-
|unsigned long
|unsigned long
|-
|string
|string
|-
|float
|float
|-
|double
|double
|-
|any
|any
|-
|object
|some UNO interface
|}

To show that the value is a sequence, put brackets before the names, for example:
<source lang="idl">
[]char - sequence<char>
[][]char - sequence < sequence <char > >
[][][]char - sequence < sequence < sequence < char > > >
</source>
The <code>Value Objects</code> are provided by the bridge and can be obtained from the service manager object. The service manager is a registered COM component with the ProgId “com.sun.star.ServiceManager” ([[Documentation/DevGuide/ProUNO/Bridge/The Service Manager Component|The Service Manager Component]]). For example:
<source lang="javascript">
// JScript
var valueObject= objSericeManager.Bridge_GetValueObject();
</source>
To use a <code>Value Object</code> as in parameter, specify the type and pass the value to the object:
<source lang="idl">
// UNO IDL
void doSomething( [in] sequence< short > ar);
</source>
<source lang="javascript">
// JScript
var value= objServiceManager.Bridge_GetValueObject();
var array= new Array(1,2,3);
value.Set("[]short",array);
object.doSomething( value);
</source>
In the previous example, the <code>Value Object</code> was defined to be a sequence of short values. The array could also contain <code>Value Objects</code> again:
<source lang="javascript">
var value1= objServiceManager.Bridge_GetValueObject();
var value2= objServiceManager.Bridge_GetValueObject();
value1.Set("short“, 100);
value2.Set("short", 111);
var array= new Array();
array[0]= value1;
array[1]= value2;
var allValue= objServiceManager.Bridge_GetValueObject();
allValue.Set("[]short“, array);
object.doSomething( allValue);
</source>
If a function takes an out parameter, tell the <code>Value Object</code> like this:
<source lang="idl">
// UNO IDL
void doSomething( [out] long);
</source>
<source lang="javascript">
// JScript
var value= objServiceManager.Bridge_GetValueObject();
value.InitOutParam();
object.doSomething( value);
var out= value.Get();
</source>
When the <code>Value Object</code> is an <code>inout</code> parameter, it needs to know the type and value as well:
<source lang="idl">
//UNO IDL
void doSomething( [inout] long);
</source>
<source lang="javascript">
//JScript
var value= objServiceManager.Bridge_GetValueObject();
value.InitInOutParam("long", 123);
object.doSomething(value);
var out= value.Get();
</source>

==UNO Value Object (as of OOo 3.4)==
The UNO Value Object is basically the same as the Automation Value Object. It can be provided as argument in calls on automation objects. The value object is an uno service and implements <idl>com.sun.star.bridge.oleautomation.XValueObject</idl>. The type description is provided by flags which resemble the <code>VARTYPE</code> as used by <code>VARIANTs</code>. All possible type flags are provided as properties by the XValueObject interface.
<source lang="vb">
'OOo Basic
'function expects a VARIANT of VT_I1 (signed char)
Dim value As Object
value = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
value.set(valueI2.VT_I1, 100)
automation_object.func(value)

'function expects a VARIANT of SAFEARRAY of VT_I2
Dim valueI2 As Object
Dim arI2(1) As Long
arI2(0) = 1000
arI2(1) = 1000
valueI2 = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
valueI2.set(valueI2.VT_I2 Or valueI2.VT_ARRAY, arI2)
automation_object.func(valueI2)
</source>

If a Value Object is provided as out or in/out parameter then the type will be changed after the function has returned. Therefore the argument type must be of Variant. For example:

<source lang="vb">
Dim valueLong As Variant
valueLong = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
valueLong.set(valueLong.VT_INT, 1000)
automation_object.outLong(valueLong)
</source>

{{PDL1}}

[[Category:Documentation/Developer's Guide/Professional UNO]]

Documentation/DevGuide/ProUNO/Bridge/Value Objects

2011-03-29T10:36:26Z

Jl: Uno Value Object

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2c=block
|ABridgeSvcMgr=block
|ABridgeTM=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Bridge/Client-Side Conversions
|NextPage=Documentation/DevGuide/ProUNO/Bridge/Exceptions and Errorcodes
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/Bridge/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Value Objects}}
==The Automation Value Object==
The object can be obtained from any uno object by calling the Bridge_GetValueObject on it. It holds a value and a type description, hence it resembles a UNO any or a VARIANT. A Value Object can stand in for all kinds of arguments in a call to a UNO method from a automation language. A Value Object is used when the bridge needs additional information for the parameter conversion. This is the case when a UNO method takes an any as argument. In many cases, however, one can do without a Value Object if one provides an argument which maps exactly to the expected UNO type according to the default mapping. For example, a UNO method takes an any as argument which is expected to contain a short. Then it would be sufficient to provide a Long in Visual Basic. But in JScript there are no types and implicitly a four byte integer would be passed to the call. Then the any would not contain a short and the call may fail. In that case the Value Object would guarantee the proper conversion.

A Value Object also enables in/out and out parameter in languages which only know in-parameters in functions. JScript is a particular case because one can use Array objects as well as Value Objects for those parameters.

A Value Object exposes four functions that can be accessed through <code>IDispatch</code>. These are:
<source lang="idl">
void Set( [in]VARIANT type, [in]VARIANT value);
</source>
Assigns a type and a value.
<source lang="idl">
void Get( [out,retval] VARIANT* val);
</source>
Returns the value contained in the object. Get is used when the Value Object was used as inout or out parameter.
<source lang="idl">
void InitOutParam();
</source>
Tells the object that it is used as out parameter.
<source lang="idl">
void InitInOutParam( [in]VARIANT type, [in]VARIANT value);
</source>
Tells the object that it is used as inout parameter and passes the value for the in parameter, as well as the type.

When the Value Object is used as in or inout parameter then specify the type of the value. The names of types correspond to the names used in UNO IDL, except for the “object” name. The following table shows what types can be specified.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Name (used with Value Object)
!UNO IDL
|-
|char
|char
|-
|boolean
|boolean
|-
|byte
|byte
|-
|unsigned
|unsigned byte
|-
|short
|short
|-
|unsigned short
|unsigned short
|-
|long
|long
|-
|unsigned long
|unsigned long
|-
|string
|string
|-
|float
|float
|-
|double
|double
|-
|any
|any
|-
|object
|some UNO interface
|}

To show that the value is a sequence, put brackets before the names, for example:
<source lang="idl">
[]char - sequence<char>
[][]char - sequence < sequence <char > >
[][][]char - sequence < sequence < sequence < char > > >
</source>
The <code>Value Objects</code> are provided by the bridge and can be obtained from the service manager object. The service manager is a registered COM component with the ProgId “com.sun.star.ServiceManager” ([[Documentation/DevGuide/ProUNO/Bridge/The Service Manager Component|The Service Manager Component]]). For example:
<source lang="javascript">
// JScript
var valueObject= objSericeManager.Bridge_GetValueObject();
</source>
To use a <code>Value Object</code> as in parameter, specify the type and pass the value to the object:
<source lang="idl">
// UNO IDL
void doSomething( [in] sequence< short > ar);
</source>
<source lang="javascript">
// JScript
var value= objServiceManager.Bridge_GetValueObject();
var array= new Array(1,2,3);
value.Set("[]short",array);
object.doSomething( value);
</source>
In the previous example, the <code>Value Object</code> was defined to be a sequence of short values. The array could also contain <code>Value Objects</code> again:
<source lang="javascript">
var value1= objServiceManager.Bridge_GetValueObject();
var value2= objServiceManager.Bridge_GetValueObject();
value1.Set("short“, 100);
value2.Set("short", 111);
var array= new Array();
array[0]= value1;
array[1]= value2;
var allValue= objServiceManager.Bridge_GetValueObject();
allValue.Set("[]short“, array);
object.doSomething( allValue);
</source>
If a function takes an out parameter, tell the <code>Value Object</code> like this:
<source lang="idl">
// UNO IDL
void doSomething( [out] long);
</source>
<source lang="javascript">
// JScript
var value= objServiceManager.Bridge_GetValueObject();
value.InitOutParam();
object.doSomething( value);
var out= value.Get();
</source>
When the <code>Value Object</code> is an <code>inout</code> parameter, it needs to know the type and value as well:
<source lang="idl">
//UNO IDL
void doSomething( [inout] long);
</source>
<source lang="javascript">
//JScript
var value= objServiceManager.Bridge_GetValueObject();
value.InitInOutParam("long", 123);
object.doSomething(value);
var out= value.Get();
</source>

==UNO Value Object==
The UNO Value Object is basically the same as the Automation Value Object. It can be provided as argument in calls on automation objects. The value object is an uno service and implements <idl>com.sun.star.bridge.oleautomation.XValueObject</idl>. The type description is provided by flags which resemble the <code>VARTYPE</code> as used by <code>VARIANTs</code>. All possible type flags are provided as properties by the XValueObject interface.
<source lang="vb">
'OOo Basic
'function expects a VARIANT of VT_I1 (signed char)
Dim value As Object
value = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
value.set(valueI2.VT_I1, 100)
automation_object.func(value)

'function expects a VARIANT of SAFEARRAY of VT_I2
Dim valueI2 As Object
Dim arI2(1) As Long
arI2(0) = 1000
arI2(1) = 1000
valueI2 = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
valueI2.set(valueI2.VT_I2 Or valueI2.VT_ARRAY, arI2)
automation_object.func(valueI2)
</source>

If a Value Object is provided as out or in/out parameter then the type will be changed after the function has returned. Therefore the argument type must be of Variant. For example:

<source lang="vb">
Dim valueLong As Variant
valueLong = createUnoService("com.sun.star.bridge.oleautomation.ValueObject")
valueLong.set(valueLong.VT_INT, 1000)
automation_object.outLong(valueLong)
</source>

{{PDL1}}

[[Category:Documentation/Developer's Guide/Professional UNO]]

Documentation/DevGuide/ProUNO/Bridge/Mapping of Sequence

2011-03-29T09:32:37Z

Jl:

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2c=block
|ABridgeSvcMgr=block
|ABridgeTM=block
|ABridgeDM=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Bridge/Mapping of Interfaces and Structures
|NextPage=Documentation/DevGuide/ProUNO/Bridge/Mapping of Type
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/Bridge/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Mapping of Sequence}}
==Kinds of arrays==
Arrays in Automation have a particular type. The <code>SAFEARRAY</code>. A <code>SAFEARRAY</code> array is used when a UNO function takes a sequence as an argument. To create a <code>SAFEARRAY</code> in C++, use Windows API functions. The C++ name is also <code>SAFEARRAY</code>, but in other languages it might be named differently. In VB for example, the type does not even exist, because it is mapped to an ordinary VB array:
<source lang="vb">
Dim myarr(9) as String
</source>

JScript is different. It does not have a method to create a <code>SAFEARRAY</code>. Instead, JScript features an <code>Array</code> object that can be used as a common array in terms of indexing and accessing its values. It is represented by a dispatch object internally. JScript offers a <code>VBArray</code> object that converts a <code>SAFEARRAY</code> into an <code>Array</code> object, which can then be processed further.

The Automation bridge accepts both, <code>SAFEARRAY</code> and <code>Array</code> object, for arguments whose UNO type is a sequence.

{{Documentation/Tip|If a <tt>SAFEARRAY</tt> is obtained in JScript as a result of a call to an ActiveX component or a VB Script function (for example, the Internet Explorer allows JScript and VBS code on the same page), then it can also be used as an argument of a UNO function without converting it to an <tt>Array</tt> object.}}

==Multidimensional arrays==
UNO does not recognize multi-dimensional sequences. Instead, a sequences can have elements that are also sequences. Those “inner” sequences can have different lengths, whereas the elements of a dimension of a multi-dimensional array are all the same length.

To provide an argument for a sequence of sequences, a <code>SAFEARRAY</code> containing <code>VARIANT</code>s of <code>SAFEARRAY</code>s has to be created. For example:
<source lang="idl">
//UNO method
void foo([in] sequence< sequence< long > > value);
</source>
<source lang="vb">
Dim seq(1) As Variant
Dim ar1(3) As Long
Dim ar2(4) As Long
'fill ar1, ar2
...

seq(0) = ar1
seq(1) = ar2

objUno.foo seq
</source>

The array seq corresponds to the “outer” sequence and contains two <code>VARIANT</code>s, which in turn contain <code>SAFEARRAY</code>s of different lengths.

It is also possible to use a multi-dimensional <code>SAFEARRAY</code> if the elements of the sequence are all the same length:
<source lang="vb">
Dim seq(9, 1) As Long
'fill the sequence
...
objUno.foo seq
</source>

Be aware that Visual Basic uses a column-oriented ordering in contrast to C. That is, the C equivalent to the VB array is
<source lang="c">
long seq[2][10]
</source>
The highest dimension in VB is represented by the right-most number.

This language binding specifies that the “outer” sequence corresponds to the highest dimension. Therefore, the VB array seq(9,1) would map to a sequence of sequences where the outer sequence has two elements and the inner sequences each have ten elements.

==Conversion of returned sequences==

Sequences can be returned as return values of uno functions or properties and as in/out or out arguments of uno functions. They are converted into <code>SAFEARRAY</code>s containing <code>VARIANT</code>s. If a sequence of sequences is returned, then the <code>VARIANT</code>s contain again <code>SAFEARRAY</code>s. For example, if an uno function returns a sequence of strings then the bridge will convert the sequence into a <code>SAFEARRAY</code> containing <code>VARIANT</code>s of strings. This is necessary because some languages, for example VBScript can only access members of arrays if they are <code>VARIANT</code>s.

To process a returned <code>SAFEARRAY</code> in JScript, use the <code>VBArray</code> object to convert the <code>SAFEARRAY</code> into a JScript <code>Array</code>.

That a returned sequence maps to a <code>SAFEARRAY</code> of <code>VARIANT</code>s is not ideal because it is ambiguous when the array is passed back to UNO. However, the bridge solves this problem by using UNO type information. For example, a returned sequence of longs will result in a <code>SAFEARRAY</code> of <code>VARIANT</code>s containing long values. When the <code>SAFEARRAY</code> is passed in a method as an argument for a parameter of type <code>sequence<long ></code> then it is converted accordingly. However, if the parameter is an <code>any</code>, then the bridge does not have the necessary type information and converts the <code>SAFEARRAY</code> to <code>sequence<any></code>. If the method now expects the any to contain a <code>sequence<long></code> then it may fail. This is confusing if there are pairs of methods like <code>getxxx</code> and <code>setxxx</code>, which take any arguments. Then you may get a <code>SAFEARRAY</code> as a return value, which cannot be used in the respective <code>setXXX</code> call. For example:
<source lang="idl">
//UNO IDL
any getByIndex();
void setByIndex([in] any value);
</source>
<source lang="vb">
' VB
Dim arLong() As Variant
arLong = objUno.getByIndex() 'object returns sequence<long> in any
objUno.setByIndex arLong 'object receives sequence<any> in any and may cause an error.
</source>

To solve this problem, wrap the argument in a Value Object ([[Documentation/DevGuide/ProUNO/Bridge/Value Objects|Value Objects]]):
<source lang="vb">
' VB
Dim arLong() As Variant
arLong = objUno.getByIndex() 'object returns sequence<long> in any

Dim objValueObject As Object
Set objValueObject = objServiceManager.Bridge_GetValueObject()
objValueObject.set “[]long”, arLong

objUno.setByIndex objValueObject 'object receives sequence<long>
</source>

A similar problem may occur when one calls functions of an automation object which takes <code>VARIANT</code>s as arguments and the function expects particular types within those <code>VARIANT</code>s. For example, an automation object expects a <code>VARIANT</code> containing a <code>SAFEARRAY</code> of strings. The bridge only knows from the object's type information that the function expects a <code>VARIANT</code>, but not the contained type. The bridge will therefore do a default conversion of the sequence, which produces a <code>SAFEARRAY</code> of <code>VARIANT</code>s. The function may not be able to understand this argument. Then one can use a value object in order to give the bridge a hint of the expected type.

If the parameter is a multi–dimensional <code>SAFEARRAY</code>, then a sequence containing sequences has to be provided. The number of nested sequences corresponds to the number of dimensions. Since the elements of a dimension have the same length, the sequences that represent that dimension should also have the same length. For example, assume the expected <code>SAFEARRAY</code> can be expressed in C as
<source lang="c">
long ar[2][10]
</source>

Then the outer sequence must have two elements and each of those sequences has 10 elements.
{{PDL1}}

[[Category:Documentation/Developer's Guide/Professional UNO]]

Documentation/DevGuide/ProUNO/Bridge/Mapping of Sequence

2011-03-29T09:28:08Z

Jl: Some cleanup and mentioning use of value objects on the uno side

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2c=block
|ABridgeSvcMgr=block
|ABridgeTM=block
|ABridgeDM=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Bridge/Mapping of Interfaces and Structures
|NextPage=Documentation/DevGuide/ProUNO/Bridge/Mapping of Type
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/Bridge/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Mapping of Sequence}}
==Kinds of arrays==
Arrays in Automation have a particular type. The <code>SAFEARRAY</code>. A <code>SAFEARRAY</code> array is used when a UNO function takes a sequence as an argument. To create a <code>SAFEARRAY</code> in C++, use Windows API functions. The C++ name is also <code>SAFEARRAY</code>, but in other languages it might be named differently. In VB for example, the type does not even exist, because it is mapped to an ordinary VB array:
<source lang="vb">
Dim myarr(9) as String
</source>

JScript is different. It does not have a method to create a <code>SAFEARRAY</code>. Instead, JScript features an <code>Array</code> object that can be used as a common array in terms of indexing and accessing its values. It is represented by a dispatch object internally. JScript offers a <code>VBArray</code> object that converts a <code>SAFEARRAY</code> into an <code>Array</code> object, which can then be processed further.

The Automation bridge accepts both, <code>SAFEARRAY</code> and <code>Array</code> object, for arguments whose UNO type is a sequence.

{{Documentation/Tip|If a <tt>SAFEARRAY</tt> is obtained in JScript as a result of a call to an ActiveX component or a VB Script function (for example, the Internet Explorer allows JScript and VBS code on the same page), then it can also be used as an argument of a UNO function without converting it to an <tt>Array</tt> object.}}

==Multidimensional arrays==
UNO does not recognize multi-dimensional sequences. Instead, a sequences can have elements that are also sequences. Those “inner” sequences can have different lengths, whereas the elements of a dimension of a multi-dimensional array are all the same length.

To provide an argument for a sequence of sequences, a <code>SAFEARRAY</code> containing <code>VARIANT</code>s of <code>SAFEARRAY</code>s has to be created. For example:
<source lang="idl">
//UNO method
void foo([in] sequence< sequence< long > > value);
</source>
<source lang="vb">
Dim seq(1) As Variant
Dim ar1(3) As Long
Dim ar2(4) As Long
'fill ar1, ar2
...

seq(0) = ar1
seq(1) = ar2

objUno.foo seq
</source>

The array seq corresponds to the “outer” sequence and contains two <code>VARIANT</code>s, which in turn contain <code>SAFEARRAY</code>s of different lengths.

It is also possible to use a multi-dimensional <code>SAFEARRAY</code> if the elements of the sequence are all the same length:
<source lang="vb">
Dim seq(9, 1) As Long
'fill the sequence
...
objUno.foo seq
</source>

Be aware that Visual Basic uses a column-oriented ordering in contrast to C. That is, the C equivalent to the VB array is
<source lang="c">
long seq[2][10]
</source>
The highest dimension in VB is represented by the right-most number.

This language binding specifies that the “outer” sequence corresponds to the highest dimension. Therefore, the VB array seq(9,1) would map to a sequence of sequences where the outer sequence has two elements and the inner sequences each have ten elements.

==Conversion of returned sequences==

Sequences can be returned as return values of uno functions or properties and as in/out or out arguments of uno functions. They are converted into <code>SAFEARRAY</code>s containing <code>VARIANT</code>s. If a sequence of sequences is returned, then the <code>VARIANT</code>s contain again <code>SAFEARRAY</code>s. For example, if an uno function returns a sequence of strings then the bridge will convert the sequence into a <code>SAFEARRAY</code> containing <code>VARIANT</code>s of strings. This is necessary because some languages, for example VBScript can only access members of arrays if they are <code>VARIANT</code>s.

To process a returned <code>SAFEARRAY</code> in JScript, use the <code>VBArray</code> object to convert the <code>SAFEARRAY</code> into a JScript <code>Array</code>.

That a returned sequence maps to a <code>SAFEARRAY</code> of <code>VARIANT</code>s is not ideal because it is ambiguous when the array is passed back to UNO. However, the bridge solves this problem by using UNO type information. For example, a returned sequence of longs will result in a <code>SAFEARRAY</code> of <code>VARIANT</code>s containing long values. When the <code>SAFEARRAY</code> is passed in a method as an argument for a parameter of type <code>sequence<long ></code> then it is converted accordingly. However, if the parameter is an <code>any</code>, then the bridge does not have the necessary type information and converts the <code>SAFEARRAY</code> to <code>sequence<any></code>. That is, the called method receives an any containing a <code>sequence<any></code>. If the method now expects the any to contain a <code>sequence<long></code> then it may fail. This is confusing if there are pairs of methods like <code>getxxx</code> and <code>setxxx</code>, which take any arguments. Then you may get a <code>SAFEARRAY</code> as a return value, which cannot be used in the respective <code>setXXX</code> call. For example:
<source lang="idl">
//UNO IDL
any getByIndex();
void setByIndex([in] any value);
</source>
<source lang="vb">
' VB
Dim arLong() As Variant
arLong = objUno.getByIndex() 'object returns sequence<long> in any
objUno.setByIndex arLong 'object receives sequence<any> in any and may cause an error.
</source>

To solve this problem, wrap the argument in a Value Object ([[Documentation/DevGuide/ProUNO/Bridge/Value Objects|Value Objects]]):
<source lang="vb">
' VB
Dim arLong() As Variant
arLong = objUno.getByIndex() 'object returns sequence<long> in any

Dim objValueObject As Object
Set objValueObject = objServiceManager.Bridge_GetValueObject()
objValueObject.set “[]long”, arLong

objUno.setByIndex objValueObject 'object receives sequence<long>
</source>

A similar problem may occur when one calls functions of an automation object which takes <code>VARIANT</code>s as arguments and the function expects particular types within those <code>VARIANT</code>s. For example, an automation object expects a <code>VARIANT</code> containing a <code>SAFEARRAY</code> of strings. The bridge only knows from the object's type information that the function expects a <code>VARIANT</code>, but not the contained type. The bridge will therefore do a default conversion of the sequence, which produces a <code>SAFEARRAY</code> of <code>VARIANT</code>s. The function may not be able to understand this argument. Then one can use a value object in order to give the bridge a hint of the expected type.

If the parameter is a multi–dimensional <code>SAFEARRAY</code>, then a sequence containing sequences has to be provided. The number of nested sequences corresponds to the number of dimensions. Since the elements of a dimension have the same length, the sequences that represent that dimension should also have the same length. For example, assume the expected <code>SAFEARRAY</code> can be expressed in C as
<source lang="c">
long ar[2][10]
</source>

Then the outer sequence must have two elements and each of those sequences has 10 elements.
{{PDL1}}

[[Category:Documentation/Developer's Guide/Professional UNO]]

Documentation/DevGuide/ProUNO/Bridge/Client-Side Conversions

2011-03-29T08:21:11Z

Jl: Remove the duplicate text

Documentation/DevGuide/Extensions/Updating Extensions

2010-11-24T08:51:35Z

Jl: removed update of bundled extensions

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/The Active Extension
|NextPage=Documentation/DevGuide/Extensions/Processing Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Updating Extensions}}
'''(As of OOo 3.3)'''

An extension can be updated by either explicitly installing the extension or by running the update function in the extension manager.
Updating an extension consisted originally in removing the installed extension and then installing the new version of the extension in the same repository. This meant that it was necessary to have write permission for the extensions folder of the shared repository for updating shared extensions.

Updating shared extensions is now possible. If the user has no write permission, then the update will be installed in the user repository. The actual shared extension will then remain unchanged, but it will be superseded by the update, because it has a higher priority.

Bundled extensions cannot be updated by the extension manager (see [[Setup_-_Bundled_Extensions | Setup - Bundled Extensions]]). However, users can still download and install these extension themselves.

Users will be informed if there are newer versions of extensions, which they currently use, are available. It does not matter if the currently used extensions are from the user or shared repository. If there is a better version, then it is offered as an update. This allows users to always obtain the latest versions of their extensions.

The updates, that is, the extensions with a newer version, will either be obtained from an online repository or locally, depending on which ones have the highest versions. In the latter case, the newer version will come from the shared or bundled repository if there is one available. If the version of an extension in a local repository is the same as the one from the online repository, then the local one is used.

Using a local repository (bundled or shared) as update source is useful for the case when a user has installed an user extension and then a more current version is installed in the shared or bundled repository. The user would then use the "old" version, although a better one is already available.

The following tables show scenarios where the user can update extensions. If a cell contains a “1” then this simple means there is an extensions installed. If it contains a “2” then this represents an extension with the same identifier then “1” but with a higher version. If there are several “2”s under each other then it is sufficient if just one of them has a higher version than “1”.

The first table shows the case where a user has '''no write permission''' in the shared folder. In all cases the update is installed in the '''user repository'''. The new version comes either from the shared, bundled or online repository, depending on which has the best version.

{| border="1" cellpadding="2"
!
! Case a
! Case b
|-
|style="background:#EFDECD" |User repository || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Bundled repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"|2
|}

In words:
An update (installing in the user repository) is possible, if
#there is shared extension (no user) and the bundled or online repository contains a higher version
#there is a user extension and the shared, bundled or online repository contains a higher version

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''shared repository'''. If a user extension exists does not matter.
{| border="1" cellpadding="2"
!
! Case a
|-
|style="background:#EFDECD" |Shared repository || align="center"| 1
|-
|style="background:#EFDECD" |Bundled repository || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in shared repository) is possible, if there is shared extension and the bundled or online repository contains a higher version

This also means that, if there is only a user extension (no shared, no bundled) and there is one with a higher version in the online repository, then no update is done in the shared repository.

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''user repository'''.

{| border="1" cellpadding="2"
!
! Case a
|-
|style="background:#EFDECD" |User repository || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Bundled repository || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in user repository) is possible, if there is a user extension and the shared, bundled, or online repository contains a higher version.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Setup - Bundled Extensions

2010-08-03T13:46:16Z

Jl: /* Configuration */

=Setup - Bundled/Integrated Extensions=

{{Specification_Header|Lutz Hoeger|Jun 17, 2010|Standard}}

== Abstract ==
Integrated extensions - such as dictionaries for spell checking - will be displayed in the OOo installer module selection (during custom installation). This allows users to gain more control over what will be installed on their system. At the same time, managing such extensions (remove, update) will be moved from the extension manager into the application installer.

__TOC__

== References ==

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Reference Document''' || bgcolor="#dddddd" | '''Check''' || bgcolor="#dddddd" | '''Location (URL)'''
|-
| '''Product Requirement, RFE, Issue ID''' (required)
| [available]
| http://www.openoffice.org/issues/show_bug.cgi?id=112404
|-
| '''[[Test case specification]]''' (required)
| [available]
| http://www.openoffice.org/nonav/issues/showattachment.cgi/70050/Bundled%20Extensions.html
|-
|}

== Contacts ==

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Role''' || bgcolor="#dddddd" | '''Name''' || bgcolor="#dddddd" | '''E-Mail Address'''
|-
| '''Developer'''
| Joachim Lingner
| jl@openoffice.org
|-
| '''Quality Assurance'''
| Olaf Felka
| of@openoffice.org
|-
| '''Documentation'''
| Uwe Fischer
| ufi@openoffice.org
|-
|}

== Detailed Specification ==

This document distinguishes between '''bundled''' extensions and '''integrated''' extensions.

'''Bundled Extensions''':
* The extension package is '''co-located with the main product installer'''. This can be in a separate directory, next to the installer, or on an additional medium.
* There is '''no integration into the installation process''' of the main product.
* The purpose of bundled extensions is to achieve a moderate level of '''convenience''' for users, and to add value to the overall '''product bundling'''.

'''Integrated Extensions''':
* The extension is '''part of the installation''' package of the main application. It is installed via the main product installer.
* The purpose of integrated extensions is to '''add functionality to the main product''', while maintaining the flexibility given by extensions.
* Typical integrated extensions - such as dictionaries for spell checking - will be '''displayed in the OOo installer''' module selection (during custom installation).
* On Windows and Unix, user can de-select items; on Mac, all items will be installed
* At the same time, managing integrated extensions (remove, update) will be '''removed from the Extension Manager''' and put into the application installer.
* Integrated extensions shall '''not ping for updates'''. Any update available will be deployed exclusively via later releases of the main product OOo.

----

'''Display of Dictionaries:'''
* Location in setup: Optional Components, #1 after Java
* Module name: Dictionaries
* Module description: Spelling and hyphenation dictionaries and thesauri
* Default: ON (incl. all sub-modules, according to spellchecker selection per language specific installation set)
* Sub-modules: See list below.

=== Dictionaries ===
Note: The set of dictionaries actually included in a language specific installation set – or in a multi language set – does not change. The following list just enlists all dictionary languages possibly shipped in OOo.

The set of languages display in setup should be sorted alphabetically by Module name.

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Language''' || bgcolor="#dddddd" | '''Module Name''' || bgcolor="#dddddd" | '''Module descrition'''
|-
| af
| Afrikaans
| Afrikaans spell checker
|-
| pt
| Brazilian Portuguese
| Brazilian Portuguese Spelling Dictionary - 1990 Spelling Agreement
|-
| ca
| Catalan
| Spelling and hyphenation dictionaries and thesaurus for Catalan language (general)
|-
| cs
| Czech
| Czech thesaurus
|-
| da
| Danish
| Spelling and hyphenation dictionary for Danish
|-
| nl
| Dutch
| Dutch spelling and hyphenation dictionaries
|-
| en-US
| English
| English spelling and hyphenation dictionaries and thesaurus
|-
| et
| Estonian
| Estonian spelling and hyphenation dictionaries
|-
| fr
| French
| French "Classic and Reform 1990" spelling, thesaurus and hyphenation
|-
| gl
| Galician
| Galician spellchecker dictionary for OpenOffice.org
|-
| de-AT
| German (Austria)
| German (AT-frami) spelling, hyphenation, thesaurus
|-
| de-DE
| German (Germany)
| German (DE-frami) spelling, hyphenation, thesaurus
|-
| de-CH
| German (Switzerland)
| German (CH-frami) spelling, hyphenation, thesaurus
|-
| he
| Hebrew
| Hebrew spell check dictionary
|-
| hu
| Hungarian
| Hungarian spelling dictionary, hyphenation patterns, and thesaurus
|-
| it
| Italian
| Italian spelling and hyphenation dictionaries and thesaurus
|-
| ku-TR
| Kurdish (Turkey)
| Kurdish (Turkey) spell check dictionary
|-
| lt
| Lithuanian
| Lithuanian spelling and hyphenation dictionaries
|-
| ne
| Nepali
| Nepali spelling dictionary and thesaurus
|-
| no
| Norwegian
| Norwegian dictionaries (Nynorsk and Bokmål)
|-
| pl
| Polish
| Polish spell check dictionary, hyphenation rules and thesaurus
|-
| ro
| Romanian
| Romanian Dictionaries
|-
| ru
| Russian
| Russian hyphenation dictionary and thesaurus
|-
| sr
| Serbian
| Serbian spelling and hyphenation dictionaries
|-
| sk
| Slovak
| Slovak spell check dictionary, hyphenation rules and thesaurus
|-
| sl
| Slovenian
| Slovenian dictionary pack
|-
| es
| Spanish
| Spanish spelling dictionary
|-
| sw
| Swahili
| Swahili spelling dictionary
|-
| sv
| Swedish
| Swedish Dictionary
|-
| th
| Thai
| Thai spelling dictionary
|-
| vi
| Vietnamese
| Vietnamese spellchecker dictionary
|-
| zu
| Zulu
| Zulu hyphenation dictionary
|-
|}

[[Specification_Template_Help#Detailed_Specification|Help]] | [[UI-Elements|User Interface Element Templates]] | [[Specification_Example|Example Spec]]

== Accessibility ==
Accessibility not impacted.

== Migration ==
Bundled dictionaries in OOo versions previous to 3.3 were installed as shared extensions. Shared extensions are not migrated.

As of 3.3 bundled extensions will always be removed when uninstalling OOo. They are therefore not eligible for being migrated.

== Configuration ==
Bundled extensions can be configured if they provide their own options pages in OOo's options dialog.

[[Specification_Template_Help#Configuration|Help]] | [[Configuration-Table|Configuration Table Template]]

== Open Issues ==
* Pre-bundled extensions still show up in the Extension Manager. This is considered a minor impact, as the user cannot change such extension in this place. Issue will be resolved in the future.

[[Category:Specification]]
[[Category:Extensions]]
[[Category:Installation]]

Documentation/DevGuide/Extensions/Updating Extensions

2010-08-03T08:02:26Z

Jl: minor correction

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/The Active Extension
|NextPage=Documentation/DevGuide/Extensions/Processing Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Updating Extensions}}
'''(As of OOo 3.3)'''

An extension can be updated by either explicitly installing the extension or by running the update function in the extension manager.
Updating an extension consisted originally in removing the installed extension and then installing the new version of the extension in the same repository. This meant that it was necessary to have write permission for the extensions folder of the shared repository for updating shared extensions.

However, in order to hide the complexity of the different repositories from the user, the extension manager allows to install updates for shared or bundled extensions. These updates will in fact be installed as user extensions, in case the user cannot write in the shared repository. The installed bundled/shared extension will then remain unchanged, but it will be superseded by the update, because it has a higher priority.

Users will be informed if there are newer versions of extensions which they currently use are available. It does not matter if the currently used extensions are from the user, shared or bundled repository. If there is a better version, then it is offered as an update. This allows users, to always obtain the latest versions of their extensions.

The updates, that is, the extensions with a newer version, will either be obtained from an online repository or locally, depending on which one have the highest versions. In the latter case, the newer version will come from the shared or bundled repository if there is one available. This is useful for the case when a user has installed an user extension and then a more current version is installed in the shared or bundled repository.

The following tables show scenarios where the user can update extensions. If a cell contains a “1” then this simple means there is an extensions installed. If it contains a “2” then this represents an extension with the same identifier then “1” but with a higher version. If there are several “2”s under each other then it is sufficient if just one of them has a higher version than “1”.

The first table shows the case where a user has '''no write permission''' in the shared folder. In all cases the update is installed in the '''user repository'''. The new version comes either from the shared, bundled or online repository, depending on which has the best version.

{| border="1" cellpadding="2"
!
! Case a
! Case b
! Case c
|-
|style="background:#EFDECD" |User repository || align="center" | - || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || align="center" | - ||align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"|2
|}

In words:
An update (installing in the user repository) is possible, if
#there is a bundled extension (no user and no shared) and the online repository contains a higher version
#there is shared extension (no user) and the bundled or online repository contains a higher version
#there is a user extension and the shared, bundled or online repository contains a higher version

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''shared repository'''. If a user extension exists does not matter.
{| border="1" cellpadding="2"
!
! Case a
! Case b
|-
|style="background:#EFDECD" |Shared repository || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in shared repository) is possible, if
#there is a bundled extension (and no shared) and the online repository contains a higher version
#there is shared extension and the bundled or online repository contains a higher version

This also means that, if there is only a user extension (no shared, no bundled) and there is one with a higher version in the online repository, then no update is done in the shared repository.

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''user repository'''.

{| border="1" cellpadding="2"
!
! Case a
|-
|style="background:#EFDECD" |User repository || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Bundled repository || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in user repository) is possible, if there is a user extension and the shared, bundled, or online repository contains a higher version.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Processing Extensions

2010-07-07T07:33:58Z

Jl: Paragraph "Restarting OOo"

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Updating Extensions
|NextPage=Documentation/DevGuide/Extensions/Packaging Notes
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Processing Extensions}}
'''(As of OOo 3.3)'''
==Checking for modification during start-up==
Every time OOo is started it needs to check if extensions were removed from or added to the shared or bundled repository. If this is the case, then the registration data of the repository must be updated accordingly and OOo is restarted.

Because OOo checks for added or removed extensions at start-up, this must be very quick. To achieve this, OOo compares the modification time of extension folders of the repositories with the time of the most recently performed check. This time is “saved” in the file lastsynchronized in the registration data folder of the repositories. In fact, the modification time of the file is used rather then a value is written into the file. If the modification time of the extension folder is more recent, then the extension manager will check if extensions were added or removed and update its database accordingly. This is of course an implementation detail and may change at any time.

==Restarting OOo==
The restart is necessary to avoid that users use ''removed'' shared extensions. Removing a shared extensions does not entail the immediate removal of the the extension files. This is necessary to allow live deployment. For details see [[Documentation/DevGuide/Extensions/Processing_Extensions#Adding a shared extension | Adding a shared extension]] and [[Documentation/DevGuide/Extensions/Processing_Extensions#Removing a shared extension | Removing a shared extension]].
The extension manager updates its databases during start-up of OOo an removes entries of removed extension, so that they cannot be used anymore. However, until this has happend services from the removed extension may have been started and menus added to the menu bar.

Even if the extensions are completely removed from the disk, as is the case with removed bundled extensions, remnants can still be visible for the user. This applies particularly for configuration data. The extension manager processes them and creates additional data (registration data), that is configuration data containing expanded URLs. OOo only uses the registration data, which is stored in the user data. Removing the bundled extension, which is done by the installer, does not remove the registration data. This is only done during the start-up when the extension manager runs. But by this time, the configuration manager has already loaded the registration data of the removed extension. ''Live removal'' of menu entries does not work yet. Therefore artifacts of removed extensions may still be seen when OOo is run the first after removing the extension.

There are also extensions which do not work well right after they are installed. In other words, they do not support live deployment. This is typically caused by issues in OOo and/or the extension. After restarting OOo, the extensions perform as expected.

Although live deployment issues can be fixed, there is still the problem of removed shared extensions. This could only be solved if one would not allow live deployment of shared extensions.

==Adding==
===Adding a user extension===
A user extension is extracted into a folder with a unique name which in turn is contained in the extensions folder. The additional folder with the unique name is necessary to make live deployment possible. When removing an extension, it is only marked as “unusable” and the extension is not deleted, because it may still be in use. If now the same extension is installed again in the same process, then it will be extracted to another folder with a unique name. This prevents a name clash with the folder name of the previously “removed” extension. The user can now repeat to remove and install the extension in the same process. This results in having the same extension multiple times in the extensions folder of the repository, but everyone is contained in a folder with a unique name. The folders of the “removed” extensions, as well as the folders which contain them, are only removed after running the extension manager after restarting OOo.

The extension database of repository is updated and the new active extension is determined.

===Adding a shared extension===
For the user who adds a shared extension, the extension is processed the same way as a user extension.

For all other users, the extension manager processes the extension the next time they start OOo.
The extension database of repository is updated and the new active extension is determined.

===Adding a bundled extension===
A bundled extension is installed by the installation program of OOo. The folder of the extension, including all files contained therein, is copied into the extensions folder of the bundled repository.
Only when a user starts OOo, then the extension manager processes the extension. The extension database of repository is updated and the new active extension is determined.

==Removing==
===Removing a user extension===
The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined. The extension will be deleted when the user runs the extension manager after restarting OOo.

===Removing a shared extension===
The extension will be revoked if it was registered. To prevent other users from using the extension it is marked to be deleted. This is done by creating a tag file, the "extension removed file", next to the folder with the unique name. This way, the information that the extension was deleted can be accessed by all users. If this file does not exist and there is no entry in the extensions database, then it is assumed that the extension was added. The file will be deleted when the extension is deleted. The file also contains the name of the user who removed the extension. If the same user runs the extension manager after restarting OOo, then the extension, the unique folder, temp file and the "extensions removed file are deleted. Why it must be the same user shows the following scenario:

A user starts OOo and uses the extension. The extension will then be removed and OOo keeps running. Now a second user, who also has write access to the extensions folder, starts OOo. When the extension manager starts it would properly delete extensions which were previously removed. However in this case this would affect the office of the first user which still uses that extension.
The same user cannot start another instance, because this is prevented by the lock file.

For all other users, the extension manager processes the extension the next time they start OOo. This includes the detection of the removed extensions. An extension is regarded as removed if:
*The unique folder, tmp file, extension folder do not exist anymore.
*There is a "extension removed file"
*The extension exists but has a different identifier or version than the one which was previously at the same location. This may happen when the extension was updated, or a previous office update removed the extension and another with the same name was added in the latest office update.

The extension could also have the same file name.
The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined.

===Removing a bundled extension===
A bundled extension can only be removed by the set-up. The folder of the extension, including all files contained in it, is deleted from the extension folder of the bundled repository.

If a user starts OOo, then the extension manager processes the removed extension. This includes the detection of the removed extensions.
An extension is regarded as removed if:
*The extension folder do not exist anymore.
*The extension exists but has a different identifier or version than the one which was previously at the same location.

The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined.

==Updating==
An update consists of first removing the extension and then adding the new extension. That is, this is already covered by these two scenarios.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Extension Layers

2010-07-02T10:13:22Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Location of Installed Extensions
|NextPage=Documentation/DevGuide/Extensions/Checklist for Writing Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Extension Manager Rework}}
__NOTOC__
The Extension Manager uses two extension layers, the user and the shared layer. Extensions installed in the shared layer can be used by all users whereas those in the user layer can only be used by the user who installed them. An extension can be installed in either layer or both.

This system was developed many years ago. Since then new features were added, such as extension versioning, online update, bundled extensions, etc. During that time it became obvious that there are some problems with the original design. This document tries to explain them.
==Current problems==

=== Hiding ===
The idea of layers is that extensions in the top layer '''hide''' the same extensions in the layer below. In other words, the extension in the highest layer will be given preference, when resources from the extension are requested. Because the user layer is the top layer, a shared extension is only used when the same extension does not exist in the user layer. The version of the extension has no influence.

This, however, is only a simplified model. An extension is never used as a whole. Instead clients access the particular contents, such as components, configuration data, etc. And it is also these contents which obscure the same content in a lower layer. For example, an extension contains a UNO service, which is installed in both layers. When the client instantiates it then the one from the top layer is used.

There are situations where contents of the shared extensions are still used, although they should be hidden and therefore not usable. Assuming there are version 1 and version 2 of an extension. Then the different versions may have different content. For example, version 1 may contain a service ''foo'' which is not contained in version 2. If now version 1 is installed in the shared layer and version 2 in the user layer then ''foo'' is still around and can be instantiated. Foo may access resources which are also delivered with this extension and are also available in version 2 which is in the user layer. Resources in version 2, which hide those from version 1 (same node in xcu or same service), can be incompatible, so that foo fails.

A service may also need files which are part of the same extension and which are only directly accessible. That is there is no API, such as the registry or service manager, which can provide the content. A "running" service does not know from which layer it comes from. To get the install location it can use the [[Documentation/DevGuide/Extensions/Location of Installed Extensions|PackageInformationProvider]]. This service will first look into user layer and if the extension cannot be found, then it will look into the shared layer. If now the service from the shared layer needs some file from its extension, then it may accidentally use the one from a different version of the extension in the user layer. This file can be incompatible or not even exist and make the service fail.

Another example can be constructed using registry values, which are contained in xcu files. Let's assume that version 1 of an extension adds a menu ''foo'' and version 2 adds menu ''bar''. If one extension is installed in the share and the other in the user layer, then both menus appear. This is because the nodes of the configuration files are merged into the configuration and not the xcu files itself. That is, if the extensions contain an xcu file with the same name, then the xcu file of the last installed extension will NOT replace the one from the other extension. The second xcu file can, however, change the values for nodes which have been defined by the first xcu.

These examples prove that the layering (in terms of hiding the items from the layer below) on extension level does not work, although it does for the respective [[Documentation/DevGuide/Extensions/Deployment Items|deployment items]]. And it may be safe to say, that this goes against the user's expectation.

===Unclear behavior===
It may be unclear to users how the behavior is when the same extension is installed as user and shared extension. If there is a shared extension and the same extension is installed as user extension, then the user should be informed that the currently installed extension will become 'inactive'. Then, when the user extension is uninstalled, the user should be informed that the shared extension will become 'active' again.

=== Extension versions ===

As already observed, the version of an extension has no influence on the decision if the extension from the user or the shared layer is used. At the time of developing the extension framework there was no support for versioned extensions, so one did not have to care about them. Later, we recognized that an extension version is useful for users. For example, if one has an extension installed and is installing the same extension again, then one is being informed about what extension has the later version (so one can decide which is the best for them).

I think the general expectation is that the latest version is the best. Therefore it should be natural that OOo uses always that one. However, this is not the case and users may unintentionally prevent, that they use the latest extension. For example, OOo comes with a bundled English dictionary. Now a user installs, intentionally or not, the same extension and forgets about it. The administrator updates OOo regularly, which also updates the dictionary with the latest version. But the user would still use the old dictionary, because that is the one from the user layer which hides the one from the shared layer.

One could think now of a notification for the user but there are some questions:
*when does OOo check for this situation?
*how can this be explained to the user?
The first question, is easily answered: At every start-up.

The second question is more difficult.Think about a message, such as: "Dear user. You cannot use the latest version of the french dictionary, which is installed in the shared/bundled layer. Instead the dictionary which you installed earlier is used. You need to uninstall it, if you want the new version ...."
Many users would probably not understand this. So the easiest and natural way is simply to use the latest version of the extension indepedent of what layer it is installed in. The term layer should then be replaced, by repository, indicating that the location does not include a preference – just think about the picture of one layer above the other compared to repositories which are arranged in one row.

=== Layer location ===

The shared layer is located within the OOo installation. The benefit is that normal users cannot modify it. The layer will be modified after installation of OOo when an extensions is added, deleted, enabled or disabled. Depending on the operation system, this may be against the system guidelines. For example, it would be not allowed on Windows Vista/ 7. However, to allow “legacy application” to work Microsoft invented the virtual store.

=== Clean uninstallation ===

Modification of the shared layer will also prevent the clean uninstallation of OOo. This is because the native installer does not “own” the files/folder which were added by the extension manager. For example, on Linux the path /opt/openoffice.org3/share/uno_packages will remain on the system. On OpenSolaris the shared extensions (with the same directory structure) will be copied to /var/lost+found on uninstallation.

=== No Separation of shared and bundled extensions ===
The rule is, whatever a user installed should not be removed by OOo. This is also valid for shared extensions. Today a bundled extension is nothing else than a shared extension and therefore can be modified by users, provided they have sufficient file access rights. They can install the same extension as one, which was installed as bundled extension, in the shared layer. This means that the original bundled extension is replaced by the recently installed shared extension. This can happen in two scenarios. The first one is during an online update of the extension and the second is when the extension is “manually” installed. In these cases users intentionally choose to replace the original extension. Therefore this extension may not be deleted when uninstalling OOo. This, however, requires to know that the bundled extension was replaced, but there is currently no way to recognize this.

===Selection of extensions in setup===
Like many other features, bundled extensions should be selectable in the dialog of the installer. The installer can also be invoked later to add or remove particular features. The problem is, that the extensions which the installer “sees” are not the same as “seen” by the extension manager. The setup copies an oxt file to ../share/extension/install and then invokes a post-install script (Unix) or a custom action (Windows) which runs unopkg to install the extension properly. The extension is then unzipped to ../share/uno_packages/cache/uno_packages and some data are added to the extension manager database. The installer only knows the file that it copied to the ../share/extension/install folder. If it is there then it is regarded as installed – otherwise not.

For an extension to show up in the dialog of the extension manager, there are two conditions which need to be met. First, it must be unpacked in the uno_packages folder. And second, there must be an appropriate entry in the extension manager database, indicating that it is installed. Therefore it would be possible that the installer displayed an extension as being installed but the extension manager did not. This may of course happen the other way round as well.

Even if the installer would copy the uncompressed extension directly to ../share/uno_packages/cache/uno_packages, both dialogs could show a different status. One could assume that the installer and extension manager regard an extension as installed if the the respective folder exists. But this does not work, because the extension manager does not remove immediately the extension when it is being uninstalled. The reason is, that files from the extension can still be in use in the process. Only after restarting OOo and the extension manager, the extension's folder will be finally removed.

===Code execution during installation===
Copying extensions into the office installation during setup is not sufficient to make them usable. Only after the extension manager has processed them, OOo can make use of them. Therefore the installer invokes the extension manager after an extension has been copied. Unfortunately this requires different solutions for different platforms. RPM (Linux) and PKG (Solaris) use post-install/pre-install scripts which are executed after the copying step. But there are installation scenarios on Solaris, where code execution is not allowed during the setup. For example, the installer is running on Solaris Sparc and installs OOo on a Solaris Intel Machine machine. Therefore OOo uses a “postrun” service which invokes the extension manager when the system is rebooted. OpenSolaris prohibits code execution completely. The setup needs to install an SMF service which is triggered after the setup. Windows needs a 'custom action' which is compiled native code. The Mac dmg file already contains the processed extensions. That is, the extension manager processes the extension while building the dmg file.

It is obvious that the current situation is complex and one understands why testing and bug finding are rather difficult.

===Extension Manager database===
The database is created when the extension manager is started for the first time. The database contains different files and folders which are completely unknown to the installer. Therefore the installer will not remove them. This is another reason why the OpenOffice.org folder remains on the system after uninstalling OOo.

=== License of shared extension cannot be displayed to users ===
Only the one who installs the extension can see the license.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Extension Layers

2010-07-02T10:04:33Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Location of Installed Extensions
|NextPage=Documentation/DevGuide/Extensions/Checklist for Writing Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Extension Manager Rework}}
__NOTOC__
The Extension Manager uses two extension layers, the user and the shared layer. Extensions installed in the shared layer can be used by all users whereas those in the user layer can only be used by the user who installed them. An extension can be installed in either layer or both.

This system was developed many years ago. Since then new features were added, such as extension versioning, online update, bundled extensions, etc. During that time it became obvious that there are some problems with the original design. This document tries to explain them.
==Current problems==

=== Hiding ===
The idea of layers is that extensions in the top layer '''hide''' the same extensions in the layer below. In other words, the extension in the highest layer will be given preference, when resources from the extension are requested. Because the user layer is the top layer, a shared extension is only used when the same extension does not exist in the user layer. The version of the extension has no influence.

This, however, is only a simplified model. An extension is never used as a whole. Instead clients access the particular contents, such as components, configuration data, etc. And it is also these contents which obscure the same content in a lower layer. For example, an extension contains a UNO service, which is installed in both layers. When the client instantiates it then the one from the top layer is used.

There are situations where contents of the shared extensions are still used, although they should be hidden and therefore not usable. Assuming there are version 1 and version 2 of an extension. Then the different versions may have different content. For example, version 1 may contain a service ''foo'' which is not contained in version 2. If now version 1 is installed in the shared layer and version 2 in the user layer then ''foo'' is still around and can be instantiated. Foo may access resources which are also delivered with this extension and are also available in version 2 which is in the user layer. Resources in version 2, which hide those from version 1 (same node in xcu or same service), can be incompatible, so that foo fails.

A service may also need files which are part of the same extension and which are only directly accessible. That is there is no API, such as the registry or service manager, which can provide the content. A "running" service does not know from which layer it comes from. To get the install location it can use the [[Documentation/DevGuide/Extensions/Location of Installed Extensions|PackageInformationProvider]]. This service will first look into user layer and if the extension cannot be found, then it will look into the shared layer. If now the service from the shared layer needs some file from its extension, then it may accidentally use the one from a different version of the extension in the user layer. This file can be incompatible or not even exist and make the service fail.

Another example can be constructed using registry values, which are contained in xcu files. Let's assume that version 1 of an extension adds a menu ''foo'' and version 2 adds menu ''bar''. If one extension is installed in the share and the other in the user layer, then both menus appear. This is because the nodes of the configuration files are merged into the configuration and not the xcu files itself. That is, if the extensions contain an xcu file with the same name, then the xcu file of the last installed extension will NOT replace the one from the other extension. The second xcu file can, however, change the values for nodes which have been defined by the first xcu.

These examples prove that the layering (in terms of hiding the items from the layer below) on extension level does not work, although it does for the respective [[Documentation/DevGuide/Extensions/Deployment Items|deployment items]]. And it may be safe to say, that this goes against the user's expectation.

===Unclear behavior===
It may be unclear to users how the behavior is when the same extension is installed as user and shared extension. If there is a shared extension and the same extension is installed as user extension, then the user should be informed that the currently installed extension will become 'inactive'. Then, when the user extension is uninstalled, the user should be informed that the shared extension will become 'active' again.

=== Extension versions ===

As already observed, the version of an extension has no influence on the decision if the extension from the user or the shared layer is used. At the time of developing the extension framework there was no support for versioned extensions, so one did not have to care about them. Later, we recognized that an extension version is useful for users. For example, if one has an extension installed and is installing the same extension again, then one is being informed about what extension has the later version (so one can decide which is the best for them).

I think the general expectation is that the latest version is the best. Therefore it should be natural that OOo uses always that one. However, this is not the case and users may unintentionally prevent, that they use the latest extension. For example, OOo comes with a bundled English dictionary. Now a user installs, intentionally or not, the same extension and forgets about it. The administrator updates OOo regularly, which also updates the dictionary with the latest version. But the user would still use the old dictionary, because that is the one from the user layer which hides the one from the shared layer.

One could think now of a notification for the user but there are some questions:
*when does OOo check for this situation?
*how can this be explained to the user?
The first question, is easily answered: At every start-up.

The second question is more difficult.Think about a message, such as: "Dear user. You cannot use the latest version of the french dictionary, which is installed in the shared/bundled layer. Instead the dictionary which you installed earlier is used. You need to uninstall it, if you want the new version ...."
Many users would probably not understand this. So the easiest and natural way is simply to use the latest version of the extension indepedent of what layer it is installed in. The term layer should then be replaced, by repository, indicating that the location does not include a preference – just think about the picture of one layer above the other compared to repositories which are arranged in one row.

=== Layer location ===

The shared layer is located within the OOo installation. The benefit is that normal users cannot modify it. The layer will be modified after installation of OOo when an extensions is added, deleted, enabled or disabled. Depending on the operation system, this may be against the system guidelines. For example, it would be not allowed on Windows Vista/ 7. However, to allow “legacy application” to work Microsoft invented the virtual store.

=== Clean uninstallation ===

Modification of the shared layer will also prevent the clean uninstallation of OOo. This is because the native installer does not “own” the files/folder which were added by the extension manager. For example, on Linux the path /opt/openoffice.org3/share/uno_packages will remain on the system. On OpenSolaris the shared extensions (with the same directory structure) will be copied to /var/lost+found on uninstallation.

=== No Separation of shared and bundled extensions ===
The rule is, whatever a user installed should not be removed by OOo. This is also valid for shared extensions. Today a bundled extension is nothing else than a shared extension and therefore can be modified by users, provided they have sufficient file access rights. They can install the same extension as one, which was installed as bundled extension, in the shared layer. This means that the original bundled extension is replaced by the recently installed shared extension. This can happen in two scenarios. The first one is during an online update of the extension and the second is when the extension is “manually” installed. In these cases users intentionally choose to replace the original extension. Therefore this extension may not be deleted when uninstalling OOo. This, however, requires to know that the bundled extension was replaced, but there is currently no way to recognize this.

===Selection of extensions in setup===
Like many other features, bundled extensions should be selectable in the dialog of the installer. The installer can also be invoked later to add or remove particular features. The problem is, that the extensions which the installer “sees” are not the same as “seen” by the extension manager. The setup copies an oxt file to ../share/extension/install and then invokes a post-install script (Unix) or a custom action (Windows) which runs unopkg to install the extension properly. The extension is then unzipped to ../share/uno_packages/cache/uno_packages and some data are added to the extension manager database. The installer only knows the file that it copied to the ../share/extension/install folder. If it is there then it is regarded as installed – otherwise not.

For an extension to show up in the dialog of the extension manager, there are two conditions which need to be met. First, it must be unpacked in the uno_packages folder. And second, there must be an appropriate entry in the extension manager database, indicating that it is installed. Therefore it would be possible that the installer displayed an extension as being installed but the extension manager did not. This may of course happen the other way round as well.

Even if the installer would copy the uncompressed extension directly to ../share/uno_packages/cache/uno_packages, both dialogs could show a different status. One could assume that the installer and extension manager regard an extension as installed if the the respective folder exists. But this does not work, because the extension manager does not remove immediately the extension when it is being uninstalled. The reason is, that files from the extension can still be in use in the process. Only after restarting OOo and the extension manager, the extension's folder will be finally removed.

===Code execution during installation===
Copying extensions into the office installation during setup is not sufficient to make them usable. Only after the extension manager has processed them, OOo can make use of them. Therefore the installer invokes the extension manager after an extension has been copied. Unfortunately this requires different solutions for different platforms. RPM (Linux) and PKG (Solaris) use post-install/pre-install scripts which are executed after the copying step. But there are installation scenarios on Solaris, where code execution is not allowed during the setup. For example, the installer is running on Solaris Sparc and installs OOo on a Solaris Intel Machine machine. Therefore OOo uses a “postrun” service which invokes the extension manager when the system is rebooted. OpenSolaris prohibits code execution completely. The setup needs to install an SMF service which is triggered after the setup. Windows needs a 'custom action' which is compiled native code. The Mac dmg file already contains the processed extensions. That is, the extension manager processes the extension while building the dmg file.

It is obvious that the current situation is complex and one understands why testing and bug finding are rather difficult.

===Extension Manager database===
The database is created when the extension manager is started for the first time. The database contains different files and folders which are completely unknown to the installer. Therefore the installer will not remove them. This is another reason why the OpenOffice.org folder remains on the system after uninstalling OOo.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

How to use digital Signatures

2010-06-23T06:25:30Z

Jl:

'''1. Where to get a Certificate'''

First of all you need a valid digital certificate. You can get one for free by various Security Providers, for Germany especially for people from Hamburg, you can get such a certificate from the Trustcenter ([http://www.trustcenter.de]), other people may have a look at Comodo([http://www.comodo.com/products/certificate_services/email_certificate.html]), StartSSL ([http://www.startssl.com]) or CAcert ([http://www.cacert.org]). These companies offer such a certificate for free with an expiration time of one year. After that you have to renew it if you like. If not you will not be able to sign documents any longer.

If you do not trust these companies or want a higher Class Certificate you need to pay some money and the company will validate your personal data to make sure that you are the one you say you are. Such companies are Globalsign ([http://www.globalsign.com]), Verisign ([http://www.verisign.com]) and also Trustcenter and StartSSL. In combination with a Freemail Account you can get a digital certificate for Germany at Web.de ([http://www.web.de]).

'''1.1 How to make a certificate useable for [[StarOffice]]'''

If you follow the process to get a certificate this will be installed into the keystore of your Browser. Mozilla users will find it under Privacy & Security in the Option dialog of their Browser. Firefox user will find it at a similar place. The few people using Microsoft's Internet Explorer will find it under Start-Settings-Control Panel-Internet Options-Content-Certificates.

This information is needed as [[StarOffice]] / OpenOffice.org relies on the Crypto engine used on the users system. On Windows the Microsoft Crypto API is used, therefore nothing has to be done if the Internet Explorer was used to get the Certificate. In case you've used Mozilla or Firefox, you have to export your certificate into a file from the Mozilla Certificate store and import it into the Microsoft keystore. To do so, just go to your settings dialog in Mozilla and choose :

-Manage Certificates from it.
-Select the Certificate to export and click on the button Backup
-Find a place were you can save the file and name it
-Follow the instructions given by Mozilla
-To import the Certificate into the Microsoft Cryptoengine, do the following:
-travel to the location of the now exported file by using your preferred file manager and
-double click the file.
-Follow the instructions and that's it.
-You have transferred your certificate into the Microsoft keystore of your Windows installation.

For Linux and Solaris this procedure may be used the other way to get a certificate from Windows into the keystores of Mozilla, Thunderbird or Firefox.

'''1.1.1 Prerequisites on Linux / Solaris'''

To use your Certificate for digital signing of documents on Linux or Solaris we need some prerequisites :

- A certificate (obtained from a Certificate Authority)
- A Thunderbird, Mozilla or Firefox profile to store the certificate

[[StarOffice]] / OpenOffice.org is looking for a certificate in the mentioned profiles according to the following search order :

a.) The environment variable MOZILLA_CERTIFICATE_FOLDER
b.) The Thunderbird profile
c.) The Mozilla suite profile
d.) The Firefox profile.

This is especially useful to know as Debian and maybe Fedora Linux Installations seem to set the profile names in an other way as suggested by the Mozilla developers. In this case the Certificates are not shown in the digital signature dialog of the Office suite. In this case, locate the appropriate profile folder and set the Environment Variable MOZILLA_CERTIFICATE_FOLDER accordingly. See [[Certificate Detection|Certificate Detection]]

It is also necessary that the trust settings for the root certificates are set to trust the certificate to identify web sites and e-mail users.

'''1.1.2 Prerequisites on Windows'''

As you need only a valid certificate located in the keystore of the Windows Crypto API and we have installed it under Chapter 1.1, there are no more Prerequisites for Windows.

'''1.2 Using card readers'''

There are loads of different types of readers and smart cards. Please read first the documentation of your reader and card and install all necessary software which comes with it.

If you use Linux, then follow the documentation about how to add smart card support to Firefox/Thunderbird. In general, this will require to add a particular library (a pkcs11 module) in the device manager (security devices) in Firefox/Thunderbird. The device manager can be found in the options dialog under the Advanced tab page.

With some readers/cards it is sufficient to install opensc and pcscd. pcscd is a deamon, which is located in /etc/init.d. Then one has to add opensc-pkcs11.so, which may be found under /usr/lib, in the device manager.

'''2. How to sign a document'''

Edit the document you want to sign and save it. Now select Digital Signatures from the File Menu. If you get a warning about a missing Mozilla profile, have a look at chapter 1.1.1 please. You probably use a Debian or Fedora Linux and haven't set the environment variable in the correct way.

If all is properly set, you get the digital signatures dialog and can click on the Add button. On Linux and Solaris you're asked for the password for accessing the used keystore, on Windows it depends on the settings made on importing the certificate. Now your stored certificates are shown. Please select the one you want to use and than click on Ok. After that you will be back in [[StarOffice]] / OpenOffice.org Digital Signatures dialog. This dialog will show a small icon in front of the textual representation of the certificate used to sign the Document.

<br> '''2.1 How to sign a Macro'''

To sign a Macro you have two possible ways.

1.)Use Tools – Macro – Digital Signature
2.)Use File – Digital Signature within the BASIC Editor of [[StarOffice]] / OpenOffice.org

The procedure of adding a certificate to the Macro is the same as used for documents.

'''3. Error messages and visual aids'''

'''3.1 Error messages on loading of documents'''

You only get a message on loading the document if the signature of the document and / or the signature of the containing macros is broken. In this case the execution of macros is stopped and you can only activate macros by setting the security level to low and re-loading the document. But this is not recommended. Or remove the broken signature from the document and reload it. In this case make sure the macros contained in the document are not malicious.

'''3.2 Visual Aids'''

We have four visual aids for the possible states of a document signature.

A sheet with a stylised red seal stating that the document signature(s) are OK and no alteration of the document occurred since the last signing.

The addition (signed) to the title bar of an opened signed document.

A sheet with a stylised red seal and a small yellow triangle with exclamation mark stating that the document signature(s) are OK and no alteration of the document occurred since the last signing but at least one of the used certificates could not be validated. This can be caused by a not available root certificate from the Issuer of one of the certificates used or a not possible connection to the server containing the Revocation List for the Certificate Issuer. This is just an informal message, the document itself isn't changed after signing. But the decision on how far you can trust this document is up to you. The used certificate is maybe outdated or revoked.

A yellow triangle with black exclamation mark showing that the document signature is broken. So this document has been altered in some way and therefore you should not trust it's content.

These visual aids will be displayed in the digital signature dialog and the status bar. For the '(signed)' text, this one is shown in the title bar of the document window next to the file name.

'''4. Trusted Macro Source'''

To add a certificate as a trusted macro source, open a document signed with the certificate you want to trust. Then use the dialog that pops up to always trust macros from that source.

= See also =

*[[Certificate Detection|Certificate Detection]]
*[http://blogs.sun.com/roller/page/dancer/20050308 Just switch! - Secure document exchange with StarOffice 8 ]
*[http://marketing.openoffice.org/ooocon2004/presentations/friday/timmermann_digital_signatures.pdf Digital signatures (SUN-pdf file)]

[[Category:Digital_Signature]]

How to use digital Signatures

2010-06-23T06:06:41Z

Jl: Adding a not about card readers

'''1. Where to get a Certificate'''

First of all you need a valid digital certificate. You can get one for free by various Security Providers, for Germany especially for people from Hamburg, you can get such a certificate from the Trustcenter ([http://www.trustcenter.de]), other people may have a look at Comodo([http://www.comodo.com/products/certificate_services/email_certificate.html]), StartSSL ([http://www.startssl.com]) or CAcert ([http://www.cacert.org]). These companies offer such a certificate for free with an expiration time of one year. After that you have to renew it if you like. If not you will not be able to sign documents any longer.

If you do not trust these companies or want a higher Class Certificate you need to pay some money and the company will validate your personal data to make sure that you are the one you say you are. Such companies are Globalsign ([http://www.globalsign.com]), Verisign ([http://www.verisign.com]) and also Trustcenter and StartSSL. In combination with a Freemail Account you can get a digital certificate for Germany at Web.de ([http://www.web.de]).

'''1.1 How to make a certificate useable for [[StarOffice]]'''

If you follow the process to get a certificate this will be installed into the keystore of your Browser. Mozilla users will find it under Privacy & Security in the Option dialog of their Browser. Firefox user will find it at a similar place. The few people using Microsoft's Internet Explorer will find it under Start-Settings-Control Panel-Internet Options-Content-Certificates.

This information is needed as [[StarOffice]] / OpenOffice.org relies on the Crypto engine used on the users system. On Windows the Microsoft Crypto API is used, therefore nothing has to be done if the Internet Explorer was used to get the Certificate. In case you've used Mozilla or Firefox, you have to export your certificate into a file from the Mozilla Certificate store and import it into the Microsoft keystore. To do so, just go to your settings dialog in Mozilla and choose :

-Manage Certificates from it.
-Select the Certificate to export and click on the button Backup
-Find a place were you can save the file and name it
-Follow the instructions given by Mozilla
-To import the Certificate into the Microsoft Cryptoengine, do the following:
-travel to the location of the now exported file by using your preferred file manager and
-double click the file.
-Follow the instructions and that's it.
-You have transferred your certificate into the Microsoft keystore of your Windows installation.

For Linux and Solaris this procedure may be used the other way to get a certificate from Windows into the keystores of Mozilla, Thunderbird or Firefox.

'''1.1.1 Prerequisites on Linux / Solaris'''

To use your Certificate for digital signing of documents on Linux or Solaris we need some prerequisites :

- A certificate (obtained from a Certificate Authority)
- A Thunderbird, Mozilla or Firefox profile to store the certificate

[[StarOffice]] / OpenOffice.org is looking for a certificate in the mentioned profiles according to the following search order :

a.) The environment variable MOZILLA_CERTIFICATE_FOLDER
b.) The Thunderbird profile
c.) The Mozilla suite profile
d.) The Firefox profile.

This is especially useful to know as Debian and maybe Fedora Linux Installations seem to set the profile names in an other way as suggested by the Mozilla developers. In this case the Certificates are not shown in the digital signature dialog of the Office suite. In this case, locate the appropriate profile folder and set the Environment Variable MOZILLA_CERTIFICATE_FOLDER accordingly. See [[Certificate Detection|Certificate Detection]]

It is also necessary that the trust settings for the root certificates are set to trust the certificate to identify web sites and e-mail users.

'''1.1.2 Prerequisites on Windows'''

As you need only a valid certificate located in the keystore of the Windows Crypto API and we have installed it under Chapter 1.1, there are no more Prerequisites for Windows.

'''1.2 Using card readers'''

There are loads of different types of readers and smart cards. Please read first the documentation of your reader and card and install all necessary software which comes with it.

If you use Linux, then follow the documentation about how to add smart card support to Firefox/Thunderbird. In general, this will require to add a particular library (a pkcs11 module) in the device manager (security devices) in Firefox/Thunderbird. The device manager can be found in the options dialog under the Advanced tab page.

With some readers/cards it is sufficient to install opensc. Then one has to add opensc-pkcs11.so, which may be found under /usr/lib, in the device manager.

'''2. How to sign a document'''

Edit the document you want to sign and save it. Now select Digital Signatures from the File Menu. If you get a warning about a missing Mozilla profile, have a look at chapter 1.1.1 please. You probably use a Debian or Fedora Linux and haven't set the environment variable in the correct way.

If all is properly set, you get the digital signatures dialog and can click on the Add button. On Linux and Solaris you're asked for the password for accessing the used keystore, on Windows it depends on the settings made on importing the certificate. Now your stored certificates are shown. Please select the one you want to use and than click on Ok. After that you will be back in [[StarOffice]] / OpenOffice.org Digital Signatures dialog. This dialog will show a small icon in front of the textual representation of the certificate used to sign the Document.

<br> '''2.1 How to sign a Macro'''

To sign a Macro you have two possible ways.

1.)Use Tools – Macro – Digital Signature
2.)Use File – Digital Signature within the BASIC Editor of [[StarOffice]] / OpenOffice.org

The procedure of adding a certificate to the Macro is the same as used for documents.

'''3. Error messages and visual aids'''

'''3.1 Error messages on loading of documents'''

You only get a message on loading the document if the signature of the document and / or the signature of the containing macros is broken. In this case the execution of macros is stopped and you can only activate macros by setting the security level to low and re-loading the document. But this is not recommended. Or remove the broken signature from the document and reload it. In this case make sure the macros contained in the document are not malicious.

'''3.2 Visual Aids'''

We have four visual aids for the possible states of a document signature.

A sheet with a stylised red seal stating that the document signature(s) are OK and no alteration of the document occurred since the last signing.

The addition (signed) to the title bar of an opened signed document.

A sheet with a stylised red seal and a small yellow triangle with exclamation mark stating that the document signature(s) are OK and no alteration of the document occurred since the last signing but at least one of the used certificates could not be validated. This can be caused by a not available root certificate from the Issuer of one of the certificates used or a not possible connection to the server containing the Revocation List for the Certificate Issuer. This is just an informal message, the document itself isn't changed after signing. But the decision on how far you can trust this document is up to you. The used certificate is maybe outdated or revoked.

A yellow triangle with black exclamation mark showing that the document signature is broken. So this document has been altered in some way and therefore you should not trust it's content.

These visual aids will be displayed in the digital signature dialog and the status bar. For the '(signed)' text, this one is shown in the title bar of the document window next to the file name.

'''4. Trusted Macro Source'''

To add a certificate as a trusted macro source, open a document signed with the certificate you want to trust. Then use the dialog that pops up to always trust macros from that source.

= See also =

*[[Certificate Detection|Certificate Detection]]
*[http://blogs.sun.com/roller/page/dancer/20050308 Just switch! - Secure document exchange with StarOffice 8 ]
*[http://marketing.openoffice.org/ooocon2004/presentations/friday/timmermann_digital_signatures.pdf Digital signatures (SUN-pdf file)]

[[Category:Digital_Signature]]

Setup - Bundled Extensions

2010-06-15T11:00:53Z

Jl: /* Configuration */

=Setup - Bundled Extensions=

{{Specification_Header|Lutz Hoeger|Jun 15, 2010|Standard}}

== Abstract ==
Pre-bundled extensions - such as dictionaries for spell checking - will be displayed in the OOo installer module selection (during custom installation). This allows users to gain more control over what will be installed on their system. At the same time, managing such pre-bundled extensions (remove, update) will be moved from the extension manager into the application installer.

__TOC__

== References ==

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Reference Document''' || bgcolor="#dddddd" | '''Check''' || bgcolor="#dddddd" | '''Location (URL)'''
|-
| '''Product Requirement, RFE, Issue ID''' (required)
| [available]
| http://www.openoffice.org/issues/show_bug.cgi?id=112404
|-
| '''[[Test case specification]]''' (required)
| [available/not available]
| <PLEASE ENTER LOCATION HERE>
|-
|}

== Contacts ==

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Role''' || bgcolor="#dddddd" | '''Name''' || bgcolor="#dddddd" | '''E-Mail Address'''
|-
| '''Developer'''
| Joachim Lingner
| jl@openoffice.org
|-
| '''Quality Assurance'''
| Olaf Felka
| of@openoffice.org
|-
| '''Documentation'''
| Uwe Fischer
| ufi@openoffice.org
|-
|}

== Detailed Specification ==
* Pre-bundled extensions - such as dictionaries for spell checking - will be displayed in the OOo installer module selection (during custom installation).
* At the same time, managing such pre-bundled extensions (remove, update) will be moved from the extension manager into the application installer.
* On Windows and Unix, user can de-select items; on Mac, all items will be installed
* Display of Dictionaries:
** Location in setup: Optional Components, #3 after Java
** Module name: Dictionaries
** Module description: Spelling and hyphenation dictionaries and thesauri
** Default: ON (incl. all sub-modules, according to spellchecker selection per language specific installation set)
** Sub-modules: See list below.

=== Dictionaries ===
Note: The set of dictionaries actually included in a language specific installation set – or in a multi language set – does not change. The following list just enlists all dictionary languages possibly shipped in OOo.

The set of languages display in setup should be sorted alphabetically by Module name.

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Language''' || bgcolor="#dddddd" | '''Module Name''' || bgcolor="#dddddd" | '''Module descrition'''
|-
| af
| Afrikaans
| Afrikaans spell checker
|-
| pt
| Brazilian Portuguese
| Brazilian Portuguese Spelling Dictionary - 1990 Spelling Agreement
|-
| ca
| Catalan
| Spelling and hyphenation dictionaries and thesaurus for Catalan language (general)
|-
| cs
| Czech
| Czech thesaurus
|-
| da
| Danish
| Spelling and hyphenation dictionary for Danish
|-
| nl
| Dutch
| Dutch spelling and hyphenation dictionaries
|-
| en-US
| English
| English spelling and hyphenation dictionaries and thesaurus
|-
| et
| Estonian
| Estonian spelling and hyphenation dictionaries
|-
| fr
| French
| French "Classic and Reform 1990" spelling, thesaurus and hyphenation
|-
| gl
| Galician
| Galician spellchecker dictionary for OpenOffice.org
|-
| de-AT
| German (Austria)
| German (AT-frami) spelling, hyphenation, thesaurus
|-
| de-DE
| German (Germany)
| German (DE-frami) spelling, hyphenation, thesaurus
|-
| de-CH
| German (Switzerland)
| German (CH-frami) spelling, hyphenation, thesaurus
|-
| he
| Hebrew
| Hebrew spell check dictionary
|-
| hu
| Hungarian
| Hungarian spelling dictionary, hyphenation patterns, and thesaurus
|-
| it
| Italian
| Italian spelling and hyphenation dictionaries and thesaurus
|-
| ku-TR
| Kurdish (Turkey)
| Kurdish (Turkey) spell check dictionary
|-
| lt
| Lithuanian
| Lithuanian spelling and hyphenation dictionaries
|-
| ne
| Nepali
| Nepali spelling dictionary and thesaurus
|-
| no
| Norwegian
| Norwegian dictionaries (Nynorsk and Bokmål)
|-
| pl
| Polish
| Polish spell check dictionary, hyphenation rules and thesaurus
|-
| ro
| Romanian
| Romanian Dictionaries
|-
| ru
| Russian
| Russian hyphenation dictionary and thesaurus
|-
| sr
| Serbian
| Serbian spelling and hyphenation dictionaries
|-
| sk
| Slovak
| Slovak spell check dictionary, hyphenation rules and thesaurus
|-
| sl
| Slovenian
| Slovenian dictionary pack
|-
| es
| Spanish
| Spanish spelling dictionary
|-
| sw
| Swahili
| Swahili spelling dictionary
|-
| sv
| Swedish
| Swedish Dictionary
|-
| th
| Thai
| Thai spelling dictionary
|-
| vi
| Vietnamese
| Vietnamese spellchecker dictionary
|-
| zu
| Zulu
| Zulu hyphenation dictionary
|-
|}

[[Specification_Template_Help#Detailed_Specification|Help]] | [[UI-Elements|User Interface Element Templates]] | [[Specification_Example|Example Spec]]

== Accessibility ==
Accessibility not impacted.

== Migration ==
Bundled dictionaries in OOo versions previous to 3.3 were installed as shared extensions. Shared extensions are not migrated.

As of 3.3 bundled extensions will always be removed when uninstalling OOo. They are therefore not eligible for being migrated.

== Configuration ==
Bundled extensions, such as the dictionaries, can be configured if they provide their own options pages in OOo's options dialog.

[[Specification_Template_Help#Configuration|Help]] | [[Configuration-Table|Configuration Table Template]]

== Open Issues ==
* Pre-bundled extensions still show up in the Extension Manager. This is considered a minor impact, as the user cannot change such extension in this place. Issue will be resolved in the future.

[[Category:Specification]]

Setup - Bundled Extensions

2010-06-15T10:58:14Z

Jl: /* Migration */

=Setup - Bundled Extensions=

{{Specification_Header|Lutz Hoeger|Jun 15, 2010|Standard}}

== Abstract ==
Pre-bundled extensions - such as dictionaries for spell checking - will be displayed in the OOo installer module selection (during custom installation). This allows users to gain more control over what will be installed on their system. At the same time, managing such pre-bundled extensions (remove, update) will be moved from the extension manager into the application installer.

__TOC__

== References ==

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Reference Document''' || bgcolor="#dddddd" | '''Check''' || bgcolor="#dddddd" | '''Location (URL)'''
|-
| '''Product Requirement, RFE, Issue ID''' (required)
| [available]
| http://www.openoffice.org/issues/show_bug.cgi?id=112404
|-
| '''[[Test case specification]]''' (required)
| [available/not available]
| <PLEASE ENTER LOCATION HERE>
|-
|}

== Contacts ==

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Role''' || bgcolor="#dddddd" | '''Name''' || bgcolor="#dddddd" | '''E-Mail Address'''
|-
| '''Developer'''
| Joachim Lingner
| jl@openoffice.org
|-
| '''Quality Assurance'''
| Olaf Felka
| of@openoffice.org
|-
| '''Documentation'''
| Uwe Fischer
| ufi@openoffice.org
|-
|}

== Detailed Specification ==
* Pre-bundled extensions - such as dictionaries for spell checking - will be displayed in the OOo installer module selection (during custom installation).
* At the same time, managing such pre-bundled extensions (remove, update) will be moved from the extension manager into the application installer.
* On Windows and Unix, user can de-select items; on Mac, all items will be installed
* Display of Dictionaries:
** Location in setup: Optional Components, #3 after Java
** Module name: Dictionaries
** Module description: Spelling and hyphenation dictionaries and thesauri
** Default: ON (incl. all sub-modules, according to spellchecker selection per language specific installation set)
** Sub-modules: See list below.

=== Dictionaries ===
Note: The set of dictionaries actually included in a language specific installation set – or in a multi language set – does not change. The following list just enlists all dictionary languages possibly shipped in OOo.

The set of languages display in setup should be sorted alphabetically by Module name.

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Language''' || bgcolor="#dddddd" | '''Module Name''' || bgcolor="#dddddd" | '''Module descrition'''
|-
| af
| Afrikaans
| Afrikaans spell checker
|-
| pt
| Brazilian Portuguese
| Brazilian Portuguese Spelling Dictionary - 1990 Spelling Agreement
|-
| ca
| Catalan
| Spelling and hyphenation dictionaries and thesaurus for Catalan language (general)
|-
| cs
| Czech
| Czech thesaurus
|-
| da
| Danish
| Spelling and hyphenation dictionary for Danish
|-
| nl
| Dutch
| Dutch spelling and hyphenation dictionaries
|-
| en-US
| English
| English spelling and hyphenation dictionaries and thesaurus
|-
| et
| Estonian
| Estonian spelling and hyphenation dictionaries
|-
| fr
| French
| French "Classic and Reform 1990" spelling, thesaurus and hyphenation
|-
| gl
| Galician
| Galician spellchecker dictionary for OpenOffice.org
|-
| de-AT
| German (Austria)
| German (AT-frami) spelling, hyphenation, thesaurus
|-
| de-DE
| German (Germany)
| German (DE-frami) spelling, hyphenation, thesaurus
|-
| de-CH
| German (Switzerland)
| German (CH-frami) spelling, hyphenation, thesaurus
|-
| he
| Hebrew
| Hebrew spell check dictionary
|-
| hu
| Hungarian
| Hungarian spelling dictionary, hyphenation patterns, and thesaurus
|-
| it
| Italian
| Italian spelling and hyphenation dictionaries and thesaurus
|-
| ku-TR
| Kurdish (Turkey)
| Kurdish (Turkey) spell check dictionary
|-
| lt
| Lithuanian
| Lithuanian spelling and hyphenation dictionaries
|-
| ne
| Nepali
| Nepali spelling dictionary and thesaurus
|-
| no
| Norwegian
| Norwegian dictionaries (Nynorsk and Bokmål)
|-
| pl
| Polish
| Polish spell check dictionary, hyphenation rules and thesaurus
|-
| ro
| Romanian
| Romanian Dictionaries
|-
| ru
| Russian
| Russian hyphenation dictionary and thesaurus
|-
| sr
| Serbian
| Serbian spelling and hyphenation dictionaries
|-
| sk
| Slovak
| Slovak spell check dictionary, hyphenation rules and thesaurus
|-
| sl
| Slovenian
| Slovenian dictionary pack
|-
| es
| Spanish
| Spanish spelling dictionary
|-
| sw
| Swahili
| Swahili spelling dictionary
|-
| sv
| Swedish
| Swedish Dictionary
|-
| th
| Thai
| Thai spelling dictionary
|-
| vi
| Vietnamese
| Vietnamese spellchecker dictionary
|-
| zu
| Zulu
| Zulu hyphenation dictionary
|-
|}

[[Specification_Template_Help#Detailed_Specification|Help]] | [[UI-Elements|User Interface Element Templates]] | [[Specification_Example|Example Spec]]

== Accessibility ==
Accessibility not impacted.

== Migration ==
Bundled dictionaries in OOo versions previous to 3.3 were installed as shared extensions. Shared extensions are not migrated.

As of 3.3 bundled extensions will always be removed when uninstalling OOo. They are therefore not eligible for being migrated.

== Configuration ==
<START TYPING HERE --- If this part is irrelevant state a reason for its absence.>

[[Specification_Template_Help#Configuration|Help]] | [[Configuration-Table|Configuration Table Template]]

== Open Issues ==
* Pre-bundled extensions still show up in the Extension Manager. This is considered a minor impact, as the user cannot change such extension in this place. Issue will be resolved in the future.

[[Category:Specification]]

Setup - Bundled Extensions

2010-06-15T10:52:59Z

Jl: /* Contacts */

=Setup - Bundled Extensions=

{{Specification_Header|Lutz Hoeger|Jun 15, 2010|Standard}}

== Abstract ==
Pre-bundled extensions - such as dictionaries for spell checking - will be displayed in the OOo installer module selection (during custom installation). This allows users to gain more control over what will be installed on their system. At the same time, managing such pre-bundled extensions (remove, update) will be moved from the extension manager into the application installer.

__TOC__

== References ==

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Reference Document''' || bgcolor="#dddddd" | '''Check''' || bgcolor="#dddddd" | '''Location (URL)'''
|-
| '''Product Requirement, RFE, Issue ID''' (required)
| [available]
| http://www.openoffice.org/issues/show_bug.cgi?id=112404
|-
| '''[[Test case specification]]''' (required)
| [available/not available]
| <PLEASE ENTER LOCATION HERE>
|-
|}

== Contacts ==

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Role''' || bgcolor="#dddddd" | '''Name''' || bgcolor="#dddddd" | '''E-Mail Address'''
|-
| '''Developer'''
| Joachim Lingner
| jl@openoffice.org
|-
| '''Quality Assurance'''
| Olaf Felka
| of@openoffice.org
|-
| '''Documentation'''
| Uwe Fischer
| ufi@openoffice.org
|-
|}

== Detailed Specification ==
* Pre-bundled extensions - such as dictionaries for spell checking - will be displayed in the OOo installer module selection (during custom installation).
* At the same time, managing such pre-bundled extensions (remove, update) will be moved from the extension manager into the application installer.
* On Windows and Unix, user can de-select items; on Mac, all items will be installed
* Display of Dictionaries:
** Location in setup: Optional Components, #3 after Java
** Module name: Dictionaries
** Module description: Spelling and hyphenation dictionaries and thesauri
** Default: ON (incl. all sub-modules, according to spellchecker selection per language specific installation set)
** Sub-modules: See list below.

=== Dictionaries ===
Note: The set of dictionaries actually included in a language specific installation set – or in a multi language set – does not change. The following list just enlists all dictionary languages possibly shipped in OOo.

The set of languages display in setup should be sorted alphabetically by Module name.

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em 0; border: 1px #cccccc solid; border-collapse: collapse; width: 100%"
|-
| width="300" bgcolor="#dddddd" | '''Language''' || bgcolor="#dddddd" | '''Module Name''' || bgcolor="#dddddd" | '''Module descrition'''
|-
| af
| Afrikaans
| Afrikaans spell checker
|-
| pt
| Brazilian Portuguese
| Brazilian Portuguese Spelling Dictionary - 1990 Spelling Agreement
|-
| ca
| Catalan
| Spelling and hyphenation dictionaries and thesaurus for Catalan language (general)
|-
| cs
| Czech
| Czech thesaurus
|-
| da
| Danish
| Spelling and hyphenation dictionary for Danish
|-
| nl
| Dutch
| Dutch spelling and hyphenation dictionaries
|-
| en-US
| English
| English spelling and hyphenation dictionaries and thesaurus
|-
| et
| Estonian
| Estonian spelling and hyphenation dictionaries
|-
| fr
| French
| French "Classic and Reform 1990" spelling, thesaurus and hyphenation
|-
| gl
| Galician
| Galician spellchecker dictionary for OpenOffice.org
|-
| de-AT
| German (Austria)
| German (AT-frami) spelling, hyphenation, thesaurus
|-
| de-DE
| German (Germany)
| German (DE-frami) spelling, hyphenation, thesaurus
|-
| de-CH
| German (Switzerland)
| German (CH-frami) spelling, hyphenation, thesaurus
|-
| he
| Hebrew
| Hebrew spell check dictionary
|-
| hu
| Hungarian
| Hungarian spelling dictionary, hyphenation patterns, and thesaurus
|-
| it
| Italian
| Italian spelling and hyphenation dictionaries and thesaurus
|-
| ku-TR
| Kurdish (Turkey)
| Kurdish (Turkey) spell check dictionary
|-
| lt
| Lithuanian
| Lithuanian spelling and hyphenation dictionaries
|-
| ne
| Nepali
| Nepali spelling dictionary and thesaurus
|-
| no
| Norwegian
| Norwegian dictionaries (Nynorsk and Bokmål)
|-
| pl
| Polish
| Polish spell check dictionary, hyphenation rules and thesaurus
|-
| ro
| Romanian
| Romanian Dictionaries
|-
| ru
| Russian
| Russian hyphenation dictionary and thesaurus
|-
| sr
| Serbian
| Serbian spelling and hyphenation dictionaries
|-
| sk
| Slovak
| Slovak spell check dictionary, hyphenation rules and thesaurus
|-
| sl
| Slovenian
| Slovenian dictionary pack
|-
| es
| Spanish
| Spanish spelling dictionary
|-
| sw
| Swahili
| Swahili spelling dictionary
|-
| sv
| Swedish
| Swedish Dictionary
|-
| th
| Thai
| Thai spelling dictionary
|-
| vi
| Vietnamese
| Vietnamese spellchecker dictionary
|-
| zu
| Zulu
| Zulu hyphenation dictionary
|-
|}

[[Specification_Template_Help#Detailed_Specification|Help]] | [[UI-Elements|User Interface Element Templates]] | [[Specification_Example|Example Spec]]

== Accessibility ==
Accessibility not impacted.

== Migration ==
<START TYPING HERE --- If this part is irrelevant state a reason for its absence.>

== Configuration ==
<START TYPING HERE --- If this part is irrelevant state a reason for its absence.>

[[Specification_Template_Help#Configuration|Help]] | [[Configuration-Table|Configuration Table Template]]

== Open Issues ==
* Pre-bundled extensions still show up in the Extension Manager. This is considered a minor impact, as the user cannot change such extension in this place. Issue will be resolved in the future.

[[Category:Specification]]

Documentation/DevGuide/Extensions/Packaging Notes

2010-06-11T12:54:01Z

Jl: add link to scp description

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Processing Extensions
|NextPage=Documentation/DevGuide/Extensions/Deployment Items
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Packaging Notes For Bundled Extensions}}
'''(As of OOo 3.3)'''

Bundled extensions are installed during OOo's setup and only the setup can install or remove them. That is, they cannot be modified by the extension manager, which would change the installation. The installer copies the extensions into the extensions directory of the "share" folder. For example, <code>C:\Program Files\OpenOffice.org 3\share\extensions</code> on Windows XP. Contrary to versions previous to OOo 3.3, unopkg need '''NOT''' be run as a post install step. To uninstall the extensions, the installer can simply delete the directories of the respective extensions.

Extensions are packaged as directories instead of ".oxt" files. For example, there is an extension Foo.oxt containing the files f1 and f2. The installer package must then contain the "unzipped" extension, that is a directory Foo (oxt can be ommitted). After installation, the file structure must be:

<pre>
+ Office/share/extensions
+ Foo
|- f1
|- f2
</pre>

During the packaging process one must make sure that all bundled extensions have different directory names, so as to prevent overwriting other extensions. In case of a name clash, one needs to modify the directory name of the extension appropriately.

The name of the folder should still reflect the name of the original extension file. This makes it easier to locate the extension in the file system. This name will also be used by the extension manager dialog if the extension does not provide a display name. Further details can be found here: [[Extensions_Integration_into_Installation_Set | Extensions_Integration_into_Installation_Set]].

Bundled extension MUST have an identifier and version, otherwise OOo cannot determine reliably if a bundled extension was removed.

Executables contained in the extension must have the executable flag set. This is usually done by the extension manager, but not in case of bundled extensions.
{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Packaging Notes

2010-06-11T08:54:07Z

Jl: type

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Processing Extensions
|NextPage=Documentation/DevGuide/Extensions/Deployment Items
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Packaging Notes For Bundled Extensions}}
'''(As of OOo 3.3)'''

Bundled extensions are installed during OOo's setup and only the setup can install or remove them. That is, they cannot be modified by the extension manager, which would change the installation. The installer copies the extensions into the extensions directory of the "share" folder. For example, <code>C:\Program Files\OpenOffice.org 3\share\extensions</code> on Windows XP. Contrary to versions previous to OOo 3.3, unopkg need '''NOT''' be run as a post install step. To uninstall the extensions, the installer can simply delete the directories of the respective extensions.

Extensions are packaged as directories instead of ".oxt" files. For example, there is an extension Foo.oxt containing the files f1 and f2. The installer package must then contain the "unzipped" extension, that is a directory Foo (oxt can be ommitted). After installation, the file structure must be:

<pre>
+ Office/share/extensions
+ Foo
|- f1
|- f2
</pre>

During the packaging process one must make sure that all bundled extensions have different directory names, so as to prevent overwriting other extensions. In case of a name clash, one needs to modify the directory name of the extension appropriately.

The name of the folder should still reflect the name of the original extension file. This makes it easier to locate the extension in the file system. This name will also be used by the extension manager dialog if the extension does not provide a display name.

Bundled extension MUST have an identifier and version, otherwise OOo cannot determine reliably if a bundled extension was removed.

Executables contained in the extension must have the executable flag set. This is usually done by the extension manager, but not in case of bundled extensions.
{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Packaging Notes

2010-06-11T08:52:28Z

Jl: rewritten

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Processing Extensions
|NextPage=Documentation/DevGuide/Extensions/Deployment Items
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Packaging Notes For Bundled Extensions}}
'''(As of OOo 3.3)'''

Bundled extensions are installed during OOo's setup and only the setup can install or remove them. That is, they cannot be modified by the extension manager, which would change the installation. The installer copies the extension into the extensions directory of the "share" folder. For example, <code>C:\Program Files\OpenOffice.org 3\share\extensions</code> on Windows XP. Contrary to versions previous to OOo 3.3, unopkg need '''NOT''' be run as a post install step. To uninstall the extensions, the installer can simply delete the directories of the respective extensions.

Extensions are packaged as directories instead of ".oxt" files. For example, there is an extension Foo.oxt containing the files f1 and f2. The installer package must then contain the "unzipped" extension, that is a directory Foo (oxt can be ommitted). After installation, the file structure must be:

<pre>
+ Office/share/extensions
+ Foo
|- f1
|- f2
</pre>

During the packaging process one must make sure that all bundled extensions have different directory names, so as to prevent overwriting other extensions. In case of a name clash, one needs to modify the directory name of the extension appropriately.

The name of the folder should still reflect the name of the original extension file. This makes it easier to locate the extension in the file system. This name will also be used by the extension manager dialog if the extension does not provide a display name.

Bundled extension MUST have an identifier and version, otherwise OOo cannot determine reliably if a bundled extension was removed.

Executables contained in the extension must have the executable flag set. This is usually done by the extension manager, but not in case of bundled extensions.
{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Extension Layers

2010-06-09T11:47:44Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Location of Installed Extensions
|NextPage=Documentation/DevGuide/Extensions/Checklist for Writing Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Extension Manager Rework}}
__NOTOC__
The Extension Manager uses two extension layers, the user and the shared layer. Extensions installed in the shared layer can be used by all users whereas those in the user layer can only be used by the user who installed them. An extension can be installed in either layer or both.

This system was developed many years ago. Since then new features were added, such as extension versioning, online update, bundled extensions, etc. During that time it became obvious that there are some problems with the original design. This document tries to explain them.
==Current problems==

=== Hiding ===
The idea of layers is that extensions in the top layer '''hide''' the same extensions in the layer below. In other words, the extension in the highest layer will be given preference, when resources from the extension are requested. Because the user layer is the top layer, a shared extension is only used when the same extension does not exist in the user layer. The version of the extension has no influence.

This, however, is only a simplified model. An extension is never used as a whole. Instead clients access the particular contents, such as components, configuration data, etc. And it is also these contents which obscure the same content in a lower layer. For example, an extension contains a UNO service, which is installed in both layers. When the client instantiates it then the one from the top layer is used.

There are situations where contents of the shared extensions are still used, although they should be hidden and therefore not usable. Assuming there are version 1 and version 2 of an extension. Then the different versions may have different content. For example, version 1 may contain a service ''foo'' which is not contained in version 2. If now version 1 is installed in the shared layer and version 2 in the user layer then ''foo'' is still around and can be instantiated. Foo may access resources which are also delivered with this extension and are also available in version 2 which is in the user layer. Resources in version 2, which hide those from version 1 (same node in xcu or same service), can be incompatible, so that foo fails.

A service may also need files which are part of the same extension and which are only directly accessible. That is there is no API, such as the registry or service manager, which can provide the content. A "running" service does not know from which layer it comes from. To get the install location it can use the [[Documentation/DevGuide/Extensions/Location of Installed Extensions|PackageInformationProvider]]. This service will first look into user layer and if the extension cannot be found, then it will look into the shared layer. If now the service from the shared layer needs some file from its extension, then it may accidentally use the one from a different version of the extension in the user layer. This file can be incompatible or not even exist and make the service fail.

Another example can be constructed using registry values, which are contained in xcu files. Let's assume that version 1 of an extension adds a menu ''foo'' and version 2 adds menu ''bar''. If one extension is installed in the share and the other in the user layer, then both menus appear. This is because the nodes of the configuration files are merged into the configuration and not the xcu files itself. That is, if the extensions contain an xcu file with the same name, then the xcu file of the last installed extension will NOT replace the one from the other extension. The second xcu file can, however, change the values for nodes which have been defined by the first xcu.

These examples prove that the layering (in terms of hiding the items from the layer below) on extension level does not work, although it does for the respective [[Documentation/DevGuide/Extensions/Deployment Items|deployment items]]. And it may be safe to say, that this goes against the user's expectation.

===Unclear behavior===
It may be unclear to users how the behavior is when the same extension is installed as user and shared extension. If there is a shared extension and the same extension is installed as user extension, then the user should be informed that the currently installed extension will become 'inactive'. Then, when the user extension is uninstalled, the user should be informed that the shared extension will become 'active' again.

=== Extension versions ===

As already observed, the version of an extension has no influence on the decision if the extension from the user or the shared layer is used. At the time of developing the extension framework there was no support for versioned extensions, so one did not have to care about them. Later, we recognized that an extension version is useful for users. For example, if one has an extension installed and is installing the same extension again, then one is being informed about what extension has the later version (so one can decide which is the best for them).

I think the general expectation is that the latest version is the best. Therefore it should be natural that OOo uses always that one. However, this is not the case and users may unintentionally prevent, that they use the latest extension. For example, OOo comes with a bundled English dictionary. Now a user installs, intentionally or not, the same extension and forgets about it. The administrator updates OOo regularly, which also updates the dictionary with the latest version. But the user would still use the old dictionary, because that is the one from the user layer which hides the one from the shared layer.

One could think now of a notification for the user but there are some questions:
*when does OOo check for this situation?
*how can this be explained to the user?
The first question, is easily answered: At every start-up.

The second question is more difficult.Think about a message, such as: "Dear user. You cannot use the latest version of the french dictionary, which is installed in the shared/bundled layer. Instead the dictionary which you installed earlier is used. You need to uninstall it, if you want the new version ...."
Many users would probably not understand this. So the easiest and natural way is simply to use the latest version of the extension indepedent of what layer it is installed in. The term layer should then be replaced, by repository, indicating that the location does not include a preference – just think about the picture of one layer above the other compared to repositories which are arranged in one row.

=== Layer location ===

The shared layer is located within the OOo installation. The benefit is that normal users cannot modify it. The layer will be modified after installation of OOo when an extensions is added, deleted, enabled or disabled. Depending on the operation system, this may be against the system guidelines. For example, it would be not allowed on Windows Vista/ 7. However, to allow “legacy application” to work Microsoft invented the virtual store.

=== Clean uninstallation ===

Modification of the shared layer will also prevent the clean uninstallation of OOo. This is because the native installer does not “own” the files/folder which were added by the extension manager. For example, on Linux the path /opt/openoffice.org3/share/uno_packages will remain on the system. On OpenSolaris the shared extensions (with the same directory structure) will be copied to /var/lost+found on uninstallation.

=== Keeping the user's extensions ===
The rule is, whatever a user installed should not be removed by OOo. This is also valid for shared extensions. Today a bundled extension is nothing else than a shared extension and therefore can be modified by users, provided they have sufficient file access rights. They can install the same extension as one, which was installed as bundled extension, in the shared layer. This means that the original bundled extension is replaced by the recently installed shared extension. This can happen in two scenarios. The first one is during an online update of the extension and the second is when the extension is “manually” installed. In these cases users intentionally choose to replace the original extension. Therefore this extension may not be deleted when uninstalling OOo. This, however, requires to know that the bundled extension was replaced, but there is currently no way to recognize this.

===Selection of extensions in setup===
Like many other features, bundled extensions should be selectable in the dialog of the installer. The installer can also be invoked later to add or remove particular features. The problem is, that the extensions which the installer “sees” are not the same as “seen” by the extension manager. The setup copies an oxt file to ../share/extension/install and then invokes a post-install script (Unix) or a custom action (Windows) which runs unopkg to install the extension properly. The extension is then unzipped to ../share/uno_packages/cache/uno_packages and some data are added to the extension manager database. The installer only knows the file that it copied to the ../share/extension/install folder. If it is there then it is regarded as installed – otherwise not.

For an extension to show up in the dialog of the extension manager, there are two conditions which need to be met. First, it must be unpacked in the uno_packages folder. And second, there must be an appropriate entry in the extension manager database, indicating that it is installed. Therefore it would be possible that the installer displayed an extension as being installed but the extension manager did not. This may of course happen the other way round as well.

Even if the installer would copy the uncompressed extension directly to ../share/uno_packages/cache/uno_packages, both dialogs could show a different status. One could assume that the installer and extension manager regard an extension as installed if the the respective folder exists. But this does not work, because the extension manager does not remove immediately the extension when it is being uninstalled. The reason is, that files from the extension can still be in use in the process. Only after restarting OOo and the extension manager, the extension's folder will be finally removed.

===Code execution during installation===
Copying extensions into the office installation during setup is not sufficient to make them usable. Only after the extension manager has processed them, OOo can make use of them. Therefore the installer invokes the extension manager after an extension has been copied. Unfortunately this requires different solutions for different platforms. RPM (Linux) and PKG (Solaris) use post-install/pre-install scripts which are executed after the copying step. But there are installation scenarios on Solaris, where code execution is not allowed during the setup. For example, the installer is running on Solaris Sparc and installs OOo on a Solaris Intel Machine machine. Therefore OOo uses a “postrun” service which invokes the extension manager when the system is rebooted. OpenSolaris prohibits code execution completely. The setup needs to install an SMF service which is triggered after the setup. Windows needs a 'custom action' which is compiled native code. The Mac dmg file already contains the processed extensions. That is, the extension manager processes the extension while building the dmg file.

It is obvious that the current situation is complex and one understands why testing and bug finding are rather difficult.

===Extension Manager database===
The database is created when the extension manager is started for the first time. The database contains different files and folders which are completely unknown to the installer. Therefore the installer will not remove them. This is another reason why the OpenOffice.org folder remains on the system after uninstalling OOo.

===Keeping shared extensions===
Shared extensions installed by the user should should survive the uninstallation of OOo. So that future versions of OOo can use them. Depending on the platform, they are currently moved, deleted or left alone.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Scripting/Integration with Extension Manager

2010-06-09T06:15:37Z

Jl: /* Implementation of LanguageScriptProvider with support for Package Manager */

{{Documentation/DevGuide/ScriptingTOC
|Scripting2d=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/Implementation
|NextPage=Documentation/DevGuide/GUI/Graphical User Interfaces
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Scripting/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Integration with Extension Manager}}
__NOTOC__
The Extension Manager is a tool for deploying components, configuration data and macro libraries (see chapter [[Documentation/DevGuide/Extensions/Extensions|Extensions]]). It provides a convenient mechanism for macro developers to distribute their macros.

The scripting framework supports deployment of macros in extensions. Currently only extensions for the media type "<code>application/vnd.sun.star.framework-script</code>" are supported. Macros deployed in extensions of this media type must use the <code>ScriptingFramework</code> storage scheme and ''parcel-descriptor.xml'' to function correctly. An implementation of the <idl>com.sun.star.deployment.PackageRegistryBackend</idl> service is provided which supports deployment of macro libraries of media type "<code>application/vnd.sun.star.framework-script</code>" with the Extension Manager.

{{Documentation/Note|{{PRODUCTNAME}} Basic macros are handled via a separate media type "<tt>application/vnd.sun.star.basic-script</tt>" and hence handled by a different mechanism.}}

=== Overview of how ScriptingFramework integrates with the Extension Manager API ===

[[Image:PkgMgrInteraction.png|none|thumb|400px|Registration of macro library using Package Manager]]

==== Registration ====

Macro libraries contained in extensions are registered by the Extensions Manager. It informs the <code>LanguageScriptProvider</code> by calling its <code>insertByName()</code> method. The <code>LanguageScriptProvider</code> persists the registration of the macro library in order to be aware of registered libraries when {{PRODUCTNAME}} is restarted at a future time.

==== Deregistration ====

Deregistration of a macro library contained in an extension is similar to the registration process described above, the Extension Manager informs the <code>LanguageScriptProvider</code> that a macro library has been removed by calling its <code>removeByName()</code> method. The <code>LanguageScriptProvider</code> removes the macro library from its persisted store of registered macro libraries.

==== Implementation of LanguageScriptProvider with support for Package Manager ====

[[Image:LanguageProviderServicePkgNameCont.png|none|thumb|400px|LanguageScriptProvider]]

In order for the <code>LanguageScriptProvider</code> to handle macro libraries contained in UNO packages with media type "<code>application/vnd.sun.star.framework-script</code>" it's <code>initialize()</code> method must be able to accept a special location context that indicates to the <code>LanguageScriptProvider</code> that it is dealing with extensions.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Location context
|-
|"<code>user:uno_packages</code>"
|<code>String</code>. Denotes the user installation deployment context.
|-
|"<code>share:uno_packages</code>"
|<code>String</code>. Denotes the share installation deployment context.
|}

On initialization the <code>LanguageScriptProvider</code> needs to determine what macro libraries are already deployed by examining its persistent store.

{{Documentation/Note|<tt>LanguageScriptProviders</tt> created by implementing the abstract Java helper <tt>class com.sun.star.script.framework.provider.ScriptProvider</tt> do not need to concern themselves with storing details of registered macro libraries in extensions. This support is provided automatically. An XML file called ''unopkg-desc.xml'' contains the details of deployed UNO script packages . This file located in either ''<OfficePath>/user/Scripts'' or ''<OfficePath>/share/Scripts'' depending on the installation deployment context.
'''As of OOo 3.3''' the file is called shared-extension-desc.xml, for shared extetensions, and user-extension-desc.xml for user extensions. Both are in <UserInstallation>/user/Scripts.

The DTD for ''unopkg-desc.xml'' follows
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>


<!ELEMENT package EMPTY>
<!ELEMENT language (package+)>
<!ELEMENT unopackages (language+)>
<!ATTLIST language
value CDATA #REQUIRED
>
<!ATTLIST package
value CDATA #REQUIRED
>
</source>

An example of a sample an ''uno-desc.xml'' file is shown below.

<source lang="xml">
<unopackages xmlns:unopackages="unopackages.dtd">
<language value="BeanShell">
<package value="vnd.sun.star.pkg://vnd.sun.star.expand:
$UNO_USER_PACKAGES_CACHE%2Funo_packages%2Flatest.uno.pkg/WordCount" />
</language>
<language value="JavaScript">
<package value="vnd.sun.star.pkg://vnd.sun.star.expand:
$UNO_USER_PACKAGES_CACHE%2Funo_packages%2Flatest.uno.pkg/ExportSheetsToHTML" />
<package value="vnd.sun.star.pkg://vnd.sun.star.expand:
$UNO_USER_PACKAGES_CACHE%2Funo_packages%2Flatest.uno.pkg/JSUtils" />
</language>
</unopackages>
</source>
}}

A <code>LanguageScriptProvider</code> that does not use the Java abstract helper class <code>com.sun.star.script.framework.provider.ScriptProvider</code> will need to persist the extensions deployed for the supported language themselves.

The <code>LanguageScriptProvider</code> additionally needs to support the <idl>com.sun.star.container.XNameContainer</idl> interface which supports the following methods.
<source lang="idl">
void insertByName( [in] string aName,
[in] any aElement )
void removeByName( [in] string Name )
</source>
On registration of an extension containing scripts the <code>LanguageScriptProvider</code>'s <code>insertByName()</code> method is called with <code>aName</code> containing the URI to a macro library contained in the extension and <code>aElement</code> contains an object implementing <idl>com.sun.star.deployment.XPackage</idl> Note that the URI contains the full path to the macro library contained in the extension. For example, if the library is named my macros then the path includes the ''mymacros'' directory.

On deregistration of an extension containing scripts the <code>LanguageScriptProvider</code>'s <code>removeByName()</code> method is called with <code>aName</code> containing the URL to a macro library to be de-registered.

<idl>com.sun.star.container.XNameContainer</idl> interface itself inherits from <idl>com.sun.star.container.XNameAccess</idl> which supports the following method
<source lang="idl">
boolean hasByName( [in] string aName )
</source>
To determine whether the macro library in an extension is already registered the <code>LanguageScriptProvider</code>'s <code>hasByName()</code> is called with <code>aName</code> containing the URL to the script library. The other methods of the interfaces inherited by <idl>com.sun.star.container.XNameContainer</idl> are omitted for brevity and because they are not used in the interaction between the Extension Manager and the <code>LanguageScriptProvider</code>. A Developer however still must implement these methods.

==== Implementation of the BrowseNode service ====

The <code>LanguageScriptProvider</code> created for an installation deployment context needs to expose the macro and macro libraries that it is managing. How this is achieved is up to the developer. A <code>LanguageScriptProviders</code> created by extending the Java abstract helper class <code>com.sun.star.script.framework.provider.ScriptProvider</code> creates nodes for each extension that contain macro libraries for the supported language . Each extension node contains the macro library nodes for the supported language and those nodes in turn contain macro nodes.

An alternative implementation could merge the macro libraries into the existing tree for macro libraries and not distinguish whether the macros are located in an extension or not. This is loosely the approach taken for {{PRODUCTNAME}} Basic.

Example of creating a extension containing a macro library suitable for deploying with Extension Manager.The following example shows how to create an UNO package from the Beanshell macro library Capitalize. This macro library is located in the ''<OfficeDir>/share/beanshell/Capitalize'' directory of a {{PRODUCTNAME}} installation . The extension created will be deployable using the Extension Manager .

First create a scratch directory for example called ''temp''. Copy the macro library directory and its contents into ''temp''. In ''temp'' create a sub-directory called ''META-INF'' and within this directory create a file called ''manifest.xml''.

<Dir> Temp
|
|-<Dir> Capitalise
| |
| |--parcel-desc.xml
| |--capitalise.bsh
|
|-<Dir> META-INF
|
|--manifest.xml

The contents of the ''manifest.xml'' file for the Capitalize macro library are as follows
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.sun.star.framework-script" manifest:full-path="Capitalise/"/>

</manifest:manifest>
</source>
Next create a zip file containing the contents (but not including ) the ''temp'' directory. The name of the file should have the extension "''.oxt''" e.g. ''Capitalise.oxt''.

Deploying a macro library contained in an extension.To deploy the extension you need to use the Extension Manager (see chapter [[Documentation/DevGuide/Extensions/Extensions|Extensions]]). Once the extension has been deployed successfully the macro will be available for assignment or execution.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Scripting]]

Documentation/DevGuide/Extensions/Extension Versions

2010-06-09T05:37:33Z

Jl: changes for OOo 3.3

{{Documentation/DevGuide/ExtensionsTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Identifiers
|NextPage=Documentation/DevGuide/Extensions/Target Platform
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Extension Versions}}
Extensions are often improved over time. That is, publishers want to ship new versions of the same extension with added functionality and/or bug fixes. Adding extension versions allows publishers to ship new versions, and allows {{PRODUCTNAME}} to detect and handle the case that an extension installed by the user is an update of an existing extension.

Technically, an extension version v is defined as an infinite sequence of non-negative integers v = ‹v<sub>0</sub>, v<sub>1</sub>, ...› where all but a finite number of elements have the value zero. A total order is defined on versions via lexicographical comparison. A textual representation of a version v = ‹v<sub>0</sub>, v<sub>1</sub>, ...› is a finite string built from the BNF

version ::= [element (“.” element)*]
element ::= (“0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9”)+

of n ≥ 0 elements where each element is a decimal representation of v<sub>i</sub> for 0 ≤ i < n, and each v<sub>i</sub> = 0 for i ≥ n.

The extension version is obtained from the description.xml contained in the extension. If the extension does not specify such an explicit version, then an implict textual version representation of the empty string (representing a version of all zeroes) is assumed.

No general semantics are prescribed to versions, other than the total order which determines whether one version is less than, equal to, or greater than another version, respectively. However, extension publishers are encouraged to use the widely accepted three-level scheme of major (incompatible changes), minor (compatible changes), micro (bug fixes) where applicable.

'''As of OOo 3.3''' providing a version is necessary for bundled and shared extensions (see [[Documentation/DevGuide/Extensions/Processing_Extensions#Removing_a_shared_extension|Processing Extensions]]).

'''See also'''
*[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/version|XML description for description.xml]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Extension Identifiers

2010-06-09T05:33:29Z

Jl: need of identifier for OOo 3.3

{{Documentation/DevGuide/ExtensionsTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Description
|NextPage=Documentation/DevGuide/Extensions/Extension Versions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Extension Identifiers}}
Extensions now have unique identifiers. This removes the previous restriction that no two extensions with identical file names can be deployed. That is, two extensions with same file name but different identifiers can be installed but two extensions with the same identifiers cannot be installed at the same time.

The identifier plays also an important role for the [[Documentation/DevGuide/Extensions/Online_Update_of_Extensions|on-line update]]. When running the on-line update, then the Extension Manager downloads a list of available extensions from the extension repository or from the location determined by the installed extension. The Extension Manager then tries to find an extension with a newer version in this list by comparing the identifier of the installed extensions with the identifier contained in the [[Documentation/DevGuide/Extensions/Description_of_the_Update_Information|update information]]. Therefore the identifier '''MUST''' be unique. This is also the case when two extensions are logically the same but support different platforms. In this case one can achieve this uniqueness by adding a platform string to identifier. The [[Documentation/DevGuide/Extensions/Target Platform#Generating the Platform String in the Build Environment|'Target Platform']] section describes how this string can be generated in the build environment.

Technically, an extension identifier is a finite sequence of Unicode scalar values. Identifier identity is element-by-element identity of the sequences (no case folding, no normalization, etc.). It is assumed that extension writers cooperate to keep extension identifiers unique. By convention, use lowercase reversed-domain-name syntax (e.g., ''org.openoffice.'') prefixes to generate unique (but still humanly comprehensible) identifiers. When you write an extension, use the reversed domain name of a site you control (and not ''org.openoffice.'') as prefix. Identifiers starting with the prefix ''org.openoffice.legacy.'' are reserved for legacy extensions (see next). The same procedure used to avoid name clashes for extension identifier applies to all unique names in configuration files of extensions (configuration nodes in extendable lists etc.).

The extension identifier is obtained from the ''description.xml'' contained in the extension. If the extension does not specify such an explicit identifier, then an implicit identifier is generated by prepending ''org.openoffice.legacy.'' to the (obvious sequence of Unicode scalar values representing the) file name of the extension. (Uniqueness of identifiers is then guaranteed by the assumption underlying legacy extension management that no two legacy extensions have the same file name.)

'''As of OOo 3.3''' providing an identifier is necessary for bundled and shared extensions (see [[Documentation/DevGuide/Extensions/Processing_Extensions#Removing_a_shared_extension|Processing Extensions]]).

'''See also'''
*[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/identifier|XML description for description.xml]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Simple License

2010-06-08T10:41:00Z

Jl: notes for OOo 3.3

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2c=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Target Platform
|NextPage=Documentation/DevGuide/Extensions/Dependencies
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Simple License}}
This feature is about displaying a license text to the user during installation. This is not supported for '''bundled extensions'''. Distributors of OOo need to clarify license details with the publishers of extensions, which they want to bundle with OOo.

The user can agree or decline the license, where in the latter case the installation will be aborted. It is called “Simple License” because there is no tamper resistant mechanism that prevents the installation in case the user does not agree to the license. It also does not do anything more than just displaying a license text. The text can be localized (see [[Documentation/DevGuide/Extensions/Localized XML Elements]]).

The license text is displayed either in a dialog or in the console dependent on the way the Extension Manager was started. When it was started by the '''Tools - Extension Manager''' menu item or by invoking <code>unopkg gui</code> in the console then a dialog is used. By using ''unopkg'' add the license text will be displayed in the console and user input has to be done through the same.

The license dialog or the license text in the console is displayed when the extension is being installed. Currently there are two modes to install extensions, user mode and shared mode. An extension that was installed in user mode (let's call it a ''user extension'') can only be used by just that person who installed it. If the extension was installed in shared mode (let's call it a ''shared extension''), then it can be used by all users. Since the license text is only displayed during installation, all users who are using a ''shared extension'' will not see any license text (except the user who installed this ''shared extension''). However, the publisher of the extension may think it necessary that everyone who wants to use it has to agree to the license first. For this purpose, he can mark the extension accordingly. This extension can then only be installed in user mode and not in shared mode. Likewise the extension can be marked indicating that only the person who installs it needs to agree to the license. Such an extension can be installed in both modes. But when installing in user mode then every user has to agree to the license nonetheless.

'''As of OOo 3.3''' shared extension can also require that every user accepts the license. This happens the first time a user starts OOo after the shared extension was installed. If the user declines the license, then the extension is not usable for this user. It will, however, be displayed in the dialog, where the user can accept the license later. Similarly a user can accept the license by running <code>unopkg validate</code>. For example

<code>unopkg validate --shared org.openoffice.legacy.ShortLicense.oxt</code>

Here is an example of the description.xml:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<description xmlns="http://openoffice.org/extensions/description/2006"
xmlns:xlink="http://www.w3.org/1999/xlink">
<registration>
<simple-license accept-by="user" >
<license-text xlink:href="registration/license_de.txt" lang="de" />
<license-text xlink:href="registration/license_en_US.txt" lang="en-US" />
</simple-license>
</registration>
</description>
</source>

In this example, the license would have to be agreed to by all users (that means no shared mode installation). This is indicated by the value <code>user</code> of the attribute accept-by in the <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code> element. The attribute could also have the value <code>admin</code>, which would indicate that the license needs only be agreed to by the person who installs it.

The <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> elements contain information about the files which contain the text that is displayed. The content of these files must be UTF-8 encoded. It is displayed exactly as it is in the file. That is, no formatting occurs. There can be one to many <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> elements, where each element provides information about a different language of the license text. The attribute <code>xlink:href</code> contains a relative URL (relative to the root directory of the extension) which points to a file which contains the license text in exactly one language. Which language is indicated by <code>lang</code> attribute.

If the package manager does not find a <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> element which matches the locale of {{PRODUCTNAME}} then it will pick the first <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> element as the default. Prior to OOo 2.4. the default entry needed to marked explicitely by <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|license-id]]</code> attribute.

==Important Issues==

*'''(Obsolete as of OOo 3.3)'''Using the simple license in extensions always requires user interaction. Using <code>accept-by="user"</code> in the <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> prevents this extension from being installed centrally, that is as shared extensions. Both issues can prevent the extension from being used by companies, which centrally maintain software.
*'''(Obsolete as of OOo 3.3, feature is not supported but installation will not hang when using extensions with a license)''' The 'simple license' does not work for bundled extensions (installation will probably hang as user input is required). If one wants to build an OOo installation set with bundled extensions, then they must not use this feature.

To get around these limitations, extensions need to provide the attribute [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|suppress-if-required="true"]].

'''See also'''
*[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|XML description for description.xml]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Packaging Notes

2010-06-08T09:27:55Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Processing Extensions
|NextPage=Documentation/DevGuide/Extensions/Deployment Items
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Packaging Notes For Bundled Extensions}}
'''(As of OOo 3.3)'''

Bundled extensions are installed during OOo's setup and only the setup can install or remove them. They are copied in an uncompressed way into the extension folder of the repository. For example, an extension Foo contains two files f1, f2. Then the native package contains a folder Foo and therein the files f1 and f2.
It must be guaranteed that the paths to the installed extensions are unique in order to prevent overwriting a previously installed extension. Fore example, extension1.rpm contains Foo and extension2.rpm also contains Foo, which is a different extension. Both packages would be installed in
<bundled_repository_extension_folder>/Foo
when blindly using the extension name.

Therefore, when packaging the rpm, one must provide a unique path. Because, bundling an extension is no automated process, we can leave it to the person who bundles the extension to ensure the uniqueness. In case of a name clash, one needs to modify the folder name of the extension appropriately.

The name of the folder should reflect the name of the original extension file. This makes it easier to locate the extension in the file system. This name will also be displayed in different dialogs if the extension does not provide a display name.

A bundled extension is uninstalled by simply removing the folder containing the extension files. That is, installation and removal only involve simple file operations as done by the installer. No code execution is required.

Bundled extension MUST have an identifier and version, otherwise OOo cannot determine reliably if a bundled extension was removed.

Executables contained in the extension must have the executable flag set. This is usually done by the extension manager, but not in case of bundled extensions.
{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Deployment Items

2010-06-08T09:22:25Z

Jl: fixed PrevPage

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Packaging Notes
|NextPage=Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Deployment Items}}
The Extension Manager can be used to deploy various types of files. It is primarily used for extensions. The latest incarnation of an extensions is the ''.oxt'' file, which has superseded ''.uno.pkg'' and ''.zip''.

Apart from extensions the Extension Manager can also manage these types:

* Configuration data (''.xcu'', ''.xcs'')
* UNO Libraries (''.dll'' / ''.so'')
* JARs (''.jar'')
* Type libraries (''.rdb'')

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Updating Extensions

2010-06-08T09:20:31Z

Jl: fixed title and nextPage link

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/The Active Extension
|NextPage=Documentation/DevGuide/Extensions/Processing Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Updating Extensions}}
'''(As of OOo 3.3)'''

An extension can be updated by either explicitly installing the extension or by running the update function in the extension manager.
Updating an extension consisted originally in removing the installed extension and then installing the new version of the extension in the same repository. This meant that it was necessary to have write permission for the extensions folder of the shared repository for updating shared extensions. However, bundled extension could still not be updated by the extension manager, because this is exclusively done by the setup program.

However, in order to hide the complexity of the different repositories from the user and give them the best user experience, the extension manager will install updates for shared or bundled extensions in the user repository if necessary. That is, the installed extension will remain unchanged and the newer version is installed in a repository with a higher priority.

Users will be informed if there are newer versions of extensions which they currently use are available. It does not matter if the currently used extensions are from the user, shared or bundled repository. If there is a better version, then it is offered as an update. This allows users, to always obtain the latest versions of their extensions.

The updates, that is, the extensions with a newer version, will either be obtained from an online repository or locally, depending on which one have the highest versions. In the latter case, the newer version will come from the shared or bundled repository if there is one available. This is useful for the case when a user has installed an user extension and then a more current version is installed in the shared or bundled repository.

The following tables show scenarios where the user can update extensions. If a cell contains a “1” then this simple means there is an extensions installed. If it contains a “2” then this represents an extension with the same identifier then “1” but with a higher version. If there are several “2”s under each other then it is sufficient if just one of them has a higher version than “1”.

The first table shows the case where a user has '''no write permission''' in the shared folder. In all cases the update is installed in the '''user repository'''. The new version comes either from the shared, bundled or online repository, depending on which has the best version.

{| border="1" cellpadding="2"
!
! Case a
! Case b
! Case c
|-
|style="background:#EFDECD" |User repository || align="center" | - || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || align="center" | - ||align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"|2
|}

In words:
An update (installing in the user repository) is possible, if
#there is a bundled extension (no user and no shared) and the online repository contains a higher version
#there is shared extension (no user) and the bundled or online repository contains a higher version
#there is a user extension and the shared, bundled or online repository contains a higher version

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''shared repository'''. If a user extension exists does not matter.
{| border="1" cellpadding="2"
!
! Case a
! Case b
|-
|style="background:#EFDECD" |Shared repository || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in shared repository) is possible, if
#there is a bundled extension (and no shared) and the online repository contains a higher version
#there is shared extension and the bundled or online repository contains a higher version

This also means that, if there is only a user extension (no shared, no bundled) and there is one with a higher version in the online repository, then no update is done in the shared repository.

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''user repository'''.

{| border="1" cellpadding="2"
!
! Case a
|-
|style="background:#EFDECD" |User repository || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Bundled repository || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in user repository) is possible, if there is a user extension and the shared, bundled, or online repository contains a higher version.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Processing Extensions

2010-06-08T09:18:45Z

Jl: fixed title and nextPage link

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Updating Extensions
|NextPage=Documentation/DevGuide/Extensions/Packaging Notes
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Processing Extensions}}
'''(As of OOo 3.3)'''
==Checking for modification during start-up==
Every time OOo is started it needs to check if extensions were removed from or added to the shared or bundled repository. If this is the case, then the registration data of the repository must be updated accordingly and OOo is restarted.

The restart is particularly necessary when extensions are removed to avoid that parts of the extension are still accessible. For example, menu entries of an removed extension will only disappear after a restart. Similarly a service from an extension may already be running before the registration data is updated. Then the service will be available as long as OOo runs although the extension is removed. The reason for this is, that a shared extension is not immediately deleted from the hard disk when it is removed.

Because OOo checks for added or removed extensions at start-up, this must be very quick. To achieve this, OOo compares the modification time of extension folders of the repositories with the time of the most recently performed check. This time is “saved” in the file lastsynchronized in the registration data folder of the repositories. In fact, the modification time of the file is used rather then a value is written into the file. If the modification time of the extension folder is more recent, then the extension manager will check if extensions were added or removed and update its database accordingly. This is of course an implementation detail and may change at any time.

==Adding==
===Adding a user extension===
A user extension is extracted into a folder with a unique name which in turn is contained in the extensions folder. The additional folder with the unique name is necessary to make live deployment possible. When removing an extension, it is only marked as “unusable” and the extension is not deleted, because it may still be in use. If now the same extension is installed again in the same process, then it will be extracted to another folder with a unique name. This prevents a name clash with the folder name of the previously “removed” extension. The user can now repeat to remove and install the extension in the same process. This results in having the same extension multiple times in the extensions folder of the repository, but everyone is contained in a folder with a unique name. The folders of the “removed” extensions, as well as the folders which contain them, are only removed after running the extension manager after restarting OOo.

The extension database of repository is updated and the new active extension is determined.

===Adding a shared extension===
For the user who adds a shared extension, the extension is processed the same way as a user extension.

For all other users, the extension manager processes the extension the next time they start OOo.
The extension database of repository is updated and the new active extension is determined.

===Adding a bundled extension===
A bundled extension is installed by the installation program of OOo. The folder of the extension, including all files contained therein, is copied into the extensions folder of the bundled repository.
Only when a user starts OOo, then the extension manager processes the extension. The extension database of repository is updated and the new active extension is determined.

==Removing==
===Removing a user extension===
The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined. The extension will be deleted when the user runs the extension manager after restarting OOo.

===Removing a shared extension===
The extension will be revoked if it was registered. To prevent other users from using the extension it is marked to be deleted. This is done by creating a tag file, the "extension removed file", next to the folder with the unique name. This way, the information that the extension was deleted can be accessed by all users. If this file does not exist and there is no entry in the extensions database, then it is assumed that the extension was added. The file will be deleted when the extension is deleted. The file also contains the name of the user who removed the extension. If the same user runs the extension manager after restarting OOo, then the extension, the unique folder, temp file and the "extensions removed file are deleted. Why it must be the same user shows the following scenario:

A user starts OOo and uses the extension. The extension will then be removed and OOo keeps running. Now a second user, who also has write access to the extensions folder, starts OOo. When the extension manager starts it would properly delete extensions which were previously removed. However in this case this would affect the office of the first user which still uses that extension.
The same user cannot start another instance, because this is prevented by the lock file.

For all other users, the extension manager processes the extension the next time they start OOo. This includes the detection of the removed extensions. An extension is regarded as removed if:
*The unique folder, tmp file, extension folder do not exist anymore.
*There is a "extension removed file"
*The extension exists but has a different identifier or version than the one which was previously at the same location. This may happen when the extension was updated, or a previous office update removed the extension and another with the same name was added in the latest office update.

The extension could also have the same file name.
The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined.

===Removing a bundled extension===
A bundled extension can only be removed by the set-up. The folder of the extension, including all files contained in it, is deleted from the extension folder of the bundled repository.

If a user starts OOo, then the extension manager processes the removed extension. This includes the detection of the removed extensions.
An extension is regarded as removed if:
*The extension folder do not exist anymore.
*The extension exists but has a different identifier or version than the one which was previously at the same location.

The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined.

==Updating==
An update consists of first removing the extension and then adding the new extension. That is, this is already covered by these two scenarios.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Packaging Notes

2010-06-08T09:17:32Z

Jl:

Documentation/DevGuide/Extensions/Packaging Notes

2010-06-08T09:16:18Z

Jl: Initial page

Template:Documentation/DevGuide/ExtensionsTOC

2010-06-08T09:14:16Z

Jl: adding Packaging Notes

{{Documentation/MasterTOC
|ShowPrevPage={{{ShowPrevPage}}}
|PrevPage={{{PrevPage}}}
|ShowNextPage={{{ShowNextPage}}}
|NextPage={{{NextPage}}}
|bookid=DevGuide
|booktitle=[[Documentation/DevGuide/OpenOffice.org Developers Guide|OpenOffice.org Developer's Guide]]
|ShowParttitle=block
|parttitle=[[Documentation/DevGuide/Extensions/Extensions|Extensions]]
|ShowPrevPart=block
|PrevPart=Documentation/DevGuide/WritingUNO/Writing UNO Components
|ShowNextPart=block
|NextPart=Documentation/DevGuide/AdvUNO/Advanced UNO
|toccontent=
* [[Documentation/DevGuide/Extensions/Extension Manager|Extension Manager]]
<div id=Extensions2a" style="display:{{{Extensions2a|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Extension Repositories | Extension Repositories]]
* [[Documentation/DevGuide/Extensions/The Active Extension | The Active Extension]]
* [[Documentation/DevGuide/Extensions/Updating Extensions | Updating Extensions]]
* [[Documentation/DevGuide/Extensions/Processing Extensions | Processing Extensions]]
* [[Documentation/DevGuide/Extensions/Packaging Notes | Packaging Notes For Bundled Extensions]]
* [[Documentation/DevGuide/Extensions/Deployment Items|Deployment Items]]
* [[Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User|Installing Extensions for All or a Single User]]
* [[Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org|Extension Manager in OpenOffice.org]]
* [[Documentation/DevGuide/Extensions/unopkg|unopkg]]
* [[Documentation/DevGuide/Extensions/Location of Installed Extensions|Location of Installed Extensions]]
* [[Documentation/DevGuide/Extensions/Extension Layers|Extension Layers]]
</div>
* [[Documentation/DevGuide/Extensions/Checklist for Writing Extensions|Checklist for Writing Extensions]]
* [[Documentation/DevGuide/Extensions/File Format|File Format]]
* [[Documentation/DevGuide/Extensions/description.xml|description.xml]]
<div id=Extensions2b" style="display:{{{Extensions2b|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Description of XML Elements|Description of XML Elements]]
* [[Documentation/DevGuide/Extensions/Localized XML Elements|Localized XML Elements]]
* [[Documentation/DevGuide/Extensions/Example|Example]]
</div>
* [[Documentation/DevGuide/Extensions/Display Name|Display Name]]
* [[Documentation/DevGuide/Extensions/Icon|Icon]]
* [[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
* [[Documentation/DevGuide/Extensions/Extension Identifiers|Extension Identifiers]]
* [[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
* [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
* [[Documentation/DevGuide/Extensions/Simple License|Simple License]]
* [[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
* [[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
* [[Documentation/DevGuide/Extensions/System Integration|System Integration]]
* [[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
<div id=Extensions2d" style="display:{{{Extensions2d|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Running Online - Update|Running Online - Update]]
* [[Documentation/DevGuide/Extensions/Concept|Concept]]
* [[Documentation/DevGuide/Extensions/Example Scenario for Providing Updates|Example Scenario for Providing Updates]]
* [[Documentation/DevGuide/Extensions/Migration of Update Information|Migration of Update Information]]
* [[Documentation/DevGuide/Extensions/Description of the Update Information|Description of the Update Information]]
* [[Documentation/DevGuide/Extensions/Description of Atom Feed|Description of Atom Feed]]
* [[Documentation/DevGuide/Extensions/Examples|Examples]]
</div>
* [[Documentation/DevGuide/Extensions/Options Dialog|Options Dialog]]
* [[Documentation/DevGuide/Extensions/Creating the GUI of the Options Page|Creating the GUI of the Options Page]]
* [[Documentation/DevGuide/Extensions/Saving and Reading Data for the Options Page|Saving and Reading Data for the Options Page]]
* [[Documentation/DevGuide/Extensions/Defining the Usage of Options Pages|Defining the Usage of Options Pages]]
<div id=Extensions2e" style="display:{{{Extensions2e|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/The Options Dialog of the Extension Manager|The Options Dialog of the Extension Manager]]
* [[Documentation/DevGuide/Extensions/Adding a Leaf to an Existing Node|Adding a Leaf to an Existing Node]]
* [[Documentation/DevGuide/Extensions/Adding Several Leaves|Adding Several Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Leaves|Grouping of Leaves]]
* [[Documentation/DevGuide/Extensions/Adding Nodes|Adding Nodes]]
* [[Documentation/DevGuide/Extensions/Adding Several Nodes|Adding Several Nodes]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Leaves|Absolute Position of Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Nodes|Grouping of Nodes]]
* [[Documentation/DevGuide/Extensions/Assigning Nodes to Modules|Assigning Nodes to Modules]]
* [[Documentation/DevGuide/Extensions/Defining a Module|Defining a Module]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Nodes|Absolute Position of Nodes]]
</div>
* [[Documentation/DevGuide/Extensions/Help Content|Help Content]]
}}

Documentation/DevGuide/Extensions/Processing Extensions

2010-06-08T08:07:43Z

Jl: Initial page

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Updating Extensions
|NextPage=Documentation/DevGuide/Extensions/Processing Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:The Active Extension}}
'''(As of OOo 3.3)'''
==Checking for modification during start-up==
Every time OOo is started it needs to check if extensions were removed from or added to the shared or bundled repository. If this is the case, then the registration data of the repository must be updated accordingly and OOo is restarted.

The restart is particularly necessary when extensions are removed to avoid that parts of the extension are still accessible. For example, menu entries of an removed extension will only disappear after a restart. Similarly a service from an extension may already be running before the registration data is updated. Then the service will be available as long as OOo runs although the extension is removed. The reason for this is, that a shared extension is not immediately deleted from the hard disk when it is removed.

Because OOo checks for added or removed extensions at start-up, this must be very quick. To achieve this, OOo compares the modification time of extension folders of the repositories with the time of the most recently performed check. This time is “saved” in the file lastsynchronized in the registration data folder of the repositories. In fact, the modification time of the file is used rather then a value is written into the file. If the modification time of the extension folder is more recent, then the extension manager will check if extensions were added or removed and update its database accordingly. This is of course an implementation detail and may change at any time.

==Adding==
===Adding a user extension===
A user extension is extracted into a folder with a unique name which in turn is contained in the extensions folder. The additional folder with the unique name is necessary to make live deployment possible. When removing an extension, it is only marked as “unusable” and the extension is not deleted, because it may still be in use. If now the same extension is installed again in the same process, then it will be extracted to another folder with a unique name. This prevents a name clash with the folder name of the previously “removed” extension. The user can now repeat to remove and install the extension in the same process. This results in having the same extension multiple times in the extensions folder of the repository, but everyone is contained in a folder with a unique name. The folders of the “removed” extensions, as well as the folders which contain them, are only removed after running the extension manager after restarting OOo.

The extension database of repository is updated and the new active extension is determined.

===Adding a shared extension===
For the user who adds a shared extension, the extension is processed the same way as a user extension.

For all other users, the extension manager processes the extension the next time they start OOo.
The extension database of repository is updated and the new active extension is determined.

===Adding a bundled extension===
A bundled extension is installed by the installation program of OOo. The folder of the extension, including all files contained therein, is copied into the extensions folder of the bundled repository.
Only when a user starts OOo, then the extension manager processes the extension. The extension database of repository is updated and the new active extension is determined.

==Removing==
===Removing a user extension===
The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined. The extension will be deleted when the user runs the extension manager after restarting OOo.

===Removing a shared extension===
The extension will be revoked if it was registered. To prevent other users from using the extension it is marked to be deleted. This is done by creating a tag file, the "extension removed file", next to the folder with the unique name. This way, the information that the extension was deleted can be accessed by all users. If this file does not exist and there is no entry in the extensions database, then it is assumed that the extension was added. The file will be deleted when the extension is deleted. The file also contains the name of the user who removed the extension. If the same user runs the extension manager after restarting OOo, then the extension, the unique folder, temp file and the "extensions removed file are deleted. Why it must be the same user shows the following scenario:

A user starts OOo and uses the extension. The extension will then be removed and OOo keeps running. Now a second user, who also has write access to the extensions folder, starts OOo. When the extension manager starts it would properly delete extensions which were previously removed. However in this case this would affect the office of the first user which still uses that extension.
The same user cannot start another instance, because this is prevented by the lock file.

For all other users, the extension manager processes the extension the next time they start OOo. This includes the detection of the removed extensions. An extension is regarded as removed if:
*The unique folder, tmp file, extension folder do not exist anymore.
*There is a "extension removed file"
*The extension exists but has a different identifier or version than the one which was previously at the same location. This may happen when the extension was updated, or a previous office update removed the extension and another with the same name was added in the latest office update.

The extension could also have the same file name.
The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined.

===Removing a bundled extension===
A bundled extension can only be removed by the set-up. The folder of the extension, including all files contained in it, is deleted from the extension folder of the bundled repository.

If a user starts OOo, then the extension manager processes the removed extension. This includes the detection of the removed extensions.
An extension is regarded as removed if:
*The extension folder do not exist anymore.
*The extension exists but has a different identifier or version than the one which was previously at the same location.

The entry in the extension database of the repository referring to this extension will be deleted and the active extension will be determined.

==Updating==
An update consists of first removing the extension and then adding the new extension. That is, this is already covered by these two scenarios.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Template:Documentation/DevGuide/ExtensionsTOC

2010-06-08T07:35:15Z

Jl: adding Processing Extensions

{{Documentation/MasterTOC
|ShowPrevPage={{{ShowPrevPage}}}
|PrevPage={{{PrevPage}}}
|ShowNextPage={{{ShowNextPage}}}
|NextPage={{{NextPage}}}
|bookid=DevGuide
|booktitle=[[Documentation/DevGuide/OpenOffice.org Developers Guide|OpenOffice.org Developer's Guide]]
|ShowParttitle=block
|parttitle=[[Documentation/DevGuide/Extensions/Extensions|Extensions]]
|ShowPrevPart=block
|PrevPart=Documentation/DevGuide/WritingUNO/Writing UNO Components
|ShowNextPart=block
|NextPart=Documentation/DevGuide/AdvUNO/Advanced UNO
|toccontent=
* [[Documentation/DevGuide/Extensions/Extension Manager|Extension Manager]]
<div id=Extensions2a" style="display:{{{Extensions2a|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Extension Repositories | Extension Repositories]]
* [[Documentation/DevGuide/Extensions/The Active Extension | The Active Extension]]
* [[Documentation/DevGuide/Extensions/Updating Extensions | Updating Extensions]]
* [[Documentation/DevGuide/Extensions/Processing Extensions | Processing Extensions]]
* [[Documentation/DevGuide/Extensions/Deployment Items|Deployment Items]]
* [[Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User|Installing Extensions for All or a Single User]]
* [[Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org|Extension Manager in OpenOffice.org]]
* [[Documentation/DevGuide/Extensions/unopkg|unopkg]]
* [[Documentation/DevGuide/Extensions/Location of Installed Extensions|Location of Installed Extensions]]
* [[Documentation/DevGuide/Extensions/Extension Layers|Extension Layers]]
</div>
* [[Documentation/DevGuide/Extensions/Checklist for Writing Extensions|Checklist for Writing Extensions]]
* [[Documentation/DevGuide/Extensions/File Format|File Format]]
* [[Documentation/DevGuide/Extensions/description.xml|description.xml]]
<div id=Extensions2b" style="display:{{{Extensions2b|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Description of XML Elements|Description of XML Elements]]
* [[Documentation/DevGuide/Extensions/Localized XML Elements|Localized XML Elements]]
* [[Documentation/DevGuide/Extensions/Example|Example]]
</div>
* [[Documentation/DevGuide/Extensions/Display Name|Display Name]]
* [[Documentation/DevGuide/Extensions/Icon|Icon]]
* [[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
* [[Documentation/DevGuide/Extensions/Extension Identifiers|Extension Identifiers]]
* [[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
* [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
* [[Documentation/DevGuide/Extensions/Simple License|Simple License]]
* [[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
* [[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
* [[Documentation/DevGuide/Extensions/System Integration|System Integration]]
* [[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
<div id=Extensions2d" style="display:{{{Extensions2d|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Running Online - Update|Running Online - Update]]
* [[Documentation/DevGuide/Extensions/Concept|Concept]]
* [[Documentation/DevGuide/Extensions/Example Scenario for Providing Updates|Example Scenario for Providing Updates]]
* [[Documentation/DevGuide/Extensions/Migration of Update Information|Migration of Update Information]]
* [[Documentation/DevGuide/Extensions/Description of the Update Information|Description of the Update Information]]
* [[Documentation/DevGuide/Extensions/Description of Atom Feed|Description of Atom Feed]]
* [[Documentation/DevGuide/Extensions/Examples|Examples]]
</div>
* [[Documentation/DevGuide/Extensions/Options Dialog|Options Dialog]]
* [[Documentation/DevGuide/Extensions/Creating the GUI of the Options Page|Creating the GUI of the Options Page]]
* [[Documentation/DevGuide/Extensions/Saving and Reading Data for the Options Page|Saving and Reading Data for the Options Page]]
* [[Documentation/DevGuide/Extensions/Defining the Usage of Options Pages|Defining the Usage of Options Pages]]
<div id=Extensions2e" style="display:{{{Extensions2e|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/The Options Dialog of the Extension Manager|The Options Dialog of the Extension Manager]]
* [[Documentation/DevGuide/Extensions/Adding a Leaf to an Existing Node|Adding a Leaf to an Existing Node]]
* [[Documentation/DevGuide/Extensions/Adding Several Leaves|Adding Several Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Leaves|Grouping of Leaves]]
* [[Documentation/DevGuide/Extensions/Adding Nodes|Adding Nodes]]
* [[Documentation/DevGuide/Extensions/Adding Several Nodes|Adding Several Nodes]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Leaves|Absolute Position of Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Nodes|Grouping of Nodes]]
* [[Documentation/DevGuide/Extensions/Assigning Nodes to Modules|Assigning Nodes to Modules]]
* [[Documentation/DevGuide/Extensions/Defining a Module|Defining a Module]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Nodes|Absolute Position of Nodes]]
</div>
* [[Documentation/DevGuide/Extensions/Help Content|Help Content]]
}}

Documentation/DevGuide/Extensions/Updating Extensions

2010-06-07T15:18:05Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Repositories
|NextPage=Documentation/DevGuide/Extensions/Processing Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:The Active Extension}}
'''(As of OOo 3.3)'''

An extension can be updated by either explicitly installing the extension or by running the update function in the extension manager.
Updating an extension consisted originally in removing the installed extension and then installing the new version of the extension in the same repository. This meant that it was necessary to have write permission for the extensions folder of the shared repository for updating shared extensions. However, bundled extension could still not be updated by the extension manager, because this is exclusively done by the setup program.

However, in order to hide the complexity of the different repositories from the user and give them the best user experience, the extension manager will install updates for shared or bundled extensions in the user repository if necessary. That is, the installed extension will remain unchanged and the newer version is installed in a repository with a higher priority.

Users will be informed if there are newer versions of extensions which they currently use are available. It does not matter if the currently used extensions are from the user, shared or bundled repository. If there is a better version, then it is offered as an update. This allows users, to always obtain the latest versions of their extensions.

The updates, that is, the extensions with a newer version, will either be obtained from an online repository or locally, depending on which one have the highest versions. In the latter case, the newer version will come from the shared or bundled repository if there is one available. This is useful for the case when a user has installed an user extension and then a more current version is installed in the shared or bundled repository.

The following tables show scenarios where the user can update extensions. If a cell contains a “1” then this simple means there is an extensions installed. If it contains a “2” then this represents an extension with the same identifier then “1” but with a higher version. If there are several “2”s under each other then it is sufficient if just one of them has a higher version than “1”.

The first table shows the case where a user has '''no write permission''' in the shared folder. In all cases the update is installed in the '''user repository'''. The new version comes either from the shared, bundled or online repository, depending on which has the best version.

{| border="1" cellpadding="2"
!
! Case a
! Case b
! Case c
|-
|style="background:#EFDECD" |User repository || align="center" | - || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || align="center" | - ||align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"|2
|}

In words:
An update (installing in the user repository) is possible, if
#there is a bundled extension (no user and no shared) and the online repository contains a higher version
#there is shared extension (no user) and the bundled or online repository contains a higher version
#there is a user extension and the shared, bundled or online repository contains a higher version

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''shared repository'''. If a user extension exists does not matter.
{| border="1" cellpadding="2"
!
! Case a
! Case b
|-
|style="background:#EFDECD" |Shared repository || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in shared repository) is possible, if
#there is a bundled extension (and no shared) and the online repository contains a higher version
#there is shared extension and the bundled or online repository contains a higher version

This also means that, if there is only a user extension (no shared, no bundled) and there is one with a higher version in the online repository, then no update is done in the shared repository.

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''user repository'''.

{| border="1" cellpadding="2"
!
! Case a
|-
|style="background:#EFDECD" |User repository || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Bundled repository || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in user repository) is possible, if there is a user extension and the shared, bundled, or online repository contains a higher version.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Updating Extensions

2010-06-07T15:09:46Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Repositories
|NextPage=Documentation/DevGuide/Extensions/Updating Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:The Active Extension}}
'''(As of OOo 3.3)'''

An extension can be updated by either explicitly installing the extension or by running the update function in the extension manager.
Updating an extension consisted originally in removing the installed extension and then installing the new version of the extension in the same repository. This meant that it was necessary to have write permission for the extensions folder of the shared repository for updating shared extensions. However, bundled extension could still not be updated by the extension manager, because this is exclusively done by the setup program.

However, in order to hide the complexity of the different repositories from the user and give them the best user experience, the extension manager will install updates for shared or bundled extensions in the user repository if necessary. That is, the installed extension will remain unchanged and the newer version is installed in a repository with a higher priority.

Users will be informed if there are newer versions of extensions which they currently use are available. It does not matter if the currently used extensions are from the user, shared or bundled repository. If there is a better version, then it is offered as an update. This allows users, to always obtain the latest versions of their extensions.

The updates, that is, the extensions with a newer version, will either be obtained from an online repository or locally, depending on which one have the highest versions. In the latter case, the newer version will come from the shared or bundled repository if there is one available. This is useful for the case when a user has installed an user extension and then a more current version is installed in the shared or bundled repository.

The following tables show scenarios where the user can update extensions. If a cell contains a “1” then this simple means there is an extensions installed. If it contains a “2” then this represents an extension with the same identifier then “1” but with a higher version. If there are several “2”s under each other then it is sufficient if just one of them has a higher version than “1”.

The first table shows the case where a user has '''no write permission''' in the shared folder. In all cases the update is installed in the '''user repository'''. The new version comes either from the shared, bundled or online repository, depending on which has the best version.

{| border="1" cellpadding="2"
!
! Case a
! Case b
! Case c
|-
|style="background:#EFDECD" |User repository || align="center" | - || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || align="center" | - ||align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"|2
|}

In words:
An update (installing in the user repository) is possible, if
#there is a bundled extension (no user and no shared) and the online repository contains a higher version
#there is shared extension (no user) and the bundled or online repository contains a higher version
#there is a user extension and the shared, bundled or online repository contains a higher version

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''shared repository'''. If a user extension exists does not matter.
{| border="1" cellpadding="2"
!
! Case a
! Case b
|-
|style="background:#EFDECD" |Shared repository || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in shared repository) is possible, if
#there is a bundled extension (and no shared) and the online repository contains a higher version
#there is shared extension and the bundled or online repository contains a higher version

This also means that, if there is only a user extension (no shared, no bundled) and there is one with a higher version in the online repository, then no update is done in the shared repository.

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''user repository'''.

{| border="1" cellpadding="2"
!
! Case a
|-
|style="background:#EFDECD" |User repository || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Bundled repository || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in user repository) is possible, if there is a user extension and the shared, bundled, or online repository contains a higher version.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Updating Extensions

2010-06-07T14:39:28Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Repositories
|NextPage=Documentation/DevGuide/Extensions/Updating Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:The Active Extension}}
'''(As of OOo 3.3)'''

An extension can be updated by either explicitly installing the extension or by running the update function in the extension manager.
Updating an extension consisted originally in removing the installed extension and then installing the new version of the extension in the same repository. This meant that it was necessary to have write permission for the extensions folder of the shared repository for updating shared extensions. However, bundled extension could still not be updated by the extension manager, because this is exclusively done by the setup program.

However, in order to hide the complexity of the different repositories from the user and give them the best user experience, the extension manager will install updates for shared or bundled extensions in the user repository if necessary. That is, the installed extension will remain unchanged and the newer version is installed in a repository with a higher priority.

Users will be informed if there are newer versions of extensions which they currently use are available. It does not matter if the currently used extensions are from the user, shared or bundled repository. If there is a better version, then it is offered as an update. This allows users, to always obtain the latest versions of their extensions.

The updates, that is, the extensions with a newer version, will either be obtained from an online repository or locally, depending on which one have the highest versions. In the latter case, the newer version will come from the shared or bundled repository if there is one available. This is useful for the case when a user has installed an user extension and then a more current version is installed in the shared or bundled repository.

The following tables show scenarios where the user can update extensions. If a cell contains a “1” then this simple means there is an extensions installed. If it contains a “2” then this represents an extension with the same identifier then “1” but with a higher version. If there are several “2”s under each other then it is sufficient if just one of them has a higher version than “1”.

The first table shows the case where a user has '''no write permission''' in the shared folder. In all cases the update is installed in the '''user repository'''. The new version comes either from the shared, bundled or online repository, depending on which has the best version.

{| border="1" cellpadding="2"
!
! Case a
! Case b
! Case c
|-
|style="background:#EFDECD" |User repository || align="center" | - || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Shared repository || align="center" | - ||align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"|2
|}

In words:
An update (installing in the user repository) is possible, if
#there is a bundled extension (no user and no shared) and the online repository contains a higher version
#there is shared extension (no user) and the bundled or online repository contains a higher version
#there is a user extension and the shared, bundled or online repository contains a higher version

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''shared repository'''. If a user extension exists does not matter.
{| border="1" cellpadding="2"
!
! Case a
! Case b
|-
|style="background:#EFDECD" |Shared repository || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |Bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |Online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|}

In words:
An update (installing in shared repository) is possible, if
#there is a bundled extension (and no shared) and the online repository contains a higher version
#there is shared extension and the bundled or online repository contains a higher version

This also means that, if there is only a user extension (no shared, no bundled) and there is one with a higher version in the online repository, then no update is done in the shared repository.

The next table shows the case where the user has '''write permission''' in the shared folder. In all those cases the update/installation will happen in the '''user repository'''.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Updating Extensions

2010-06-07T14:23:15Z

Jl:

Template:Documentation/DevGuide/ExtensionsTOC

2010-06-07T14:20:55Z

Jl: added Updating Extensions

{{Documentation/MasterTOC
|ShowPrevPage={{{ShowPrevPage}}}
|PrevPage={{{PrevPage}}}
|ShowNextPage={{{ShowNextPage}}}
|NextPage={{{NextPage}}}
|bookid=DevGuide
|booktitle=[[Documentation/DevGuide/OpenOffice.org Developers Guide|OpenOffice.org Developer's Guide]]
|ShowParttitle=block
|parttitle=[[Documentation/DevGuide/Extensions/Extensions|Extensions]]
|ShowPrevPart=block
|PrevPart=Documentation/DevGuide/WritingUNO/Writing UNO Components
|ShowNextPart=block
|NextPart=Documentation/DevGuide/AdvUNO/Advanced UNO
|toccontent=
* [[Documentation/DevGuide/Extensions/Extension Manager|Extension Manager]]
<div id=Extensions2a" style="display:{{{Extensions2a|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Extension Repositories | Extension Repositories]]
* [[Documentation/DevGuide/Extensions/The Active Extension | The Active Extension]]
* [[Documentation/DevGuide/Extensions/Updating Extensions | Updating Extensions]]
* [[Documentation/DevGuide/Extensions/Deployment Items|Deployment Items]]
* [[Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User|Installing Extensions for All or a Single User]]
* [[Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org|Extension Manager in OpenOffice.org]]
* [[Documentation/DevGuide/Extensions/unopkg|unopkg]]
* [[Documentation/DevGuide/Extensions/Location of Installed Extensions|Location of Installed Extensions]]
* [[Documentation/DevGuide/Extensions/Extension Layers|Extension Layers]]
</div>
* [[Documentation/DevGuide/Extensions/Checklist for Writing Extensions|Checklist for Writing Extensions]]
* [[Documentation/DevGuide/Extensions/File Format|File Format]]
* [[Documentation/DevGuide/Extensions/description.xml|description.xml]]
<div id=Extensions2b" style="display:{{{Extensions2b|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Description of XML Elements|Description of XML Elements]]
* [[Documentation/DevGuide/Extensions/Localized XML Elements|Localized XML Elements]]
* [[Documentation/DevGuide/Extensions/Example|Example]]
</div>
* [[Documentation/DevGuide/Extensions/Display Name|Display Name]]
* [[Documentation/DevGuide/Extensions/Icon|Icon]]
* [[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
* [[Documentation/DevGuide/Extensions/Extension Identifiers|Extension Identifiers]]
* [[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
* [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
* [[Documentation/DevGuide/Extensions/Simple License|Simple License]]
* [[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
* [[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
* [[Documentation/DevGuide/Extensions/System Integration|System Integration]]
* [[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
<div id=Extensions2d" style="display:{{{Extensions2d|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Running Online - Update|Running Online - Update]]
* [[Documentation/DevGuide/Extensions/Concept|Concept]]
* [[Documentation/DevGuide/Extensions/Example Scenario for Providing Updates|Example Scenario for Providing Updates]]
* [[Documentation/DevGuide/Extensions/Migration of Update Information|Migration of Update Information]]
* [[Documentation/DevGuide/Extensions/Description of the Update Information|Description of the Update Information]]
* [[Documentation/DevGuide/Extensions/Description of Atom Feed|Description of Atom Feed]]
* [[Documentation/DevGuide/Extensions/Examples|Examples]]
</div>
* [[Documentation/DevGuide/Extensions/Options Dialog|Options Dialog]]
* [[Documentation/DevGuide/Extensions/Creating the GUI of the Options Page|Creating the GUI of the Options Page]]
* [[Documentation/DevGuide/Extensions/Saving and Reading Data for the Options Page|Saving and Reading Data for the Options Page]]
* [[Documentation/DevGuide/Extensions/Defining the Usage of Options Pages|Defining the Usage of Options Pages]]
<div id=Extensions2e" style="display:{{{Extensions2e|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/The Options Dialog of the Extension Manager|The Options Dialog of the Extension Manager]]
* [[Documentation/DevGuide/Extensions/Adding a Leaf to an Existing Node|Adding a Leaf to an Existing Node]]
* [[Documentation/DevGuide/Extensions/Adding Several Leaves|Adding Several Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Leaves|Grouping of Leaves]]
* [[Documentation/DevGuide/Extensions/Adding Nodes|Adding Nodes]]
* [[Documentation/DevGuide/Extensions/Adding Several Nodes|Adding Several Nodes]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Leaves|Absolute Position of Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Nodes|Grouping of Nodes]]
* [[Documentation/DevGuide/Extensions/Assigning Nodes to Modules|Assigning Nodes to Modules]]
* [[Documentation/DevGuide/Extensions/Defining a Module|Defining a Module]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Nodes|Absolute Position of Nodes]]
</div>
* [[Documentation/DevGuide/Extensions/Help Content|Help Content]]
}}

Documentation/DevGuide/Extensions/Updating Extensions

2010-06-07T14:18:57Z

Jl: Initial page

An extension can be updated by either explicitly installing the extension or by running the update function in the extension manager.
Updating an extension consisted originally in removing the installed extension and then installing the new version of the extension in the same repository. This meant that it was necessary to have write permission for the extensions folder of the shared repository for updating shared extensions. However, bundled extension could still not be updated by the extension manager, because this is exclusively done by the setup program.

However, in order to hide the complexity of the different repositories from the user and give them the best user experience, the extension manager will install updates for shared or bundled extensions in the user repository if necessary. That is, the installed extension will remain unchanged and the newer version is installed in a repository with a higher priority.

Users will be informed if there are newer versions of extensions which they currently use are available. It does not matter if the currently used extensions are from the user, shared or bundled repository. If there is a better version, then it is offered as an update. This allows users, to always obtain the latest versions of their extensions.

The updates, that is, the extensions with a newer version, will either be obtained from an online repository or locally, depending on which one have the highest versions. In the latter case, the newer version will come from the shared or bundled repository if there is one available. This is useful for the case when a user has installed an user extension and then a more current version is installed in the shared or bundled repository.

The following tables show scenarios where the user can update extensions. If a cell contains a “1” then this simple means there is an extensions installed. If it contains a “2” then this represents an extension with the same identifier then “1” but with a higher version. If there are several “2”s under each other then it is sufficient if just one of them has a higher version than “1”.

The first table shows the case where a user has '''no write permission''' in the shared folder. In all cases the update is installed in the '''user repository'''. The new version comes either from the shared, bundled or online repository, depending on which has the best version.

{| border="1" cellpadding="2"
!
! Case a
! Case b
! Case c
|-
|style="background:#EFDECD" |user repository || align="center" | - || align="center"| - || align="center"| 1
|-
|style="background:#EFDECD" |shared repository || align="center" | - ||align="center" | 1 || style="background:#BCD4E6" align="center" |2
|-
|style="background:#EFDECD" |bundled repository || align="center" | 1 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2
|-
|style="background:#EFDECD" |online repository || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"| 2 || style="background:#BCD4E6" align="center"|2
|}

Template:Documentation/DevGuide/ExtensionsTOC

2010-06-07T12:36:52Z

Jl: adde The Active Extension

{{Documentation/MasterTOC
|ShowPrevPage={{{ShowPrevPage}}}
|PrevPage={{{PrevPage}}}
|ShowNextPage={{{ShowNextPage}}}
|NextPage={{{NextPage}}}
|bookid=DevGuide
|booktitle=[[Documentation/DevGuide/OpenOffice.org Developers Guide|OpenOffice.org Developer's Guide]]
|ShowParttitle=block
|parttitle=[[Documentation/DevGuide/Extensions/Extensions|Extensions]]
|ShowPrevPart=block
|PrevPart=Documentation/DevGuide/WritingUNO/Writing UNO Components
|ShowNextPart=block
|NextPart=Documentation/DevGuide/AdvUNO/Advanced UNO
|toccontent=
* [[Documentation/DevGuide/Extensions/Extension Manager|Extension Manager]]
<div id=Extensions2a" style="display:{{{Extensions2a|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Extension Repositories | Extension Repositories]]
* [[Documentation/DevGuide/Extensions/The Active Extension | The Active Extension]]
* [[Documentation/DevGuide/Extensions/Deployment Items|Deployment Items]]
* [[Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User|Installing Extensions for All or a Single User]]
* [[Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org|Extension Manager in OpenOffice.org]]
* [[Documentation/DevGuide/Extensions/unopkg|unopkg]]
* [[Documentation/DevGuide/Extensions/Location of Installed Extensions|Location of Installed Extensions]]
* [[Documentation/DevGuide/Extensions/Extension Layers|Extension Layers]]
</div>
* [[Documentation/DevGuide/Extensions/Checklist for Writing Extensions|Checklist for Writing Extensions]]
* [[Documentation/DevGuide/Extensions/File Format|File Format]]
* [[Documentation/DevGuide/Extensions/description.xml|description.xml]]
<div id=Extensions2b" style="display:{{{Extensions2b|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Description of XML Elements|Description of XML Elements]]
* [[Documentation/DevGuide/Extensions/Localized XML Elements|Localized XML Elements]]
* [[Documentation/DevGuide/Extensions/Example|Example]]
</div>
* [[Documentation/DevGuide/Extensions/Display Name|Display Name]]
* [[Documentation/DevGuide/Extensions/Icon|Icon]]
* [[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
* [[Documentation/DevGuide/Extensions/Extension Identifiers|Extension Identifiers]]
* [[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
* [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
* [[Documentation/DevGuide/Extensions/Simple License|Simple License]]
* [[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
* [[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
* [[Documentation/DevGuide/Extensions/System Integration|System Integration]]
* [[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
<div id=Extensions2d" style="display:{{{Extensions2d|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Running Online - Update|Running Online - Update]]
* [[Documentation/DevGuide/Extensions/Concept|Concept]]
* [[Documentation/DevGuide/Extensions/Example Scenario for Providing Updates|Example Scenario for Providing Updates]]
* [[Documentation/DevGuide/Extensions/Migration of Update Information|Migration of Update Information]]
* [[Documentation/DevGuide/Extensions/Description of the Update Information|Description of the Update Information]]
* [[Documentation/DevGuide/Extensions/Description of Atom Feed|Description of Atom Feed]]
* [[Documentation/DevGuide/Extensions/Examples|Examples]]
</div>
* [[Documentation/DevGuide/Extensions/Options Dialog|Options Dialog]]
* [[Documentation/DevGuide/Extensions/Creating the GUI of the Options Page|Creating the GUI of the Options Page]]
* [[Documentation/DevGuide/Extensions/Saving and Reading Data for the Options Page|Saving and Reading Data for the Options Page]]
* [[Documentation/DevGuide/Extensions/Defining the Usage of Options Pages|Defining the Usage of Options Pages]]
<div id=Extensions2e" style="display:{{{Extensions2e|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/The Options Dialog of the Extension Manager|The Options Dialog of the Extension Manager]]
* [[Documentation/DevGuide/Extensions/Adding a Leaf to an Existing Node|Adding a Leaf to an Existing Node]]
* [[Documentation/DevGuide/Extensions/Adding Several Leaves|Adding Several Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Leaves|Grouping of Leaves]]
* [[Documentation/DevGuide/Extensions/Adding Nodes|Adding Nodes]]
* [[Documentation/DevGuide/Extensions/Adding Several Nodes|Adding Several Nodes]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Leaves|Absolute Position of Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Nodes|Grouping of Nodes]]
* [[Documentation/DevGuide/Extensions/Assigning Nodes to Modules|Assigning Nodes to Modules]]
* [[Documentation/DevGuide/Extensions/Defining a Module|Defining a Module]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Nodes|Absolute Position of Nodes]]
</div>
* [[Documentation/DevGuide/Extensions/Help Content|Help Content]]
}}

Documentation/DevGuide/Extensions/Extension Repositories

2010-06-07T12:35:02Z

Jl: changed NextPage

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Manager
|NextPage=Documentation/DevGuide/Extensions/The Active Extension
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Extension Repositories}}
'''(As of OOo 3.3)'''

OOo stores extensions in different places, the so-called repositories. This mostly does not matter for users because this has no influence on the extension's functionality. There are three repositories: user, shared and bundled. An extension can be part of every repository at the same time, but one repository can only hold one version of an extension. That is, assuming one has version one and version two of an extension, which also may be contained in different files, then only one of them can be installed per repository. The extension manager enforces this by checking the extension identifier which is stored within an extension.
The repositories are prioritized, meaning that an extension in a repository with a high priority is preferred over the same extension in a repository with a lower priority. The user repository has the highest and the bundled repository has the lowest priority.
An extension repository consists basically of two parts, the extensions and additional data, which is produced by the extension manager. In order to easier refer to the locations where these are stored, we name the location containing the extensions the extensions folder and the place where the other data is stored the registration data folder. Both folders may not necessarily be within the same parent folder. The registration data folder for all repositories are within the user installation (user data).

==User repository==
This repository contains extensions, aka user extensions, which can only be used by the user who installs them. Users can manage the user extensions themselves. That is, they can add, remove, disable and update them.

==Shared repository==
The extensions in this repository, which are also referred to as shared extension, can be used by all users - that's where the name “shared” comes from. Therefore they need to be located in a place accessible by all users, which is currently within the office installation. This place is usually restricted in terms of who is allowed to modify (write, delete) files. Therefore only people with the proper file access rights, who usually have an administrator or root account, can add, remove, update ( disabling is not supported) extensions in the shared repository. '''Before modifying a shared extension one must make sure that all other OOo processes, that is, OOo run by other users, are shut down.'''

==Bundled repository==
This repository holds the bundled extensions. They resemble to a certain degree the shared extensions. That is, they are usable by all users. But only those with the proper file access rights, can add and remove them. Bundled extensions are, as the name suggest, bundled with OOo. That is, they are part of the installation set and are already available after installation. Contrary to shared and user extensions, they are exclusively maintained by the installation program (aka setup) of OOo. Although they are visible in the extension manager's dialog, they cannot be modified by the extension manager, even by administrators. The setup program may offer to choose which extensions are to be installed. To later add or remove a bundled extension, one needs to restart the setup program and determine the wanted extensions. '''Before running the setup program one must make sure that all OOo processes are shut down.''' When the office is being uninstalled then all bundled extensions are removed.
{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/The Active Extension

2010-06-07T12:34:16Z

Jl: Initial page

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Repositories
|NextPage=Documentation/DevGuide/Extensions/Updating Extensions
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:The Active Extension}}
'''(As of OOo 3.3)'''

If the same extension is installed in the user and shared repository, then it is expected that only the one in the user repository is used. In other words it "hides" the one in the shared repository. This, however, was never the case (until now). It only worked if both extensions contained exactly the same items, such as services, configuration items, etc. However, two different versions of an extension often have different contents. For example, they may have different menu entries. Then the entries from both extensions would be displayed.

In case of having the same contents, one could rely on the underlying facilites, such as configuration manager, service manager, type description provider, to prefer the respective contents of the user extension over those of the shared extension. However, these facilities have no notion of an extension. For example, if the user and shared extension (having the same extension identifier) contain a service ''Foo'', then the service manager will provide the service ''Foo'' of the user extension. If the shared extension also contained the service ''Bar'', which is not in the user extension, then the service manager must not offer this service. To to this, the service manager would need the information, which extension contains the service. Similar all other facilities which process extension contents, like the configuration manager, need the association between a particular item and the respective extension.

The ''active extension'' solves this "hiding problem". It makes sure that an extension in a repository with a higher priority completely hides the same extension in a repository with a lower priority. This is done without extending all those facilities in a way so that they can deal with extensions. Instead the extension manager determines which extension may be used an which not. And this is how it works exactly:

There is a fixed hierarchy of repositories:
#user (highest priority)
#shared
#bundled (lowest priority)

This means that there can be three extensions with the same identifier. But only the one in the repository with the highest priority can be the active extension, unless it is disabled. Only disabling of user extensions is supported.

Only the active extension can be used in OOo. For example, if one extension is in all repositories, then only the services from the active extension will be used.
In the following explanation we assume that extensions have the same identifier, when speaking of extensions in different repositories, unless otherwise noted.

A user extension hides the shared extension, which in turn hides the bundled extension. If there is a user extension then it is always the active extension independent of its version and if there are extensions in the shared or bundled repository.

A shared extension can only be an active extension if there is no or a disabled user extension. Again, the version of the shared extension and the fact that there may be a bundled extension do not matter.
A bundled extension can only be an active extension if there are no shared or user extension. There may be, however, a disabled user extension.

An extension becomes active if it is registered (<idlm>com.sun.star.deployment.XPackage:registerPackage</idlm>) after having revoked (<idlm>com.sun.star.deployment.XPackage:revokePackage</idlm>) those extensions with the same identifier in other repositories. This means that of all the extensions with the same identifier in the different repositories, there is at most one registered at a time. For example:
#user extension: registered
#shared extension: revoked
#bundled extension: revoked
or
#no user extension
#shared extension: registerd
#bundled extension: revoked
or
#no user extension
#no shared extension
#bundled extension: registered

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Extension Manager

2010-06-07T11:48:55Z

Jl: changed NextPage

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extensions
|NextPage=Documentation/DevGuide/Extensions/Extension Repositories
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Extension Manager}}
The Extension Manager is a tool for managing extensions and other deployable items, such as separate libraries, JARs, configuration data files. This includes adding, removing, enabling and disabling of these items.

The Extension Manager can be started from within the office by pressing the menu item '''Tools > Extension Manager''' or by running the ''unopkg'' executable, which is contained in the program directory of the office installation.

When an extension is installed, then a copy is created which is kept either in the user installation or the shared installation (''<office-directory>/share''). The original extension can therefore be (re) moved after installation.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Template:Documentation/DevGuide/ExtensionsTOC

2010-06-07T11:47:39Z

Jl: added Extension Repositories

{{Documentation/MasterTOC
|ShowPrevPage={{{ShowPrevPage}}}
|PrevPage={{{PrevPage}}}
|ShowNextPage={{{ShowNextPage}}}
|NextPage={{{NextPage}}}
|bookid=DevGuide
|booktitle=[[Documentation/DevGuide/OpenOffice.org Developers Guide|OpenOffice.org Developer's Guide]]
|ShowParttitle=block
|parttitle=[[Documentation/DevGuide/Extensions/Extensions|Extensions]]
|ShowPrevPart=block
|PrevPart=Documentation/DevGuide/WritingUNO/Writing UNO Components
|ShowNextPart=block
|NextPart=Documentation/DevGuide/AdvUNO/Advanced UNO
|toccontent=
* [[Documentation/DevGuide/Extensions/Extension Manager|Extension Manager]]
<div id=Extensions2a" style="display:{{{Extensions2a|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Extension Repositories | Extension Repositories]]
* [[Documentation/DevGuide/Extensions/Deployment Items|Deployment Items]]
* [[Documentation/DevGuide/Extensions/Installing Extensions for All or a Single User|Installing Extensions for All or a Single User]]
* [[Documentation/DevGuide/Extensions/Extension Manager in OpenOffice.org|Extension Manager in OpenOffice.org]]
* [[Documentation/DevGuide/Extensions/unopkg|unopkg]]
* [[Documentation/DevGuide/Extensions/Location of Installed Extensions|Location of Installed Extensions]]
* [[Documentation/DevGuide/Extensions/Extension Layers|Extension Layers]]
</div>
* [[Documentation/DevGuide/Extensions/Checklist for Writing Extensions|Checklist for Writing Extensions]]
* [[Documentation/DevGuide/Extensions/File Format|File Format]]
* [[Documentation/DevGuide/Extensions/description.xml|description.xml]]
<div id=Extensions2b" style="display:{{{Extensions2b|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Description of XML Elements|Description of XML Elements]]
* [[Documentation/DevGuide/Extensions/Localized XML Elements|Localized XML Elements]]
* [[Documentation/DevGuide/Extensions/Example|Example]]
</div>
* [[Documentation/DevGuide/Extensions/Display Name|Display Name]]
* [[Documentation/DevGuide/Extensions/Icon|Icon]]
* [[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
* [[Documentation/DevGuide/Extensions/Extension Identifiers|Extension Identifiers]]
* [[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
* [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
* [[Documentation/DevGuide/Extensions/Simple License|Simple License]]
* [[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
* [[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
* [[Documentation/DevGuide/Extensions/System Integration|System Integration]]
* [[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
<div id=Extensions2d" style="display:{{{Extensions2d|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/Running Online - Update|Running Online - Update]]
* [[Documentation/DevGuide/Extensions/Concept|Concept]]
* [[Documentation/DevGuide/Extensions/Example Scenario for Providing Updates|Example Scenario for Providing Updates]]
* [[Documentation/DevGuide/Extensions/Migration of Update Information|Migration of Update Information]]
* [[Documentation/DevGuide/Extensions/Description of the Update Information|Description of the Update Information]]
* [[Documentation/DevGuide/Extensions/Description of Atom Feed|Description of Atom Feed]]
* [[Documentation/DevGuide/Extensions/Examples|Examples]]
</div>
* [[Documentation/DevGuide/Extensions/Options Dialog|Options Dialog]]
* [[Documentation/DevGuide/Extensions/Creating the GUI of the Options Page|Creating the GUI of the Options Page]]
* [[Documentation/DevGuide/Extensions/Saving and Reading Data for the Options Page|Saving and Reading Data for the Options Page]]
* [[Documentation/DevGuide/Extensions/Defining the Usage of Options Pages|Defining the Usage of Options Pages]]
<div id=Extensions2e" style="display:{{{Extensions2e|none}}};margin-left: 12px;">
* [[Documentation/DevGuide/Extensions/The Options Dialog of the Extension Manager|The Options Dialog of the Extension Manager]]
* [[Documentation/DevGuide/Extensions/Adding a Leaf to an Existing Node|Adding a Leaf to an Existing Node]]
* [[Documentation/DevGuide/Extensions/Adding Several Leaves|Adding Several Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Leaves|Grouping of Leaves]]
* [[Documentation/DevGuide/Extensions/Adding Nodes|Adding Nodes]]
* [[Documentation/DevGuide/Extensions/Adding Several Nodes|Adding Several Nodes]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Leaves|Absolute Position of Leaves]]
* [[Documentation/DevGuide/Extensions/Grouping of Nodes|Grouping of Nodes]]
* [[Documentation/DevGuide/Extensions/Assigning Nodes to Modules|Assigning Nodes to Modules]]
* [[Documentation/DevGuide/Extensions/Defining a Module|Defining a Module]]
* [[Documentation/DevGuide/Extensions/Absolute Position of Nodes|Absolute Position of Nodes]]
</div>
* [[Documentation/DevGuide/Extensions/Help Content|Help Content]]
}}

Documentation/DevGuide/Extensions/Extension Repositories

2010-06-07T11:20:29Z

Jl: Initial page

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Extension Manager
|NextPage=Documentation/DevGuide/Extensions/Deployment Items
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Extension Repositories}}
'''(As of OOo 3.3)'''

OOo stores extensions in different places, the so-called repositories. This mostly does not matter for users because this has no influence on the extension's functionality. There are three repositories: user, shared and bundled. An extension can be part of every repository at the same time, but one repository can only hold one version of an extension. That is, assuming one has version one and version two of an extension, which also may be contained in different files, then only one of them can be installed per repository. The extension manager enforces this by checking the extension identifier which is stored within an extension.
The repositories are prioritized, meaning that an extension in a repository with a high priority is preferred over the same extension in a repository with a lower priority. The user repository has the highest and the bundled repository has the lowest priority.
An extension repository consists basically of two parts, the extensions and additional data, which is produced by the extension manager. In order to easier refer to the locations where these are stored, we name the location containing the extensions the extensions folder and the place where the other data is stored the registration data folder. Both folders may not necessarily be within the same parent folder. The registration data folder for all repositories are within the user installation (user data).

==User repository==
This repository contains extensions, aka user extensions, which can only be used by the user who installs them. Users can manage the user extensions themselves. That is, they can add, remove, disable and update them.

==Shared repository==
The extensions in this repository, which are also referred to as shared extension, can be used by all users - that's where the name “shared” comes from. Therefore they need to be located in a place accessible by all users, which is currently within the office installation. This place is usually restricted in terms of who is allowed to modify (write, delete) files. Therefore only people with the proper file access rights, who usually have an administrator or root account, can add, remove, update ( disabling is not supported) extensions in the shared repository. '''Before modifying a shared extension one must make sure that all other OOo processes, that is, OOo run by other users, are shut down.'''

==Bundled repository==
This repository holds the bundled extensions. They resemble to a certain degree the shared extensions. That is, they are usable by all users. But only those with the proper file access rights, can add and remove them. Bundled extensions are, as the name suggest, bundled with OOo. That is, they are part of the installation set and are already available after installation. Contrary to shared and user extensions, they are exclusively maintained by the installation program (aka setup) of OOo. Although they are visible in the extension manager's dialog, they cannot be modified by the extension manager, even by administrators. The setup program may offer to choose which extensions are to be installed. To later add or remove a bundled extension, one needs to restart the setup program and determine the wanted extensions. '''Before running the setup program one must make sure that all OOo processes are shut down.''' When the office is being uninstalled then all bundled extensions are removed.
{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Description of XML Elements

2010-02-22T11:00:21Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/description.xml
|NextPage=Documentation/DevGuide/Extensions/Localized XML Elements
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Description of XML Elements}}
__NOTOC__
==== Element <code>/description</code> ====
* Parent element: document root
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/identifier|<identifier>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/version|<version>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/platform|<platform>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration|<registration>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information|<update-information>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher|<publisher>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes|<release-notes>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name|<display-name>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description|<extension-description>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/deploymentHooks|<deploymentHooks>]]</code>
*Since: OOo 2.0.4

<code><description></code> is the root element of the ''description.xml''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><description></code>
!Attribute
!Description
|-
|<code>xmlns</code>
|The default namespace of element description and all children must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>xmlns:dep</code>
|The namespace for dependency information must also be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>xmlns:xlink</code>
|The xlink namespace must be defined as
http://www.w3.org/1999/xlink
|-
|other namespace definitions
|Other namespaces can be added as necessary
|}

==== Element <code>/description/identifier</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children: none
*Since: OOo 2.2

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><identifier></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. The extension identifier.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Identifiers |Extension Identifiers]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/version</code> ====
*Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
*Children: none
*Since: OOo 2.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><version></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. A textual representation of the extension version.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/platform</code> ====
*Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
*Children: none
*Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><platform></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. A token representing a particular platform. See [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]] for details.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code>
* Since: OOo 2.0.4
The registration element currently only contains the <code><simple-license></code> element. If the <code><registration></code> element exists, then it must have a child element.

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration/simple-license</code> ====
Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration|<registration>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code>
* Since: OOo 2.0.4
The element contains the <code><license-text></code> elements, determines if all user must agree to the license, or just the person who installs it, and determines a default <code><license-text></code> element. The mechanism for determining a "default" has changed in OOo 2.4. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details. This element is disregarded for bundled extensions.

If the <code><simple-license></code> element exists, then it must have at least one child element.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><simple-license></code>
!Attribute
!Description
|-
|<code>accept-by</code>
|<code>Required.Value</code> is either “user” or “admin”. “user” means that every user has to agree to the license. That is, the extension can only be installed as user extension but not as shared extension. If it has the value “admin” then it can be deployed as shared extension as well. In that case only the person who installs it has to agree to the license. Individual users will not be asked to accept the license. They can use the extension right away. In case the value is “user” and the extension is being installed as user extension then the user must always agree to the license. By using <code>suppress-if-required=“true“</code> it is, however, possible to install an extension for all users, that is, as shared extension, even if <code>accept-by=“user“</code>.
|-
|<code>default-license-id</code>
|Required. Since OOo 2.4 this attribute is '''obsolete'''. If the extension should work properly (regarding showing the proper license during installation) on versions prior 2.4 one must use this attribute. If one does not use this attribute then one should use the [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|OpenOffice.org-minimal-version]] dependency with a value of '2.4'.
The attribute determines what <license-text> is used if no <license-text> element has a lang attribute whose value matches the locals of {{PRODUCTNAME}}. There must always be exactly one <code><license-text></code> element with a license-id attribute whose value matches that of the default-license-id. The type is <code>xsd:IDREF</code>.
|-
|<code>suppress-on-update</code>
|Optional. When the attribute is not provided then the value “false” is assumed. The value true indicates that the license for this extension will not be displayed during installation when the same extension (same id but probably different version) is already installed. This applies for the automatic update as well as for manually installing an extension. The version of the already installed extension does not matter. Suppressing the license can be useful during the online update, because otherwise the update operation could be interrupted by many license dialogs.
|-
|<code>suppress-if-required</code>
|Optional. Since 3.3. When the attribute is not provided then the value “false” is assumed. The value “true“ indicates that the license will not be displayed during installation if this is desired, which can be expressed by the unopkg switch <code>--suppress-license</code> and is implicitely assumed for bundled extensions.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration/simple-license/license-text</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code>
* Child elements: none
* Since: OOo 2.0.4

The element contains information about where to find the file containing the license text, which language it uses, and if this element is the “default” <code><license-text></code>. The mechanism for determining a "default" has changed in OOo 2.4. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><license-text></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a relative URL to the license file within the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|-
|<code>license-id</code>
|Optional. Since OOo 2.4 this attribute is '''obsolete'''. If the extension should work properly (regarding showing the proper license during installation) on versions prior 2.4 one must use this attribute. If one does not use this attribute then one should use the [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|OpenOffice.org-minimal-version]] dependency with a value of '2.4'.
One license-text element must have this attribute and the value must match the value of the default-license-id attribute of the <code><simple-license></code> element. The type is <code>xsd:ID</code>.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|<OpenOffice.org-minimal-version>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-maximal-version|<OpenOffice.org-maximal-version>]]</code>
** others
* Since: OOo 2.0.4

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies/OpenOffice.org-minimal-version</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
* Children: none
* Since: OOo 2.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><OpenOffice.org-minimal-version></code>
!Attribute
!Description
|-
|<code>xmlns:dep</code>
|The namespace for dependency information (inherited from <code><description></code>) must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>dep:name</code>
|Required. Descriptive string that will be displayed. Example : “OpenOffice.org value” (where value is the value of the attribute value).
|-
|<code>dep:OpenOffice.org-minimal-version</code>
|Optional. This attribute should never be used with this element.
|-
|<code>value</code>
|Required. String. The required underlying OpenOffice.org version (“2.1”, “2.2”, etc.), starting with OpenOffice.org 2.1. You cannot specify a particular corrective version, e.g. “2.2.1”, use “2.2” instead.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies/OpenOffice.org-maximal-version</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
* Children: none
* Since: OOo 3.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><OpenOffice.org-maximal-version></code>
!Attribute
!Description
|-
|<code>xmlns:dep</code>
|The namespace for dependency information (inherited from <code><description></code>) must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>dep:name</code>
|Required. Descriptive string that will be displayed. Example : “OpenOffice.org value or older” (where value is the value of the attribute value).
|-
|<code>dep:OpenOffice.org-minimal-version</code>
|Optional. This attribute should always be defined as “2.3” for this element.
|-
|<code>value</code>
|Required. The required maximal underlying OpenOffice.org version (“3.0”, “3.1”, etc.). You cannot specify a particular corrective version, e.g. “3.1.1”, use “3.1” instead.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]

==== Element <code>/description/update-information</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information/src|<src>]]</code>
* Since: OOo 2.2

<code><update-information></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information/src|<src>]]</code> child element. The second, third, etc. element are regarded as fallback, that is, the elements provide URLs to mirrors. The Extension Manager will try to get update information by using a URL and only use a different URL if an error occurred. That is, if for example the first URL references an atom feed that does not contain any references at all, but is a valid feed, then the Extension Manager assumes that there are no update information available. Then URLs from other <code><src></code> elements are not examined. Therefore the update information referenced by every URL must be identical.

'''See also'''
*[[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/update-information/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information|<update-information>]]</code>
* Children: none
* Since: OOo 2.2

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL which provides the update information directly or an atom feed which in turn references the update information. The URL can point directly to a file or it may invoke code, such as a servlet, cgi, etc, that returns the atom feed or the update information.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/publisher</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher/name|<name>]]</code>
* Since: OOo 2.4

<code><publisher></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher/name|<name>]]</code> child element. The children of this element provide a [[Documentation/DevGuide/Extensions/Localized XML Elements|localized publisher name]] together with a URL.

'''See also'''
*[[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/publisher/name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher|<publisher>]]</code>
* Children: Text
* Since: OOo 2.4

The text value of this element is the ''publisher name''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><name></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL to the web site of the publisher of the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/release-notes</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes/src|<src>]]</code>
* Since: OOo 2.4

<code><release-notes></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes/src|<src>]]</code> child element. The children provide URLs to [[Documentation/DevGuide/Extensions/Localized XML Elements|localized release-notes]].

Currently this element and its children are not used by the Extension Manager.

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/release-notes/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes|<release-notes>]]</code>
* Children: none
* Since: OOo 2.4

The element contains a URL to the ''release notes''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL to the release notes of the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/display-name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name/name|<name>]]</code>
* Since: OOo 2.4

<code><display-name></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name/name|<name>]]</code> child element. The children of this element provide a [[Documentation/DevGuide/Extensions/Localized XML Elements|localized display name]]. The name will be used in the GUI instead of the file name.

'''See also'''
*[[Documentation/DevGuide/Extensions/Display Name|Display Name]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/display-name/name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name|<display-name>]]</code>
* Children: Text
* Since: OOo 2.4

The text value of this element is the ''display name'' of the extension. The string length must be greater then null and must not only contain white space characters.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><name></code> ||
!Attribute
!Description
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Display Name|Display Name]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon/default|<default>]]</code>
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon/high-contrast|<high-contrast>]]</code>
* Since: OOo 3.0

'''See also'''
*[[Documentation/DevGuide/Extensions/Icon|Icon]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon/default</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
* Children: none
* Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><default></code> ||
!Attribute
!Description
|-
|<code>xlink:href</code>
|The value is a relative URL to the icon file within the extension.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon/high-contrast</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
* Children: none
* Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><high-contrast></code> ||
!Attribute
!Description
|-
|<code>xlink:href</code>
|The value is a relative URL to the icon file within the extension.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/extension-description</code> ====
Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description/src|<src>]]</code>
* Since: OOo 3.1
<extension-description> must have at least on [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description/src|<src>]] child element. Every child references a localized description. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/extension-description/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description|<extension-description>]]</code>
* Child elements: none
* Since: OOo 3.1

The element contains information about where to find the file containing the description text and which language it uses.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a relative URL to the description file within the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/deploymentHooks</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children: none
*Since: OOo 3.3

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><deploymentHooks></code>
!Attribute
!Description
|-
|<code>service</code>
|Required. The service identifier which implements the XDeploymentHooks interface.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension DeploymentHooks|Extension DeploymentHooks]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Simple License

2010-02-22T10:54:37Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2c=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/Target Platform
|NextPage=Documentation/DevGuide/Extensions/Dependencies
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Simple License}}
This feature is about displaying a license text to the user during installation. This is not supported for '''bundled extensions'''. Distributors of OOo need to clarify license details with the publishers of extensions, which they want to bundle with OOo.

The user can agree or decline the license, where in the latter case the installation will be aborted. It is called “Simple License” because there is no tamper resistant mechanism that prevents the installation in case the user does not agree to the license. It also does not do anything more than just displaying a license text. The text can be localized (see [[Documentation/DevGuide/Extensions/Localized XML Elements]]).

The license text is displayed either in a dialog or in the console dependent on the way the Extension Manager was started. When it was started by the '''Tools - Extension Manager''' menu item or by invoking <code>unopkg gui</code> in the console then a dialog is used. By using ''unopkg'' add the license text will be displayed in the console and user input has to be done through the same.

The license dialog or the license text in the console is displayed when the extension is being installed. Currently there are two modes to install extensions, user mode and shared mode. An extension that was installed in user mode (let's call it a ''user extension'') can only be used by just that person who installed it. If the extension was installed in shared mode (let's call it a ''shared extension''), then it can be used by all users. Since the license text is only displayed during installation, all users who are using a ''shared extension'' will not see any license text (except the user who installed this ''shared extension''). However, the publisher of the extension may think it necessary that everyone who wants to use it has to agree to the license first. For this purpose, he can mark the extension accordingly. This extension can then only be installed in user mode and not in shared mode. Likewise the extension can be marked indicating that only the person who installs it needs to agree to the license. Such an extension can be installed in both modes. But when installing in user mode then every user has to agree to the license nonetheless.

Here is an example of the description.xml:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<description xmlns="http://openoffice.org/extensions/description/2006"
xmlns:xlink="http://www.w3.org/1999/xlink">
<registration>
<simple-license accept-by="user" >
<license-text xlink:href="registration/license_de.txt" lang="de" />
<license-text xlink:href="registration/license_en_US.txt" lang="en-US" />
</simple-license>
</registration>
</description>
</source>

In this example, the license would have to be agreed to by all users (that means no shared mode installation). This is indicated by the value <code>user</code> of the attribute accept-by in the <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code> element. The attribute could also have the value <code>admin</code>, which would indicate that the license needs only be agreed to by the person who installs it.

The <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> elements contain information about the files which contain the text that is displayed. The content of these files must be UTF-8 encoded. It is displayed exactly as it is in the file. That is, no formatting occurs. There can be one to many <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> elements, where each element provides information about a different language of the license text. The attribute <code>xlink:href</code> contains a relative URL (relative to the root directory of the extension) which points to a file which contains the license text in exactly one language. Which language is indicated by <code>lang</code> attribute.

If the package manager does not find a <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> element which matches the locale of {{PRODUCTNAME}} then it will pick the first <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> element as the default. Prior to OOo 2.4. the default entry needed to marked explicitely by <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|license-id]]</code> attribute.

==Important Issues==

*Using the simple license in extensions always requires user interaction. Using <code>accept-by="user"</code> in the <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code> prevents this extension from being installed centrally, that is as shared extensions. Both issues can prevent the extension from being used by companies, which centrally maintain software.
*The 'simple license' does not work for bundled extensions (installation will probably hang as user input is required). If one wants to build an OOo installation set with bundled extensions, then they must not use this feature.

To get around these limitations, extensions need to provide the attribute [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|suppress-if-required="true"]].

'''See also'''
*[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|XML description for description.xml]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Description of XML Elements

2010-02-10T12:46:09Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/description.xml
|NextPage=Documentation/DevGuide/Extensions/Localized XML Elements
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Description of XML Elements}}
__NOTOC__
==== Element <code>/description</code> ====
* Parent element: document root
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/identifier|<identifier>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/version|<version>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/platform|<platform>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration|<registration>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information|<update-information>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher|<publisher>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes|<release-notes>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name|<display-name>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description|<extension-description>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/deploymentHooks|<deploymentHooks>]]</code>
*Since: OOo 2.0.4

<code><description></code> is the root element of the ''description.xml''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><description></code>
!Attribute
!Description
|-
|<code>xmlns</code>
|The default namespace of element description and all children must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>xmlns:dep</code>
|The namespace for dependency information must also be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>xmlns:xlink</code>
|The xlink namespace must be defined as
http://www.w3.org/1999/xlink
|-
|other namespace definitions
|Other namespaces can be added as necessary
|}

==== Element <code>/description/identifier</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children: none
*Since: OOo 2.2

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><identifier></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. The extension identifier.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Identifiers |Extension Identifiers]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/version</code> ====
*Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
*Children: none
*Since: OOo 2.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><version></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. A textual representation of the extension version.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/platform</code> ====
*Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
*Children: none
*Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><platform></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. A token representing a particular platform. See [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]] for details.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code>
* Since: OOo 2.0.4
The registration element currently only contains the <code><simple-license></code> element. If the <code><registration></code> element exists, then it must have a child element.

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration/simple-license</code> ====
Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration|<registration>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code>
* Since: OOo 2.0.4
The element contains the <code><license-text></code> elements, determines if all user must agree to the license, or just the person who installs it, and determines a default <code><license-text></code> element. The mechanism for determining a "default" has changed in OOo 2.4. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

If the <code><simple-license></code> element exists, then it must have at least one child element.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><simple-license></code>
!Attribute
!Description
|-
|<code>accept-by</code>
|<code>Required.Value</code> is either “user” or “admin”. “user” means that every user has to agree to the license. That is, the extension can only be installed as user extension but not as shared extension. If it has the value “admin” then it can be deployed as shared extension as well. In that case only the person who installs it has to agree to the license. Individual users will not be asked to accept the license. They can use the extension right away. In case the value is “user” and the extension is being installed as user extension then the user must always agree to the license. By using <code>suppress-if-required=“true“</code> it is, however, possible to install an extension for all users, that is, as shared extension, even if <code>accept-by=“user“</code>.
|-
|<code>default-license-id</code>
|Required. Since OOo 2.4 this attribute is '''obsolete'''. If the extension should work properly (regarding showing the proper license during installation) on versions prior 2.4 one must use this attribute. If one does not use this attribute then one should use the [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|OpenOffice.org-minimal-version]] dependency with a value of '2.4'.
The attribute determines what <license-text> is used if no <license-text> element has a lang attribute whose value matches the locals of {{PRODUCTNAME}}. There must always be exactly one <code><license-text></code> element with a license-id attribute whose value matches that of the default-license-id. The type is <code>xsd:IDREF</code>.
|-
|<code>suppress-on-update</code>
|Optional. When the attribute is not provided then the value “false” is assumed. The value true indicates that the license for this extension will not be displayed during installation when the same extension (same id but probably different version) is already installed. This applies for the automatic update as well as for manually installing an extension. The version of the already installed extension does not matter. Suppressing the license can be useful during the online update, because otherwise the update operation could be interrupted by many license dialogs.
|-
|<code>suppress-if-required</code>
|Optional. Since 3.3. When the attribute is not provided then the value “false” is assumed. The value “true“ indicates that the license will not be displayed during installation if this is desired, which can be expressed by the unopkg switch <code>--suppress-license</code> and is implicitely assumed for bundled extensions.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration/simple-license/license-text</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code>
* Child elements: none
* Since: OOo 2.0.4

The element contains information about where to find the file containing the license text, which language it uses, and if this element is the “default” <code><license-text></code>. The mechanism for determining a "default" has changed in OOo 2.4. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><license-text></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a relative URL to the license file within the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|-
|<code>license-id</code>
|Optional. Since OOo 2.4 this attribute is '''obsolete'''. If the extension should work properly (regarding showing the proper license during installation) on versions prior 2.4 one must use this attribute. If one does not use this attribute then one should use the [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|OpenOffice.org-minimal-version]] dependency with a value of '2.4'.
One license-text element must have this attribute and the value must match the value of the default-license-id attribute of the <code><simple-license></code> element. The type is <code>xsd:ID</code>.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|<OpenOffice.org-minimal-version>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-maximal-version|<OpenOffice.org-maximal-version>]]</code>
** others
* Since: OOo 2.0.4

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies/OpenOffice.org-minimal-version</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
* Children: none
* Since: OOo 2.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><OpenOffice.org-minimal-version></code>
!Attribute
!Description
|-
|<code>xmlns:dep</code>
|The namespace for dependency information (inherited from <code><description></code>) must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>dep:name</code>
|Required. Descriptive string that will be displayed. Example : “OpenOffice.org value” (where value is the value of the attribute value).
|-
|<code>dep:OpenOffice.org-minimal-version</code>
|Optional. This attribute should never be used with this element.
|-
|<code>value</code>
|Required. String. The required underlying OpenOffice.org version (“2.1”, “2.2”, etc.), starting with OpenOffice.org 2.1. You cannot specify a particular corrective version, e.g. “2.2.1”, use “2.2” instead.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies/OpenOffice.org-maximal-version</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
* Children: none
* Since: OOo 3.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><OpenOffice.org-maximal-version></code>
!Attribute
!Description
|-
|<code>xmlns:dep</code>
|The namespace for dependency information (inherited from <code><description></code>) must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>dep:name</code>
|Required. Descriptive string that will be displayed. Example : “OpenOffice.org value or older” (where value is the value of the attribute value).
|-
|<code>dep:OpenOffice.org-minimal-version</code>
|Optional. This attribute should always be defined as “2.3” for this element.
|-
|<code>value</code>
|Required. The required maximal underlying OpenOffice.org version (“3.0”, “3.1”, etc.). You cannot specify a particular corrective version, e.g. “3.1.1”, use “3.1” instead.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]

==== Element <code>/description/update-information</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information/src|<src>]]</code>
* Since: OOo 2.2

<code><update-information></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information/src|<src>]]</code> child element. The second, third, etc. element are regarded as fallback, that is, the elements provide URLs to mirrors. The Extension Manager will try to get update information by using a URL and only use a different URL if an error occurred. That is, if for example the first URL references an atom feed that does not contain any references at all, but is a valid feed, then the Extension Manager assumes that there are no update information available. Then URLs from other <code><src></code> elements are not examined. Therefore the update information referenced by every URL must be identical.

'''See also'''
*[[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/update-information/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information|<update-information>]]</code>
* Children: none
* Since: OOo 2.2

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL which provides the update information directly or an atom feed which in turn references the update information. The URL can point directly to a file or it may invoke code, such as a servlet, cgi, etc, that returns the atom feed or the update information.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/publisher</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher/name|<name>]]</code>
* Since: OOo 2.4

<code><publisher></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher/name|<name>]]</code> child element. The children of this element provide a [[Documentation/DevGuide/Extensions/Localized XML Elements|localized publisher name]] together with a URL.

'''See also'''
*[[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/publisher/name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher|<publisher>]]</code>
* Children: Text
* Since: OOo 2.4

The text value of this element is the ''publisher name''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><name></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL to the web site of the publisher of the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/release-notes</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes/src|<src>]]</code>
* Since: OOo 2.4

<code><release-notes></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes/src|<src>]]</code> child element. The children provide URLs to [[Documentation/DevGuide/Extensions/Localized XML Elements|localized release-notes]].

Currently this element and its children are not used by the Extension Manager.

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/release-notes/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes|<release-notes>]]</code>
* Children: none
* Since: OOo 2.4

The element contains a URL to the ''release notes''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL to the release notes of the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/display-name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name/name|<name>]]</code>
* Since: OOo 2.4

<code><display-name></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name/name|<name>]]</code> child element. The children of this element provide a [[Documentation/DevGuide/Extensions/Localized XML Elements|localized display name]]. The name will be used in the GUI instead of the file name.

'''See also'''
*[[Documentation/DevGuide/Extensions/Display Name|Display Name]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/display-name/name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name|<display-name>]]</code>
* Children: Text
* Since: OOo 2.4

The text value of this element is the ''display name'' of the extension. The string length must be greater then null and must not only contain white space characters.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><name></code> ||
!Attribute
!Description
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Display Name|Display Name]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon/default|<default>]]</code>
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon/high-contrast|<high-contrast>]]</code>
* Since: OOo 3.0

'''See also'''
*[[Documentation/DevGuide/Extensions/Icon|Icon]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon/default</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
* Children: none
* Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><default></code> ||
!Attribute
!Description
|-
|<code>xlink:href</code>
|The value is a relative URL to the icon file within the extension.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon/high-contrast</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
* Children: none
* Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><high-contrast></code> ||
!Attribute
!Description
|-
|<code>xlink:href</code>
|The value is a relative URL to the icon file within the extension.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/extension-description</code> ====
Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description/src|<src>]]</code>
* Since: OOo 3.1
<extension-description> must have at least on [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description/src|<src>]] child element. Every child references a localized description. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/extension-description/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description|<extension-description>]]</code>
* Child elements: none
* Since: OOo 3.1

The element contains information about where to find the file containing the description text and which language it uses.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a relative URL to the description file within the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/deploymentHooks</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children: none
*Since: OOo 3.3

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><deploymentHooks></code>
!Attribute
!Description
|-
|<code>service</code>
|Required. The service identifier which implements the XDeploymentHooks interface.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension DeploymentHooks|Extension DeploymentHooks]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Description of XML Elements

2010-02-10T12:41:43Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/description.xml
|NextPage=Documentation/DevGuide/Extensions/Localized XML Elements
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Description of XML Elements}}
__NOTOC__
==== Element <code>/description</code> ====
* Parent element: document root
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/identifier|<identifier>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/version|<version>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/platform|<platform>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration|<registration>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information|<update-information>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher|<publisher>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes|<release-notes>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name|<display-name>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description|<extension-description>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/deploymentHooks|<deploymentHooks>]]</code>
*Since: OOo 2.0.4

<code><description></code> is the root element of the ''description.xml''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><description></code>
!Attribute
!Description
|-
|<code>xmlns</code>
|The default namespace of element description and all children must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>xmlns:dep</code>
|The namespace for dependency information must also be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>xmlns:xlink</code>
|The xlink namespace must be defined as
http://www.w3.org/1999/xlink
|-
|other namespace definitions
|Other namespaces can be added as necessary
|}

==== Element <code>/description/identifier</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children: none
*Since: OOo 2.2

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><identifier></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. The extension identifier.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Identifiers |Extension Identifiers]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/version</code> ====
*Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
*Children: none
*Since: OOo 2.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><version></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. A textual representation of the extension version.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/platform</code> ====
*Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
*Children: none
*Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><platform></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. A token representing a particular platform. See [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]] for details.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code>
* Since: OOo 2.0.4
The registration element currently only contains the <code><simple-license></code> element. If the <code><registration></code> element exists, then it must have a child element.

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration/simple-license</code> ====
Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration|<registration>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code>
* Since: OOo 2.0.4
The element contains the <code><license-text></code> elements, determines if all user must agree to the license, or just the person who installs it, and determines a default <code><license-text></code> element. The mechanism for determining a "default" has changed in OOo 2.4. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

If the <code><simple-license></code> element exists, then it must have at least one child element.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><simple-license></code>
!Attribute
!Description
|-
|<code>accept-by</code>
|<code>Required.Value</code> is either “user” or “admin”. “user” means that every user has to agree to the license. That is, the extension can only be installed as user extension but not as shared extension. If it has the value “admin” then it can be deployed as shared extension as well. In that case only the person who installs it has to agree to the license. Individual users will not be asked to accept the license. They can use the extension right away. In case the value is “user” and the extension is being installed as user extension then the user must always agree to the license. By using <code>suppress-on-update=“true“</code> it is, however, possible to install an extension for all users even if <code>accept-by=“true“</code>.
|-
|<code>default-license-id</code>
|Required. Since OOo 2.4 this attribute is '''obsolete'''. If the extension should work properly (regarding showing the proper license during installation) on versions prior 2.4 one must use this attribute. If one does not use this attribute then one should use the [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|OpenOffice.org-minimal-version]] dependency with a value of '2.4'.
The attribute determines what <license-text> is used if no <license-text> element has a lang attribute whose value matches the locals of {{PRODUCTNAME}}. There must always be exactly one <code><license-text></code> element with a license-id attribute whose value matches that of the default-license-id. The type is <code>xsd:IDREF</code>.
|-
|<code>suppress-on-update</code>
|Optional. When the attribute is not provided then the value “false” is assumed. The value true indicates that the license for this extension will not be displayed during installation when the same extension (same id but probably different version) is already installed. This applies for the automatic update as well as for manually installing an extension. The version of the already installed extension does not matter. Suppressing the license can be useful during the online update, because otherwise the update operation could be interrupted by many license dialogs.
|-
|<code>suppress-if-required</code>
|Optional. Since 3.3. When the attribute is not provided then the value “false” is assumed. The value “true“ indicates that the license will not be displayed during installation if this desired, which can be expressed by the unopkg switch <code>--suppress-license</code> and is implicitely assumed for bundled extensions.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration/simple-license/license-text</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code>
* Child elements: none
* Since: OOo 2.0.4

The element contains information about where to find the file containing the license text, which language it uses, and if this element is the “default” <code><license-text></code>. The mechanism for determining a "default" has changed in OOo 2.4. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><license-text></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a relative URL to the license file within the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|-
|<code>license-id</code>
|Optional. Since OOo 2.4 this attribute is '''obsolete'''. If the extension should work properly (regarding showing the proper license during installation) on versions prior 2.4 one must use this attribute. If one does not use this attribute then one should use the [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|OpenOffice.org-minimal-version]] dependency with a value of '2.4'.
One license-text element must have this attribute and the value must match the value of the default-license-id attribute of the <code><simple-license></code> element. The type is <code>xsd:ID</code>.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|<OpenOffice.org-minimal-version>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-maximal-version|<OpenOffice.org-maximal-version>]]</code>
** others
* Since: OOo 2.0.4

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies/OpenOffice.org-minimal-version</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
* Children: none
* Since: OOo 2.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><OpenOffice.org-minimal-version></code>
!Attribute
!Description
|-
|<code>xmlns:dep</code>
|The namespace for dependency information (inherited from <code><description></code>) must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>dep:name</code>
|Required. Descriptive string that will be displayed. Example : “OpenOffice.org value” (where value is the value of the attribute value).
|-
|<code>dep:OpenOffice.org-minimal-version</code>
|Optional. This attribute should never be used with this element.
|-
|<code>value</code>
|Required. String. The required underlying OpenOffice.org version (“2.1”, “2.2”, etc.), starting with OpenOffice.org 2.1. You cannot specify a particular corrective version, e.g. “2.2.1”, use “2.2” instead.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies/OpenOffice.org-maximal-version</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
* Children: none
* Since: OOo 3.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><OpenOffice.org-maximal-version></code>
!Attribute
!Description
|-
|<code>xmlns:dep</code>
|The namespace for dependency information (inherited from <code><description></code>) must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>dep:name</code>
|Required. Descriptive string that will be displayed. Example : “OpenOffice.org value or older” (where value is the value of the attribute value).
|-
|<code>dep:OpenOffice.org-minimal-version</code>
|Optional. This attribute should always be defined as “2.3” for this element.
|-
|<code>value</code>
|Required. The required maximal underlying OpenOffice.org version (“3.0”, “3.1”, etc.). You cannot specify a particular corrective version, e.g. “3.1.1”, use “3.1” instead.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]

==== Element <code>/description/update-information</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information/src|<src>]]</code>
* Since: OOo 2.2

<code><update-information></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information/src|<src>]]</code> child element. The second, third, etc. element are regarded as fallback, that is, the elements provide URLs to mirrors. The Extension Manager will try to get update information by using a URL and only use a different URL if an error occurred. That is, if for example the first URL references an atom feed that does not contain any references at all, but is a valid feed, then the Extension Manager assumes that there are no update information available. Then URLs from other <code><src></code> elements are not examined. Therefore the update information referenced by every URL must be identical.

'''See also'''
*[[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/update-information/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information|<update-information>]]</code>
* Children: none
* Since: OOo 2.2

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL which provides the update information directly or an atom feed which in turn references the update information. The URL can point directly to a file or it may invoke code, such as a servlet, cgi, etc, that returns the atom feed or the update information.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/publisher</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher/name|<name>]]</code>
* Since: OOo 2.4

<code><publisher></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher/name|<name>]]</code> child element. The children of this element provide a [[Documentation/DevGuide/Extensions/Localized XML Elements|localized publisher name]] together with a URL.

'''See also'''
*[[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/publisher/name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher|<publisher>]]</code>
* Children: Text
* Since: OOo 2.4

The text value of this element is the ''publisher name''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><name></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL to the web site of the publisher of the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/release-notes</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes/src|<src>]]</code>
* Since: OOo 2.4

<code><release-notes></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes/src|<src>]]</code> child element. The children provide URLs to [[Documentation/DevGuide/Extensions/Localized XML Elements|localized release-notes]].

Currently this element and its children are not used by the Extension Manager.

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/release-notes/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes|<release-notes>]]</code>
* Children: none
* Since: OOo 2.4

The element contains a URL to the ''release notes''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL to the release notes of the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/display-name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name/name|<name>]]</code>
* Since: OOo 2.4

<code><display-name></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name/name|<name>]]</code> child element. The children of this element provide a [[Documentation/DevGuide/Extensions/Localized XML Elements|localized display name]]. The name will be used in the GUI instead of the file name.

'''See also'''
*[[Documentation/DevGuide/Extensions/Display Name|Display Name]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/display-name/name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name|<display-name>]]</code>
* Children: Text
* Since: OOo 2.4

The text value of this element is the ''display name'' of the extension. The string length must be greater then null and must not only contain white space characters.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><name></code> ||
!Attribute
!Description
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Display Name|Display Name]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon/default|<default>]]</code>
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon/high-contrast|<high-contrast>]]</code>
* Since: OOo 3.0

'''See also'''
*[[Documentation/DevGuide/Extensions/Icon|Icon]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon/default</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
* Children: none
* Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><default></code> ||
!Attribute
!Description
|-
|<code>xlink:href</code>
|The value is a relative URL to the icon file within the extension.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon/high-contrast</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
* Children: none
* Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><high-contrast></code> ||
!Attribute
!Description
|-
|<code>xlink:href</code>
|The value is a relative URL to the icon file within the extension.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/extension-description</code> ====
Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description/src|<src>]]</code>
* Since: OOo 3.1
<extension-description> must have at least on [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description/src|<src>]] child element. Every child references a localized description. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/extension-description/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description|<extension-description>]]</code>
* Child elements: none
* Since: OOo 3.1

The element contains information about where to find the file containing the description text and which language it uses.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a relative URL to the description file within the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/deploymentHooks</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children: none
*Since: OOo 3.3

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><deploymentHooks></code>
!Attribute
!Description
|-
|<code>service</code>
|Required. The service identifier which implements the XDeploymentHooks interface.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension DeploymentHooks|Extension DeploymentHooks]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]

Documentation/DevGuide/Extensions/Description of XML Elements

2010-02-10T12:40:43Z

Jl:

{{Documentation/DevGuide/ExtensionsTOC
|Extensions2b=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Extensions/description.xml
|NextPage=Documentation/DevGuide/Extensions/Localized XML Elements
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Extensions/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Description of XML Elements}}
__NOTOC__
==== Element <code>/description</code> ====
* Parent element: document root
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/identifier|<identifier>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/version|<version>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/platform|<platform>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration|<registration>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information|<update-information>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher|<publisher>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes|<release-notes>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name|<display-name>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description|<extension-description>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/deploymentHooks|<deploymentHooks>]]</code>
*Since: OOo 2.0.4

<code><description></code> is the root element of the ''description.xml''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><description></code>
!Attribute
!Description
|-
|<code>xmlns</code>
|The default namespace of element description and all children must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>xmlns:dep</code>
|The namespace for dependency information must also be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>xmlns:xlink</code>
|The xlink namespace must be defined as
http://www.w3.org/1999/xlink
|-
|other namespace definitions
|Other namespaces can be added as necessary
|}

==== Element <code>/description/identifier</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children: none
*Since: OOo 2.2

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><identifier></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. The extension identifier.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Identifiers |Extension Identifiers]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/version</code> ====
*Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
*Children: none
*Since: OOo 2.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><version></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. A textual representation of the extension version.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Versions|Extension Versions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/platform</code> ====
*Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
*Children: none
*Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><platform></code>
!Attribute
!Description
|-
|<code>value</code>
|Required. A token representing a particular platform. See [[Documentation/DevGuide/Extensions/Target Platform|Target Platform]] for details.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Target Platform|Target Platform]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code>
* Since: OOo 2.0.4
The registration element currently only contains the <code><simple-license></code> element. If the <code><registration></code> element exists, then it must have a child element.

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration/simple-license</code> ====
Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration|<registration>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license/license-text|<license-text>]]</code>
* Since: OOo 2.0.4
The element contains the <code><license-text></code> elements, determines if all user must agree to the license, or just the person who installs it, and determines a default <code><license-text></code> element. The mechanism for determining a "default" has changed in OOo 2.4. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

If the <code><simple-license></code> element exists, then it must have at least one child element.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><simple-license></code>
!Attribute
!Description
|-
|<code>accept-by</code>
|<code>Required.Value</code> is either “user” or “admin”. “user” means that every user has to agree to the license. That is, the extension can only be installed as user extension but not as shared extension. If it has the value “admin” then it can be deployed as shared extension as well. In that case only the person who installs it has to agree to the license. Individual users will not be asked to accept the license. They can use the extension right away. In case the value is “user” and the extension is being installed as user extension then the user must always agree to the license. By using <code>suppress-on-update=“true“</code> it is, however, possible to install an extension for all users even if the <code>accept-by=“true“</code>.
|-
|<code>default-license-id</code>
|Required. Since OOo 2.4 this attribute is '''obsolete'''. If the extension should work properly (regarding showing the proper license during installation) on versions prior 2.4 one must use this attribute. If one does not use this attribute then one should use the [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|OpenOffice.org-minimal-version]] dependency with a value of '2.4'.
The attribute determines what <license-text> is used if no <license-text> element has a lang attribute whose value matches the locals of {{PRODUCTNAME}}. There must always be exactly one <code><license-text></code> element with a license-id attribute whose value matches that of the default-license-id. The type is <code>xsd:IDREF</code>.
|-
|<code>suppress-on-update</code>
|Optional. When the attribute is not provided then the value “false” is assumed. The value true indicates that the license for this extension will not be displayed during installation when the same extension (same id but probably different version) is already installed. This applies for the automatic update as well as for manually installing an extension. The version of the already installed extension does not matter. Suppressing the license can be useful during the online update, because otherwise the update operation could be interrupted by many license dialogs.
|-
|<code>suppress-if-required</code>
|Optional. Since 3.3. When the attribute is not provided then the value “false” is assumed. The value “true“ indicates that the license will not be displayed during installation if this desired, which can be expressed by the unopkg switch <code>--suppress-license</code> and is implicitely assumed for bundled extensions.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/registration/simple-license/license-text</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/registration/simple-license|<simple-license>]]</code>
* Child elements: none
* Since: OOo 2.0.4

The element contains information about where to find the file containing the license text, which language it uses, and if this element is the “default” <code><license-text></code>. The mechanism for determining a "default" has changed in OOo 2.4. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><license-text></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a relative URL to the license file within the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|-
|<code>license-id</code>
|Optional. Since OOo 2.4 this attribute is '''obsolete'''. If the extension should work properly (regarding showing the proper license during installation) on versions prior 2.4 one must use this attribute. If one does not use this attribute then one should use the [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|OpenOffice.org-minimal-version]] dependency with a value of '2.4'.
One license-text element must have this attribute and the value must match the value of the default-license-id attribute of the <code><simple-license></code> element. The type is <code>xsd:ID</code>.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Simple License|Simple License]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-minimal-version|<OpenOffice.org-minimal-version>]]</code>
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies/OpenOffice.org-maximal-version|<OpenOffice.org-maximal-version>]]</code>
** others
* Since: OOo 2.0.4

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies/OpenOffice.org-minimal-version</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
* Children: none
* Since: OOo 2.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><OpenOffice.org-minimal-version></code>
!Attribute
!Description
|-
|<code>xmlns:dep</code>
|The namespace for dependency information (inherited from <code><description></code>) must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>dep:name</code>
|Required. Descriptive string that will be displayed. Example : “OpenOffice.org value” (where value is the value of the attribute value).
|-
|<code>dep:OpenOffice.org-minimal-version</code>
|Optional. This attribute should never be used with this element.
|-
|<code>value</code>
|Required. String. The required underlying OpenOffice.org version (“2.1”, “2.2”, etc.), starting with OpenOffice.org 2.1. You cannot specify a particular corrective version, e.g. “2.2.1”, use “2.2” instead.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/dependencies/OpenOffice.org-maximal-version</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/dependencies|<dependencies>]]</code>
* Children: none
* Since: OOo 3.1

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><OpenOffice.org-maximal-version></code>
!Attribute
!Description
|-
|<code>xmlns:dep</code>
|The namespace for dependency information (inherited from <code><description></code>) must be defined as
http://openoffice.org/extensions/description/2006
|-
|<code>dep:name</code>
|Required. Descriptive string that will be displayed. Example : “OpenOffice.org value or older” (where value is the value of the attribute value).
|-
|<code>dep:OpenOffice.org-minimal-version</code>
|Optional. This attribute should always be defined as “2.3” for this element.
|-
|<code>value</code>
|Required. The required maximal underlying OpenOffice.org version (“3.0”, “3.1”, etc.). You cannot specify a particular corrective version, e.g. “3.1.1”, use “3.1” instead.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Dependencies|Dependencies]]

==== Element <code>/description/update-information</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information/src|<src>]]</code>
* Since: OOo 2.2

<code><update-information></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information/src|<src>]]</code> child element. The second, third, etc. element are regarded as fallback, that is, the elements provide URLs to mirrors. The Extension Manager will try to get update information by using a URL and only use a different URL if an error occurred. That is, if for example the first URL references an atom feed that does not contain any references at all, but is a valid feed, then the Extension Manager assumes that there are no update information available. Then URLs from other <code><src></code> elements are not examined. Therefore the update information referenced by every URL must be identical.

'''See also'''
*[[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/update-information/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/update-information|<update-information>]]</code>
* Children: none
* Since: OOo 2.2

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL which provides the update information directly or an atom feed which in turn references the update information. The URL can point directly to a file or it may invoke code, such as a servlet, cgi, etc, that returns the atom feed or the update information.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Online Update of Extensions|Online Update of Extensions]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/publisher</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher/name|<name>]]</code>
* Since: OOo 2.4

<code><publisher></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher/name|<name>]]</code> child element. The children of this element provide a [[Documentation/DevGuide/Extensions/Localized XML Elements|localized publisher name]] together with a URL.

'''See also'''
*[[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/publisher/name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/publisher|<publisher>]]</code>
* Children: Text
* Since: OOo 2.4

The text value of this element is the ''publisher name''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><name></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL to the web site of the publisher of the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Publisher Information|Publisher Information]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/release-notes</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes/src|<src>]]</code>
* Since: OOo 2.4

<code><release-notes></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes/src|<src>]]</code> child element. The children provide URLs to [[Documentation/DevGuide/Extensions/Localized XML Elements|localized release-notes]].

Currently this element and its children are not used by the Extension Manager.

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/release-notes/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/release-notes|<release-notes>]]</code>
* Children: none
* Since: OOo 2.4

The element contains a URL to the ''release notes''.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a URL to the release notes of the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/display-name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name/name|<name>]]</code>
* Since: OOo 2.4

<code><display-name></code> must have at least one <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name/name|<name>]]</code> child element. The children of this element provide a [[Documentation/DevGuide/Extensions/Localized XML Elements|localized display name]]. The name will be used in the GUI instead of the file name.

'''See also'''
*[[Documentation/DevGuide/Extensions/Display Name|Display Name]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/display-name/name</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/display-name|<display-name>]]</code>
* Children: Text
* Since: OOo 2.4

The text value of this element is the ''display name'' of the extension. The string length must be greater then null and must not only contain white space characters.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><name></code> ||
!Attribute
!Description
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Display Name|Display Name]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon/default|<default>]]</code>
**<code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon/high-contrast|<high-contrast>]]</code>
* Since: OOo 3.0

'''See also'''
*[[Documentation/DevGuide/Extensions/Icon|Icon]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon/default</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
* Children: none
* Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><default></code> ||
!Attribute
!Description
|-
|<code>xlink:href</code>
|The value is a relative URL to the icon file within the extension.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/icon/high-contrast</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/icon|<icon>]]</code>
* Children: none
* Since: OOo 3.0

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><high-contrast></code> ||
!Attribute
!Description
|-
|<code>xlink:href</code>
|The value is a relative URL to the icon file within the extension.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/extension-description</code> ====
Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children:
** <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description/src|<src>]]</code>
* Since: OOo 3.1
<extension-description> must have at least on [[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description/src|<src>]] child element. Every child references a localized description. See [[Documentation/DevGuide/Extensions/Localized XML Elements]] for details.

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/extension-description/src</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description/extension-description|<extension-description>]]</code>
* Child elements: none
* Since: OOo 3.1

The element contains information about where to find the file containing the description text and which language it uses.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><src></code>
!Attribute
!Description
|-
|<code>xlink:href</code>
|Required. The value is a relative URL to the description file within the extension.
|-
|<code>lang</code>
|Required. A language identifier according to RFC 3066. See also [[Documentation/DevGuide/Extensions/Localized XML Elements]].
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension Description|Extension Description]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

==== Element <code>/description/deploymentHooks</code> ====
* Parent: <code>[[Documentation/DevGuide/Extensions/Description of XML Elements#Element /description|<description>]]</code>
* Children: none
*Since: OOo 3.3

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
|+ Attributes of <code><deploymentHooks></code>
!Attribute
!Description
|-
|<code>service</code>
|Required. The service identifier which implements the XDeploymentHooks interface.
|}

'''See also'''
*[[Documentation/DevGuide/Extensions/Extension DeploymentHooks|Extension DeploymentHooks]]
*[[Documentation/DevGuide/Extensions/Example|Example of description.xml]]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Extensions]]