Difference between revisions of "Documentation/DevGuide/Scripting/Scripting Framework URI Specification"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (FINAL VERSION FOR L10N)
(Complete rewriting)
Line 7: Line 7:
 
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Scripting/{{SUBPAGENAME}}}}  
 
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Scripting/{{SUBPAGENAME}}}}  
 
  {{DISPLAYTITLE:Scripting Framework URI Specification}}
 
  {{DISPLAYTITLE:Scripting Framework URI Specification}}
−
<code>vnd.sun.star.script:MACROREF?language=Language&location=[user|share|document]</code>
+
__NOTOC__
 +
=== General syntax ===
 +
The URI is a case-sensitive string. It is composed of fixed terms and three parameters:
 +
<code>vnd.sun.star.script:MACROPARAM?language=LANGPARAM&location=LOCPARAM</code>
  
 
where:
 
where:
 +
* <code>MACROPARAM</code> identifies the script.
 +
* <code>LANGPARAM</code> identifies the <code>LanguageScriptProvider</code> needed to execute the script as described. Current language values : Basic, BeanShell, Java, JavaScript, Python
 +
* <code>LOCPARAM</code> identifies the container of the script, i.e. My Macros, or {{PRODUCTNAME}} Macros, or within the current document, or in an extension.
  
−
* <code>MACROREF</code> is a name that identifies the macro and the naming convention for <code>MACROREF</code> identifiers is <code>LanguageScriptProvider</code> specific. It allows the <code>LanguageScriptProvider</code> to associate <code>MACROREF</code> with a macro. In the case of the <code>LanguageScriptProviders</code> for the Java based languages supported by {{PRODUCTNAME}} e.g. (Java, JavaScript & Beanshell) the convention is <code>Library.functionname</code> where <code>Library</code> is the subdirectory under the language specific directory and <code>functionname</code> is the function name from the ''parcel-descriptor.xml'' in the ''Library'' directory. See [[Documentation/DevGuide/Scripting/Scripting Framework URI Specification|Scripting Framework URI Specification]].
+
As the syntax of these parameters depends on each <code>LanguageScriptProvider</code> they are described hereafter for each implemented language. Terms like '''myLibrary''', '''myMacro''' are placeholders that stand for the names used in a real case.
−
* Language specifies the <code>LanguageScriptProvider</code> needed to execute the macro as described.
+
  
−
Example 1 – URI for a JavaScript macro ''Library1.myMacro.js'' located in the share directory of a {{PRODUCTNAME}} installation.
+
=== Basic script ===
 +
A Basic script is usually called : a macro. It may be a Sub or a Function.
  
−
  vnd.sun.star.script:Library1.myMacro.js?language=JavaScript&location=share
+
The Basic script is supposed to be created through the user interface, see section [[Documentation/DevGuide/Scripting/Editing,_Creating_and_Managing_Macros|Editing, Creating and Managing Macros]].
 +
==== LANGPARAM ====
 +
'''<code>Basic</code>'''
 +
==== LOCPARAM ====
 +
* macro in a library of My Macros : '''<code>application</code>'''
 +
* macro in a library of {{PRODUCTNAME}} Macros : '''<code>application</code>'''
 +
* macro in an extension installed for the current user : '''<code>application</code>'''
 +
* macro in an extension installed for all users : '''<code>application</code>'''
 +
* macro in a library of the document that calls the macro : '''<code>document</code>'''
 +
==== MACROPARAM ====
 +
The Basic macro <code>myMacro</code> is stored in module <code>myModule</code> itself stored in library <code>myLibrary</code>.
 +
* General case : the value of MACROPARAM is : '''<code>myLibrary.myModule.myMacro</code>'''
 +
* Basic script in an extension : same as above. The directory <code>myLibrary</code> containing the files constituting the Basic library must be stored in the extension package (see description in section [[Documentation/DevGuide/Basic/Application_Library_Container|Basic / Application Library Container]]).
  
−
In general macros contained in extensions have the format
+
Remember that, contrary with a usual call in Basic, you must respect the majuscules and minuscules of library, module, macro names.
  
−
  vnd.sun.star.script:MACROREF?language=TheLanguage&location=[user:uno_packages/packageName|share:uno_packages/packageName]
+
=== BeanShell script ===
 +
The BeanShell script is supposed to be created through the user interface, see section [[Documentation/DevGuide/Scripting/Editing,_Creating_and_Managing_Macros|Editing, Creating and Managing Macros]].
 +
==== LANGPARAM ====
 +
'''<code>BeanShell</code>'''
 +
==== LOCPARAM ====
 +
* script in a library of My Macros : '''<code>user</code>'''
 +
* script in a library of {{PRODUCTNAME}} Macros : '''<code>share</code>'''
 +
* script in an extension installed for the current user : '''<code>user:uno_packages/myExtension.oxt</code>''' where '''myExtension.oxt''' is the file name of the extension package.
 +
* script in an extension installed for all users : '''<code>share:uno_packages/myExtension.oxt</code>'''
 +
* script in a library of the document that calls the script : '''<code>document</code>'''
 +
==== MACROPARAM ====
 +
The BeanShell script <code>myMacro.bsh</code> is stored in library <code>myLibrary</code>.
 +
* General case : the value of MACROPARAM is : '''<code>myLibrary.myMacro.bsh</code>'''
 +
* BeanShell script in an extension :  same as above. The directory <code>myLibrary</code> containing the BeanShell script file and  '''parcel-descriptor.xml''' file must be stored in the extension package.
  
−
Example 2 - URI for a JavaScript macro ''Library1.myMacro.js'' located in an extension called ''myUnoPkg.oxt'' located in share directory of a {{PRODUCTNAME}} installation.
+
=== Java script ===
 +
Java scripts are macros in compiled Java. This is different from language JavaScript. See section [[Documentation/DevGuide/Scripting/Writing_Macros#Compiling_and_Deploying_Java_macros|Scripting / Writing Macros / Compiling and Deploying Java macros]].
 +
==== LANGPARAM ====
 +
'''<code>Java</code>'''
 +
==== LOCPARAM ====
 +
* script in a library of My Macros : '''<code>user</code>'''
 +
* script in a library of {{PRODUCTNAME}} Macros : '''<code>share</code>'''
 +
* script in an extension installed for the current user : '''<code>user:uno_packages/myExtension.oxt</code>''' where '''myExtension.oxt''' is the file name of the extension package.
 +
* script in an extension installed for all users : '''<code>share:uno_packages/myExtension.oxt</code>'''
 +
* script in a library of the document that calls the script : '''<code>document</code>'''
 +
==== MACROPARAM ====
 +
The Java script file <code>myMacro.jar</code> is stored in directory <code>myLibrary</code>. The Java method to be executed is <code>myMethod</code> (this is the value of <code>functionname</code> element of the '''parcel-descriptor.xml''' file).
 +
* General case : the value of MACROPARAM is : '''<code>myLibrary.myMethod</code>'''
 +
* Java compiled script in an extension : same as above. The directory <code>myLibrary</code> must be stored in the extension package.
  
−
  vnd.sun.star.script:Library1.myMacro.js?language=JavaScript&location=share:uno_packages/myUnoPkg.oxt
+
=== JavaScript script ===
 +
The JavaScript script is supposed to be created through the user interface, see section [[Documentation/DevGuide/Scripting/Editing,_Creating_and_Managing_Macros|Editing, Creating and Managing Macros]].
 +
==== LANGPARAM ====
 +
'''<code>JavaScript</code>'''
 +
==== LOCPARAM ====
 +
* script in a library of My Macros : '''<code>user</code>'''
 +
* script in a library of {{PRODUCTNAME}} Macros : '''<code>share</code>'''
 +
* script in an extension installed for the current user : '''<code>user:uno_packages/myExtension.oxt</code>''' where '''myExtension.oxt''' is the file name of the extension package.
 +
* script in an extension installed for all users : '''<code>share:uno_packages/myExtension.oxt</code>'''
 +
* script in a library of the document that calls the script : '''<code>document</code>'''
 +
==== MACROPARAM ====
 +
The JavaScript file <code>myMacro.js</code> is stored in library <code>myLibrary</code>.
 +
* General case : the value of MACROPARAM is : '''<code>myLibrary.myMacro.js</code>'''
 +
* JavaScript script in an extension :  same as above. The directory <code>myLibrary</code> containing the JavaScript file and  '''parcel-descriptor.xml''' file must be stored in the extension package.
 +
 
 +
=== Python script ===
 +
The location of a Python script is described in [[Python_as_a_macro_language|Python as a macro language]].
 +
==== LANGPARAM ====
 +
'''<code>Python</code>'''
 +
==== LOCPARAM ====
 +
* script in a library of My Macros : '''<code>user</code>'''
 +
* script in a library of {{PRODUCTNAME}} Macros : '''<code>share</code>'''
 +
* script in an extension installed for the current user : '''<code>user:uno_packages</code>'''
 +
* script in an extension installed for all users : '''<code>share:uno_packages</code>'''
 +
* script in a library of the document that calls the script : '''<code>document</code>'''
 +
==== MACROPARAM ====
 +
* General case : the Python module <code>myModule.py</code> is stored in directory <code>Scripts/python</code> of the user or share directory of the installation, or of the document. The name of the Python function to be executed is <code>myFunction</code>. The value of MACROPARAM is : '''<code>myModule.py$myFunction</code>'''
 +
* Python script in an extension : '''myExtension.oxt''' is the file name of the extension package. The Python module is stored in directory <code>myScript</code> in this package. The value of MACROPARAM is : '''<code>myExtension.oxt|myScript|myModule.py$myFunction</code>'''
 +
 
 +
=== Complete URI examples ===
 +
These URI's call a script stored in My macros
 +
vnd.sun.star.script:myLibrary.myModule.myMacro?language=Basic&location=application
 +
vnd.sun.star.script:myLibrary.myMacro.bsh?language=BeanShell&location=user
 +
vnd.sun.star.script:myLibrary.myMethod?language=Java&location=user
 +
vnd.sun.star.script:myLibrary.myMacro.js?language=JavaScript&location=user
 +
vnd.sun.star.script:myModule.py$myFunction?language=Python&location=user
 +
 
 +
{{Documentation/Note|As a consequence of the current URI syntax, an extension calling a non-Basic script must be created either for one user, or for all users, not both. You need one extension for each installation case, see {{bug|102542}}}}.
  
−
{{Documentation/Note|In the case of the {{PRODUCTNAME}} Basic language, no distinction is made internally between macros deployed in extensions and those not deployed extensions. Therefore in the case of a {{PRODUCTNAME}} Basic macro located in an extension the location attribute in the URI contains just “user” or “share”.}}
 
  
 
{{PDL1}}
 
{{PDL1}}
  
 
[[Category:Documentation/Developer's Guide/Scripting]]
 
[[Category:Documentation/Developer's Guide/Scripting]]

Revision as of 06:42, 28 May 2010



General syntax

The URI is a case-sensitive string. It is composed of fixed terms and three parameters: vnd.sun.star.script:MACROPARAM?language=LANGPARAM&location=LOCPARAM

where:

  • MACROPARAM identifies the script.
  • LANGPARAM identifies the LanguageScriptProvider needed to execute the script as described. Current language values : Basic, BeanShell, Java, JavaScript, Python
  • LOCPARAM identifies the container of the script, i.e. My Macros, or OpenOffice.org Macros, or within the current document, or in an extension.

As the syntax of these parameters depends on each LanguageScriptProvider they are described hereafter for each implemented language. Terms like myLibrary, myMacro are placeholders that stand for the names used in a real case.

Basic script

A Basic script is usually called : a macro. It may be a Sub or a Function.

The Basic script is supposed to be created through the user interface, see section Editing, Creating and Managing Macros.

LANGPARAM

Basic

LOCPARAM

  • macro in a library of My Macros : application
  • macro in a library of OpenOffice.org Macros : application
  • macro in an extension installed for the current user : application
  • macro in an extension installed for all users : application
  • macro in a library of the document that calls the macro : document

MACROPARAM

The Basic macro myMacro is stored in module myModule itself stored in library myLibrary.

  • General case : the value of MACROPARAM is : myLibrary.myModule.myMacro
  • Basic script in an extension : same as above. The directory myLibrary containing the files constituting the Basic library must be stored in the extension package (see description in section Basic / Application Library Container).

Remember that, contrary with a usual call in Basic, you must respect the majuscules and minuscules of library, module, macro names.

BeanShell script

The BeanShell script is supposed to be created through the user interface, see section Editing, Creating and Managing Macros.

LANGPARAM

BeanShell

LOCPARAM

  • script in a library of My Macros : user
  • script in a library of OpenOffice.org Macros : share
  • script in an extension installed for the current user : user:uno_packages/myExtension.oxt where myExtension.oxt is the file name of the extension package.
  • script in an extension installed for all users : share:uno_packages/myExtension.oxt
  • script in a library of the document that calls the script : document

MACROPARAM

The BeanShell script myMacro.bsh is stored in library myLibrary.

  • General case : the value of MACROPARAM is : myLibrary.myMacro.bsh
  • BeanShell script in an extension : same as above. The directory myLibrary containing the BeanShell script file and parcel-descriptor.xml file must be stored in the extension package.

Java script

Java scripts are macros in compiled Java. This is different from language JavaScript. See section Scripting / Writing Macros / Compiling and Deploying Java macros.

LANGPARAM

Java

LOCPARAM

  • script in a library of My Macros : user
  • script in a library of OpenOffice.org Macros : share
  • script in an extension installed for the current user : user:uno_packages/myExtension.oxt where myExtension.oxt is the file name of the extension package.
  • script in an extension installed for all users : share:uno_packages/myExtension.oxt
  • script in a library of the document that calls the script : document

MACROPARAM

The Java script file myMacro.jar is stored in directory myLibrary. The Java method to be executed is myMethod (this is the value of functionname element of the parcel-descriptor.xml file).

  • General case : the value of MACROPARAM is : myLibrary.myMethod
  • Java compiled script in an extension : same as above. The directory myLibrary must be stored in the extension package.

JavaScript script

The JavaScript script is supposed to be created through the user interface, see section Editing, Creating and Managing Macros.

LANGPARAM

JavaScript

LOCPARAM

  • script in a library of My Macros : user
  • script in a library of OpenOffice.org Macros : share
  • script in an extension installed for the current user : user:uno_packages/myExtension.oxt where myExtension.oxt is the file name of the extension package.
  • script in an extension installed for all users : share:uno_packages/myExtension.oxt
  • script in a library of the document that calls the script : document

MACROPARAM

The JavaScript file myMacro.js is stored in library myLibrary.

  • General case : the value of MACROPARAM is : myLibrary.myMacro.js
  • JavaScript script in an extension : same as above. The directory myLibrary containing the JavaScript file and parcel-descriptor.xml file must be stored in the extension package.

Python script

The location of a Python script is described in Python as a macro language.

LANGPARAM

Python

LOCPARAM

  • script in a library of My Macros : user
  • script in a library of OpenOffice.org Macros : share
  • script in an extension installed for the current user : user:uno_packages
  • script in an extension installed for all users : share:uno_packages
  • script in a library of the document that calls the script : document

MACROPARAM

  • General case : the Python module myModule.py is stored in directory Scripts/python of the user or share directory of the installation, or of the document. The name of the Python function to be executed is myFunction. The value of MACROPARAM is : myModule.py$myFunction
  • Python script in an extension : myExtension.oxt is the file name of the extension package. The Python module is stored in directory myScript in this package. The value of MACROPARAM is : myExtension.oxt|myScript|myModule.py$myFunction

Complete URI examples

These URI's call a script stored in My macros 

vnd.sun.star.script:myLibrary.myModule.myMacro?language=Basic&location=application
vnd.sun.star.script:myLibrary.myMacro.bsh?language=BeanShell&location=user
vnd.sun.star.script:myLibrary.myMethod?language=Java&location=user
vnd.sun.star.script:myLibrary.myMacro.js?language=JavaScript&location=user
vnd.sun.star.script:myModule.py$myFunction?language=Python&location=user

Template:Documentation/Note.


Content on this page is licensed under the Public Documentation License (PDL).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/DevGuide/Scripting/Scripting_Framework_URI_Specification&oldid=169365"
Personal tools
In other languages