Global variables

Help / Discuss
,
#1

For our internal documentation purposes, we have:

  • documents located on a network drive in various directories
  • source code located in repositories
  • JIRA tickets on a remote server
  • domain names for various web application servers

The paths to these locations change, albeit infrequently.

We’d like to create references so that when the network drive or servers change, we can edit the values in a single location such that the entire wiki retains the correct reference. For example, consider the following references:

It would be convenient to provide a simple syntax to use variables, so that we can write something like:

  • [REF.PROJECT]\Architecture\filename.docx
  • [REPO]/projects/project/src/main/Filename.java

Where [REF.PROJECT] maps to “Y:\Documents\Clients\Ministry\Projects” and [REPO] maps to https://svn.ministry.com/. The same idea would apply to JIRA and other servers.

I am wondering how to:

  • define these variables, globally (or at a particular page level for every page below it);
  • use these variables (i.e., what is the syntax); and
  • optionally, provide a visual interface that shows what variables are available?

Here’s an example user interface that offers variables for end users to use within a document: https://raw.githubusercontent.com/DaveJarvis/scrivenvar/master/images/screenshot.png

(I’m aware that the UI portion will likely take some significant XWiki development, so right now I’m looking for a way to define and use variables without a UI – editing the source directly is fine.)

#2

I would be also very interested in this topic. What would be the best practice approach here?

I thought that creating a page with an object that holds the configuration as properties may be an approach. But then you would have to write code in every page to access this information?

Even if this approach was feasible how would one store secrets that must not be read by “normal” users? Is there any way way to add them to the configuration file or any other place not accessible to users without creating an extension?

#3

There is not exactly universal variables you can use in any content right now.

It depends how you want to use those “variables”.

Here are a few ideas:

Actual variables you can use in a script

Define variable in some page and include that page when you need those variables and use a script macro when you need it a in:

{{include reference="MySpace.MyVariables"/}}

Download [[{{velocity}}${REF.PROJECT}\Architecture\filename.docx{{/verlocity}}]].

{{velocity}}
See $REPO/projects/project/src/main/Filename.java for the implementation of the file name.
{{/velocity}}

Where MySpace.MyVariable contains:

{{velocity output="false"}}
#set($REF =
{
  'PROJECTS' : 'Y:\Documents\Clients\Ministry\Projects',
  'OTHERS' : 'Y:\Documents\Clients\Ministry\Others'
})

#set($REPO = 'https://svn.ministry.com')
{{/velocity}}

Wiki macros

In xwiki.org we use the following macro http://www.xwiki.org/xwiki/bin/view/Macros/SCM.

If we ever move XWiki repositories somewhere else we just need to modify the macro (will happen soon for xwiki-enterprise for example, thanks for the reminder :slight_smile: ).

#4

Consider the following architecture:

JhXEW.png2550×3300

The conversion from Markdown to TeX will require interpretation of variables based on an external data source. As such, the variables in the document must be platform-agnostic.

This means: no {{velocity}} tags, no embedded scripting, no macros, no #set commands, no special dereferencing prefixes, no include statements, just plain variables. In other words, how the variables are defined must be independent from the source documents. For example, authors would write:

# {{application.title}}
This is the introduction for {{application.title}} {{application.version}}.

And the wiki would render the following:

# XWiki
This is the introduction for XWiki 10.11.1.

The interpolated variable definitions could come from any structured data source, including YAML, XML, database query, JSON over REST, etc. This would be configured globally for a particular wiki instance.

Additional features that would be handy, but not essential:

  • Edit (or view) the variable definitions and values
  • Use Shift+Space to insert variable names based on the text value at the cursor (e.g., typing "Missi|" followed by Shift+Space would insert {{application.author.address.city}})
  • Configurable start and end delimiter tags

Where would I begin with making global variables defined externally and accessible to all wiki pages?

#5

Not answering your question but wanted to let you know that XWiki supports Markdown as an input syntax (also as an output one FWIW) and LaTeX as an output syntax. So in XWiki you can convert from any syntax to LaTeX and thus MD -> LaTeX.

#6

Not answering your question but wanted to let you know that XWiki supports Markdown as an input syntax (also as an output one FWIW) and LaTeX as an output syntax. So in XWiki you can convert from any syntax to LaTeX and thus MD -> LaTeX.

Thank you, that’s very cool to know. I prefer ConTeXt to LaTeX as it makes separating document content from presentation far easier. (Also, knitr and pander are useful to have in the tool chain.)

The XWiki API to get a Markdown document is superb and the following works:

http://domain/bin/get/clients/client/?outputSyntax=markdown

The REST API documentation is a little light on examples for how to get a list of child pages in a machine-readable format. I’ve probably overlooked something between the reverse proxy, creating wikis, and the URL. I’ve tried:

But all these are incorrect.

How do you get a list of child pages (in JSON or XML format)?

#7

No problem! :slight_smile:

Yes we need more examples and to beef up the API where it’s lacking endpoints.

So your first try could have been:

However you’ll notice that while it works, it doesn’t list nested pages. This is a current limitation and I’ve created https://jira.xwiki.org/browse/XWIKI-16065. Vote for it if you’d like to see it implemented :slight_smile: (or even better, provide a PR!)

We have a way to list all children but not as a REST resource. For example:
http://localhost:8080/xwiki/bin/view/Sandbox/?viewer=children

However, it’s possible for you to create your own REST resources very easily. I’ve just taken the time to document this on your example, see https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HInWikiPages

This examples uses XML but you can output JSON instead or any format you want.

Hope it helps

#8

FTR this converts the content into Markdown. You could also decide to directly enter content in Markdown format in XWiki if you wanted. However it’s true that the XWiki syntax is better supported for round-tripping with the WYSIWYG editor.

#9

To give some background, I’m looking to avoid vendor lock-in when writing technical documentation. That is, I want to write documentation in plain Markdown that can be ported to any system and exported into any document format (including .docx, .txt, .tex, .html, and others). Adding custom Markup (velocity tags, macros, etc.) is contrary to this goal because the other systems aren’t necessarily Velocity- or FreeMarker-aware, nor even compatible with Java. The same holds true for assigning variables inside the web page.

For a better idea of what I’m trying to accomplish in XWiki, see the screenshot for Scrivenvar, a Java-based desktop Markdown editor that supports inclusion of interpolated variables.