Exploring variables in QGIS 2.12, part 1

It’s been quite some time since I last had a chance to blog and a lot has happened since then. Not least of which is that QGIS 2.12 has now been released with a ton of new features that I’ve neglected to write about! To try and get things moving along here again I’m planning on writing a short series exploring how variables work in QGIS 2.12 and the exciting possibilities they unlock. First, let’s look into how variables can be used with QGIS map composer…

So, let’s get started! A new concept introduced in QGIS 2.12 is the ability to set custom variables for use in QGIS’ expression engine. The easiest way to do this is through the “Project Properties” dialog, under the “Variables” section:

Default project variables

Default project variables

You’ll see in the screenshot above that a blank project includes a number of read-only preset variables, such as @project_path and @project_title. (All variables in QGIS are prefixed with an @ character to differentiate them from fields or functions). You can add your own variables to this list by clicking the + button, as shown below:

Adding new variables to a project

Adding new variables to a project

Here I’ve added some new variables, @project_version and @author. Now, any of these variables can be used anywhere that you can use expressions in QGIS, including the field calculator, data defined symbology, labelling, map composer text, etc. So, you could make a map composer template with a label that includes the @author, @project_version and @project_path variables:

Variables in a composer label

Variables in a composer label

Sure, you *could* also manually enter all these details directly into the label for the same result. But what happens when you have multiple composers in your project, and need to update the version number in all of them? Or you move your project to a new folder and need to make sure the path is updated accordingly? Manually updating multiple composers is a pain – make QGIS do the work for you and instead use variables! This would especially be helpful if you’re saving map composer templates for use across multiple projects or users. Using variables will ensure that the template is automatically updated with the right details for the current project.

Another neat thing about QGIS variables is that they can be inherited and overridden, just like CSS rules. Opening the options dialog will also show a Variables group for setting “Global” variables. These variables are always available for your QGIS installation, regardless of what project you’re working on at the time. If your workplace tends to reorganise a lot and constantly shuffle your department around, you could add a global variable for @work_department, so that changing the global variable value in one place will automatically filter through to any existing and future projects you have.

Global variables

Global variables

And like I mentioned earlier, these variables are inherited through various “contexts” within QGIS. If I reopen the Project Properties dialog, you’ll see that a project has access to all the global variables plus the variables set within that specific project. In addition, by adding a variable with the same name to the Project variables the value of the Global variable will be overridden:

Overridden variables

Overridden variables

There’s also a variable editor within each individual composer’s properties tab, so variables can also be set and overridden on a composer-by-composer basis within a project. It’s a really flexible and powerful approach which both simplifies workflows and also opens up lots of new possibilities.

Stay tuned for more on this topic – this topic has only just scratched the surface of how expression variables have changed QGIS! (You can also read part 2 and part 3)

Tagged , , , ,

13 thoughts on “Exploring variables in QGIS 2.12, part 1

  1. Mark Percival says:

    Hi Nyall what should I put in the value of a project variable if I want to return the path to the project file whatever I open?

    • Nyall Dawson says:

      Hi Mark,

      You don’t need to manually do this – there’s an automatic, read only variable “@project_path” which is created by default and automatically filled with the project path. You should be able to see this by looking at the Variables group in Project Properties. There’s @project_filename, @project_folder, @project_path and @project_title created by default.

  2. […] on from part 1 in which I introduced how variables can be used in map composers, I’d like to now explore how […]

  3. Jerome says:

    Thanks for the interesting tip! Enjoying the Commonwealth Saga? 😉

    • Nyall Dawson says:

      Thanks! (and I’m glad that little reference was picked up by someone… I’m a huge fan of the series!)

  4. Salvatore says:

    Hello and congratulations,
    I follow with interest your lessons.
    Variables are a very interesting topic.
    I made some videos on youtube of some of your lessons.

    I would like to show you this video where use variables in a filter:
      “cod_reg” = @atlas_pagename



  5. Andreas Neumann says:

    Hi Nyall,

    First – let me thank you very much for this nice new functionality. It will make our use of QGIS definitely more productive for us!

    Would it be possible to add a global variable “Operating System”?

    It would help us set different file paths, depending on, whether the project is opened on Linux, Windows or OSX. We have a mixed environment – and while all users have access to the same resources, the file paths are different on each platform.

    So – if I could find out what platform is currently running QGIS, I could have a CASE statement and build different paths for file resources (e.g. paths to SVGs or photos in a composer).

    Similarly – it would be very interesting to find out whether QGIS is running on a regular QGIS Desktop context or in QGIS server. I may want to generate different output on Server, compared to Desktop.

    Please let me know, if these two enhancements would be possible to implement.

    Thank you very much,

  6. Tom says:

    Thanks Nyall, this is great stuff!

    Is it possible to use expressions in variables?

    I’ve tried setting up a global variable ‘blah blah Copyright [% year( now() )%]’ hoping that it would slot in the current year.

    That would make it even more awesome!

  7. Nago says:

    Hello, How I can show variables from Python console?

  8. Ayodele Adeyemo says:

    Hello Nyall,

    Thanks for this awesome post, I am currently using version 2.14 of QGIS and I am trying to use the @user_full_name and @user_account_name variables but at every time i try to create a new feature, it causes my QGIS to crash. Please can I have any help on this?

    Thanks ahead.

  9. E.Kristensen says:

    Is it possible to include system variables as “USERNAME” in print layout?

  10. Edouard says:

    Thank you very much for this great post, and for all those usefull ‘common’ variables created in QGIS. Just a suggestion for the next realeases of QGIS… : it would be great to add more variables for the map object in the composer, such as ‘map_projection’, ‘map_ellipsoid’, or ‘map_authid’ (e.g. ESPGXXXX) … in order to display dynamic crs strings in the titleblock from .qpt models.

    Thank you again

    Best regards, Edouard

Leave a Reply

Your email address will not be published. Required fields are marked *