Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

...	...	@@ -1,21 +1,60 @@
1	1	{{box cssClass="floatinginfobox" title="**Contents**"}}{{toc/}}{{/box}}
2		-XWiki integrates both Velocity and Groovy scripting. Together, these two mechanisms allow you to create basic to complex web applications at the XWiki page (or view) layer without the need for compiling code or deploying software components. In other words, you can use Velocity and Groovy script syntax in addition to wiki and HTML syntax as the contents of an XWiki page.
	2	+XWiki integrates [[jsr-223>>http://scripting.dev.java.net/]] scripting. [[Velocity>>http://velocity.apache.org/]], [[Groovy>>http://groovy.codehaus.org/]] and [[Python>>http://jython.sourceforge.net]] languages come bundled with XWiki while there are macros for Php and Ruby but the script engines are not bundled due to licensing concerns. Scripting allows you to create basic to complex web applications at the XWiki page (or view) layer without the need for compiling code or deploying software components. In other words, you can use scripting syntax in addition to wiki and HTML syntax as the contents of an XWiki page.
3	3
	4	+= XWiki Scripting API
	5	+
	6	+The API is documented in Javadoc format and can be accessed here: [[XWiki API Javadoc>>DevGuide.API]]. If you are not familiar with Java or object oriented programming, you will probably be confused by the API documentation. It is not within the scope of our documentation to teach you all the details about Java, or object oriented programming. You can find all of that information already online. You can also explore the page code found throughout the [[Code Zone>>code:Main.WebHome]] area to see how others have figured out how to achieve a variety of results.
	7	+
	8	+== [[Bindings>>code:Macros.ScriptMacro#HBindings]]
	9	+
	10	+These objects are available to you in scripting languages.
	11	+* [[The current Document>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Document.html]]: **##doc##**
	12	+* [[The Context of the request>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Context.html]]: **##xcontext##**
	13	+* [[The Request object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiRequest.html]]: **##request##**
	14	+* [[The Response object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiResponse.html]]: **##response##**
	15	+* [[The XWiki object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/XWiki.html]]: **##xwiki##**
	16	+
	17	+== [[XWiki Component>>code:Modules.ComponentModule]] Access:
	18	+
	19	+You can also gain direct access to XWiki components using the following code snippet:
	20	+Also see: [[Accessing components from Groovy>>DevGuide.WritingComponents#HAccessingacomponentfromgroovy]]
	21	+Note: This snippet is written in Groovy and will have to be converted to your scripting language.
	22	+{{code language=java}}
	23	+{{groovy}}
	24	+def greeter = com.xpn.xwiki.web.Utils.getComponent(org.xwiki.component.HelloWorld.class);
	25	+println greeter.sayHello();
	26	+{{/groovy}}
	27	+{{/code}}
	28	+
	29	+== XWiki Core Access:
	30	+
	31	+Sometimes the XWiki Api doesn't provide the methods which you need for your application. you can gain raw access the core of XWiki but it presents an increased security risk and as such should be avoided if at all possible.
	32	+{{code language=java}}
	33	+{{groovy}}
	34	+def xc = xcontext.getContext();
	35	+def wiki = xc.getWiki();
	36	+def xdoc = doc.getDocument();
	37	+{{/groovy}}
	38	+{{/code}}
	39	+After using this snippet, you will have 3 new objects:
	40	+* [[The underlying XWikiContext behind the Context object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/XWikiContext.html]]: **##xc##**
	41	+* [[The underlying XWiki object which backs the **##xwiki##** object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/XWiki.html]]: **##wiki##**
	42	+* [[The underlying XWikiDocument behind the current Document>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/doc/XWikiDocument.html]]: **##xdoc##**
	43	+
	44	+You will find that many of the methods in **##wiki##** and **##xdoc##** require an instance of the XWikiContext, this is **##xc##** not **##xcontext##**.
	45	+Again, these methods are only for the rare cases when functionality is not provided by the public Api and using this trick will increase the damage in the event that your script contains a security flaw which is exploited so it should be avoided when possible.
	46	+
4	4	{{id name=velocity /}}
5		-= XWiki's Velocity API
	48	+= Velocity Specific Information
6	6
7		-The concept of the 'context' is central to Velocity. The context is a 'carrier' of data between the Java layer of the XWiki engine and the template or page layer. The programmers of the XWiki core have gathered objects of various types and placed them in the Velocity context. These objects, and their methods and properties, are accessible via template elements called references and effectively form an API for XWiki.
	50	+Velocity is the only scripting language which can be used without Administration or Programming [[AdminGuide.Access Rights]]. This means you can save velocity scripts using a username with less permission and an exploit of your script is less of a security breach. Also if you are administrating a [[virtual wiki>>AdminGuide.Virtualization]] and you don't have programming rights, you can still do scripting in Velocity.
	51	+You can [[gain access to the XWiki core>>#HXWikiCoreAccess]] from Velocity but this will require programming rights.
8	8
9		-The API is documented in Javadoc format and can be accessed here: [[XWiki API Javadoc>>DevGuide.API]]. If you are not familiar with Java or object oriented programming, you will probably be confused by the API documentation. It is not within the scope of our documentation to teach you all the details about Velocity, Java, or object oriented programming. You can find all of that information already online. You should then refer to the [[Velocity User Guide>>http://velocity.apache.org/engine/releases/velocity-1.6.2/user-guide.html]] as an ongoing reference. Finally, you can explore the page code found throughout the [[Code Zone>>code:Main.WebHome]] area to see how others have figured out how to achieve a variety of results.
	53	+In Velocity you can't import classes and as such you cannot gain direct access to XWiki components as shown [[above>>#HXWikiComponentAccess]]. This leaves you with the provided [[bindings>>#HBindings]] (NOTE: In Velocity, these bindings all start with **##$##** as with all other Velocity variables)
10	10
11		-Velocity scripts can access the following:
12		-* [[The current document>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Document.html]]: **##$doc##**
13		-* [[The Context of the request>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/Context.html]]: **##$context##**
14		-* [[The Request object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiRequest.html]]: **##$request##**
15		-* [[The Response object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/web/XWikiResponse.html]]: **##$response##**
16		-* [[The XWiki object>>http://maven.xwiki.org/site/xwiki-core-parent/xwiki-core/apidocs/com/xpn/xwiki/api/XWiki.html]]: **##$xwiki##**
	55	+For more information about programming in the Velocity language, you can refer to the [[Velocity User Guide>>http://velocity.apache.org/engine/releases/velocity-1.6.2/user-guide.html]].
17	17
18		-In addition the following Velocity tools are also available in the Velocity context:
	57	+The following Velocity tools are also available in addition to the bindings.
19	19	* [[List Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/ListTool.html]]: **##$listtool##**
20	20	* [[Number Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/NumberTool.html]]: **##$numbertool##**
21	21	* [[Date Tool>>http://velocity.apache.org/tools/releases/1.4/javadoc/org/apache/velocity/tools/generic/DateTool.html]]: **##$datetool##**
...	...	@@ -33,9 +33,10 @@
33	33
34	34	{{info}}These variables can be used but are subject to change in the future.{{/info}}
35	35
36		-=== Controlling whether to display Comments/History/Attachment/Information sections or not
	75	+{{id name=HControllingwhethertodisplayCommentsHistoryAttachmentInformationsectionsornot /}}
	76	+=== Controlling Which Sections to Display
37	37
38		-It's possible to control whether to display these sections by setting some velocity variable to "no":
	78	+You can control whether to display Comments/History/Attachment/Information sections or not by setting some velocity variable to "no":
39	39
40	40	{{code}}
41	41	#set ($showcomments = "no")
...	...	@@ -50,9 +50,9 @@
50	50	#set($docextras = [])
51	51	{{/code}}
52	52
53		-= XWiki's Groovy API
	93	+= Groovy Specific Information
54	54
55		-Currently Groovy is only allowed for admins of a wiki (or users having the 'programming' right).
	95	+Currently all non Velocity scripting languages are only allowed for administrators of a wiki (or users having the 'programming' right).
56	56
57	57	* See Groovy examples in the [[Code Zone>>code:Main.WebHome]], more specifically in the [[Code Snippets area>>code:Snippets.WebHome]]
58	58	* [[Feeling Groovy>>http://www-128.ibm.com/developerworks/java/library/j-alj08034.html]]
...	...	@@ -96,3 +96,31 @@
96	96	%>
97	97	IP Address: $address
98	98	{{/code}}
	139	+
	140	+= Python Specific Information
	141	+
	142	+In Python, you have all of the powers available in Groovy but the default bindings are not available due to a [[bug in Jython>>http://bugs.jython.org/issue1426]] There is a workaround snippet which manually loads the context, document, wiki object, request and response available [[here>>code:Snippets.AccessToBindingsInPythonSnippet]].
	143	+
	144	+Example Snippet:
	145	+{{code language=python}}
	146	+{{python}}
	147	+import com.xpn.xwiki.web.Utils as Utils
	148	+import org.xwiki.context.Execution as Execution
	149	+import com.xpn.xwiki.api.Context as Context
	150	+import com.xpn.xwiki.api.Document as Document
	151	+xcontext = Context(Utils.getComponent(Execution).getContext().getProperty("xwikicontext"))
	152	+doc = Document(xcontext.getDoc(), xcontext.getContext())
	153	+print "The full name of this document is " + doc.getFullName()
	154	+{{/python}}
	155	+{{/code}}
	156	+
	157	+= Scripting In XWiki Syntax 1.0
	158	+
	159	+XWiki Syntax 1.0 is rendered by an old rendering engine which is a low development priority as it will eventually be removed. Syntax 1.0 has some idiosyncrasies which were solved by syntax 2.0.
	160	+
	161	+* The only scripting languages available to you are Velocity and Groovy.
	162	+* In Groovy, the context is known as: **##context##** not **##xcontext##**
	163	+* The beginning and end of Groovy scripts are denoted by <% and %> rather than through the [[code:Macros.GroovyMacro]] (using ~{{groovy}} and ~{{/groovy}})
	164	+* Velocity is parsed in a page no matter what (there is no need to invoke the [[code:Macros.VelocityMacro]] using ~{{velocity}} and ~{{/velocity}})
	165	+
	166	+The last part is important because it means you need to be careful of using $ and # in your document. This is still true inside of <% and %> so you have to be careful writing Groovy.