Difference between revisions of "Documentation/DevGuide/Scripting/Scripting Framework URI Specification"
(Initial author Sun Microsystems, Inc.) |
|||
(8 intermediate revisions by 3 users not shown) | |||
Line 5: | Line 5: | ||
|NextPage=Documentation/DevGuide/Scripting/Storage of Scripts | |NextPage=Documentation/DevGuide/Scripting/Storage of Scripts | ||
}} | }} | ||
− | {{DISPLAYTITLE:Scripting Framework URI Specification}} | + | {{Documentation/DevGuideLanguages|Documentation/DevGuide/Scripting/{{SUBPAGENAME}}}} |
− | <code>vnd.sun.star.script: | + | {{DISPLAYTITLE:Scripting Framework URI Specification}} |
+ | __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. | ||
− | + | As the syntax of these parameters depends on each <code>LanguageScriptProvider</code> they are described hereafter for each implemented language. Terms like <code>myLibrary</code>, <code>myMacro</code> 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 [[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]]). | ||
− | + | Remember that, unlike usual calls 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 [[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. | ||
− | + | === 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. | ||
− | + | === 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 | ||
+ | |||
+ | |||
+ | These URI's call a script stored in an extension ''installed for all users'' | ||
+ | vnd.sun.star.script:myLibrary.myModule.myMacro?language=Basic&location=application | ||
+ | vnd.sun.star.script:myLibrary.myMacro.bsh?language=BeanShell&location=share:uno_packages/myExtension.oxt | ||
+ | vnd.sun.star.script:myLibrary.myMethod?language=Java&location=share:uno_packages/myExtension.oxt | ||
+ | vnd.sun.star.script:myLibrary.myMacro.js?language=JavaScript&location=share:uno_packages/myExtension.oxt | ||
+ | vnd.sun.star.script:myExtension.oxt|myScript|myModule.py$myFunction?language=Python&location=share:uno_packages | ||
+ | |||
+ | {{Warn|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}}}}. | ||
− | |||
{{PDL1}} | {{PDL1}} | ||
− | [[Category: Scripting]] | + | |
+ | [[Category:Documentation/Developer's Guide/Scripting]] |
Revision as of 07:36, 12 July 2018
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 theLanguageScriptProvider
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, unlike usual calls 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 directoryScripts/python
of the user or share directory of the installation, or of the document. The name of the Python function to be executed ismyFunction
. 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
These URI's call a script stored in an extension installed for all users
vnd.sun.star.script:myLibrary.myModule.myMacro?language=Basic&location=application vnd.sun.star.script:myLibrary.myMacro.bsh?language=BeanShell&location=share:uno_packages/myExtension.oxt vnd.sun.star.script:myLibrary.myMethod?language=Java&location=share:uno_packages/myExtension.oxt vnd.sun.star.script:myLibrary.myMacro.js?language=JavaScript&location=share:uno_packages/myExtension.oxt vnd.sun.star.script:myExtension.oxt|myScript|myModule.py$myFunction?language=Python&location=share:uno_packages
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 Issue 102542 |
Content on this page is licensed under the Public Documentation License (PDL). |