Add documentation for auxiliary storage #2304

pblottiere · 2018-01-03T14:38:00Z

Once the PR #2299 merged, I'll add an entry in .qgz paragraph to quickly talk about auxiliary storage and .qgd files.

DelazJ · 2018-01-04T06:58:38Z

Hi, some quick comments at first glance:

why not adding it in the vector properties as part of the Layer properties dialog? I'm not sure this should have its own chapter
It may be because i read diagonally but sometimes it looked to me like a tutorial (which i feel may be more appropriate to understand the feature). However I wonder if there are not some screenshots we can remove:
- auxiliary_storage_store.png vs auxiliary_storage_symbol.png : i could not see the difference, except the zoom level
- auxiliary_storage_tab.png: not sure it's needed (particularly if we move to vector properties chapter
- auxiliary_storage_symbol_name.png : wouldn't a text be enough?
- auxiliary_storage_tabkey.png (same question but less sure)

But I'd like to hear others on this, please.

pblottiere · 2018-01-04T07:26:27Z

Hi @DelazJ!

why not adding it in the vector properties as part of the Layer properties dialog? I'm not sure this should have its own chapter

You're right, it'd be better this place.

auxiliary_storage_store.png vs auxiliary_storage_symbol.png : i could not see the difference, except the zoom level

auxiliary_storage_store.png is an image for data-defined properties in labeling tab whereas auxiliary_storage_symbol.png is for symbols.

However I wonder if there are not some screenshots we can remove. .... But I'd like to hear others on this, please.

I don't have a strong opinion on the matter, so let's hear from others.

Let me know! And thank you for your review, as always!

DelazJ

Now I can say that I know how auxiliary data storage works (an advantage of reviewing docs) but as I used to test when reviewing new features, I'm afraid that you'll find more questions/(sometimes) issue reports (I didn't follow QEP nor implementation). Some may not be clear because I add comments and reading/testing further, I realize that my comment was not really pertinent/complete/clear/true/... so I rewrite/delete/moved but I could have missed some.
Hope that helps.

DelazJ · 2018-01-09T23:16:49Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+possible if the underlying data is read only. Moreover, configuring these
+data-defined properties may be very time consuming or not desirable! For
+example, if you want to fully use map tools coming with :ref:`label_toolbar`,
+then you need to add and configure more than 20 fields in you original data


in your original

DelazJ · 2018-01-09T23:30:47Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+need to be editable!
+
+A tab is available in vector layer properties dialog to manage Auxiliary
+Storage:


Any reason of title casing auxiliary storage?

No, I updated this sentence to remove title casing.

DelazJ · 2018-01-10T12:17:08Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+properties without being editable, labeling map tools described in
+:ref:`label_toolbar` are always available as soon as labeling is activated.
+
+Actually, an auxiliary layer is needed to store these properties. Its creation


I would propose Actually, the auxiliary storage system needs an auxiliary layer to store these properties. The way it's currently written, I understand that storing properties when using label_toolbar requires an auxiliary layer, which is wrong given that i can still use my existing fields.

And then we could insert here (or line 78) some information about the layer format/storage and/or link to the "database" section. The line 93 mentions an underlying SQLite database but until that moment we never mention what was the format used so the reader could be puzzled by this info

DelazJ · 2018-01-10T13:10:35Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+
+Considering that the data source may be customized thanks to data-defined
+properties without being editable, labeling map tools described in
+:ref:`label_toolbar` are always available as soon as labeling is activated.


So we should maybe fix description at https://github.com/qgis/QGIS-Documentation/blame/ad02322343100ea85880055098614e91a5695b2f/source/docs/user_manual/working_with_vector/vector_properties.rst#L1546 (the use of now there means that it was not possible until you toggle edit button) but... see comments below

(anyway, we should inform in the label_toolbars chapter that auxiliary storage exists and can be used with it)

DelazJ · 2018-01-10T13:11:36Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+
+Actually, an auxiliary layer is needed to store these properties. Its creation
+process is run the first time you click on the map while a labeling map tool
+is currently activated. Then, a window is displayed, allowing to indicate the


This is where what looks like an issue to me arises: If I don't want an auxiliary storage but use my own fields, how do I proceed? I think this dialog should ask which system the user wants (my own fields vs auxiliaries). Selecting own (and the field to use btw) will toggle layer to edit (if not already done - because toggling to edit is prerequisite. Btw, when you select an existing field and edit is off, there should be a message when trying to use label tools).
Sorry to mention application issues here.

This is where what looks like an issue to me arises: If I don't want an auxiliary storage but use my own fields, how do I proceed?

You cannot use your own fields if the layer is not toggled as editable.

But if you set the corresponding data defined properties to your own fields (the regular way), then it's currently used by map tools when the layer is editable.

I think this dialog should ask which system the user wants (my own fields vs auxiliaries). Selecting own (and the field to use btw) will toggle layer to edit (if not already done - because toggling to edit is prerequisite).

Yes, why not! @haubourg, what do you think about it?

Well, yeah, we've had that discussion with @nyalldawson. We had to choose between easing life of newbie users - not aware of all the data defined capabilities - or advanced users. First implementation was not creating auxiliary fields transparently, and it appeared too complex for average users.

Adding a popup choice, would become very annoying quickly. I'd prefer a messagebar with a tip appearing once per session when user will first grab a custom labeling tool. I could be something like Custom labeling informations are stored in auxiliary data storage (.qgd file). If you need to use datasource field, please change data defined settings in labeling properties
Any other opinion?

Thanks for your inputs @haubourg I had in mind a single pop up, the first time. But thinking more about it, if we want to avoid too much clicks, the dialog should provide fields to pair up (which is easier to add in a dialog for rotation but may be tricky for move button or edit - btw does this work with labels tools; only text seems modifiable).
So a message bar can be the solution... if we do not want to dissuade people to continue to use their own fields to populate renderings options instead of auxiliary data.

DelazJ · 2018-01-10T14:54:49Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+===========================
+
+Once created, auxiliary fields may be edited through the
+:ref:`attribute table <sec_attribute_table>`. However, there's some subtlety


Does it mean that, once I set a "store Data in the project" and an auxiliary field is created and linked to the property, the only ways I have to set values for this property is either use label tools or attribute table?

Is there a way to retrieve later an expression I could have used to set the size of a label ie if I use some case expression with $scale to populate the auxiliary field, can I find this later or is it lost?

I'd appreciate some clarification here please. Thanks

Does it mean that, once I set a "store Data in the project" and an auxiliary field is created and linked to the property, the only ways I have to set values for this property is either use label tools or attribute table?

While the property is linked to an auxiliary field, yes, you've to use map tools or attribute table (actually, you should be able to directly update the underlying SQLite database but...). However, you can still "unlink" the auxiliary field in order to use your own data-defined (the regular way).

Is there a way to retrieve later an expression I could have used to set the size of a label ie if I use some case expression with $scale to populate the auxiliary field, can I find this later or is it lost?

I'm not sure to understand your question. @haubourg?

DelazJ · 2018-01-10T15:03:23Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+``0``.
+
+The :guilabel:`Delete` action completely removes the auxiliary layer. In other
+words, the corresponding table is deleted from the underlying SQLite database.


and properties customization are lost (or something like that).

Btw, doing that I realize that the DD icon becomes red (broken) --> I think it should be cleaned properly and set at original status.

and properties customization are lost (or something like that).

done

Btw, doing that I realize that the DD icon becomes red (broken) --> I think it should be cleaned properly and set at original status.

good point.

DelazJ · 2018-01-10T15:27:00Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+used for auxiliary storage is saved at the same place but with the extension
+``.qgd``.
+
+For conveniance, an archive may be used instead thanks to the ``.qgz`` format.


convenience, instead?

DelazJ · 2018-01-10T15:27:25Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+words, the corresponding table is deleted from the underlying SQLite database.
+
+Finally, the :guilabel:`Export` action allows to export the auxiliary layer
+thanks to the same tool than in case of :ref:`general_saveas`. Note that


... allows to save the auxiliary layer as a :ref:new vector layer <general_saveas>?

DelazJ · 2018-01-10T15:42:28Z

source/docs/user_manual/working_with_vector/auxiliary_storage.rst

+
+The Auxiliary Storage mechanism provides the solution to these limitations
+and awkward configurations. Actually, auxiliary fields are a roundabout
+mean to automatically manage and store these data-defined properties in a


data-defined properties (labels, diagram, symbology...)- given that nowhere we mention that diagrams are auxiliarisable

pblottiere · 2018-01-15T13:34:12Z

@DelazJ

I took into account your comments and I hope my answers are illuminating :)

Thanks a lot for your extensive review, it's much better this way!

Let me know if I have to update something else.

DelazJ · 2018-01-16T11:57:40Z

Thanks @pblottiere The file still needs to move into Vector Properties chapters. And also could you update the DD button description at https://docs.qgis.org/testing/en/docs/user_manual/introduction/general_tools.html#data-defined-override-setup with the "Store data..." option.

If someone else wants to give a look...

pblottiere · 2018-01-16T13:02:27Z

The file still needs to move into Vector Properties chapters.

I already moved Auxiliary Storage chapter within vector_properties.rst. But maybe I didn't understand what you meant?

And also could you update the DD button description at https://docs.qgis.org/testing/en/docs/user_manual/introduction/general_tools.html#data-defined-override-setup with the "Store data..." option.

OK, I'm going to do that.

DelazJ · 2018-01-16T13:09:15Z

I already moved Auxiliary Storage chapter within vector_properties.rst. But maybe I didn't understand what you meant?

Indeed. Sorry for the noise. I've seen the file name when replying to Regis (but it was the previous commit).

DelazJ · 2018-01-16T13:10:19Z

source/docs/user_manual/working_with_vector/vector_properties.rst

+.. note::
+
+  The :ref:`vector_auxiliary_storage` mechanism may be used with data-defined
+  properties without having and editable data source.


DelazJ reviewed Jan 10, 2018

View reviewed changes

DelazJ reviewed Jan 16, 2018

View reviewed changes

pblottiere added 6 commits January 16, 2018 13:30

Add documentation for auxiliary storage

a93a659

Move auxiliary storage doc to layer properties dialog

3566781

Update doc

fcf7b2a

Update DD button description

0aae16e

Fix typo

61d21e1

Add a note for qgz and auxiliary database

13eba5e

pblottiere force-pushed the as branch from 874e4e8 to 13eba5e Compare January 16, 2018 13:40

DelazJ merged commit 4a605e4 into qgis:master Feb 10, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for auxiliary storage #2304

Add documentation for auxiliary storage #2304

pblottiere commented Jan 3, 2018

DelazJ commented Jan 4, 2018

pblottiere commented Jan 4, 2018

DelazJ left a comment

DelazJ Jan 9, 2018

pblottiere Jan 15, 2018

DelazJ Jan 9, 2018

pblottiere Jan 15, 2018

DelazJ Jan 10, 2018

DelazJ Jan 10, 2018

pblottiere Jan 15, 2018

DelazJ Jan 10, 2018

pblottiere Jan 15, 2018

DelazJ Jan 10, 2018

pblottiere Jan 15, 2018

haubourg Jan 15, 2018 •

edited

DelazJ Jan 16, 2018

DelazJ Jan 10, 2018

DelazJ Jan 16, 2018

pblottiere Jan 16, 2018

DelazJ Jan 10, 2018

pblottiere Jan 15, 2018

DelazJ Jan 10, 2018

pblottiere Jan 15, 2018

DelazJ Jan 10, 2018

pblottiere Jan 15, 2018

DelazJ Jan 10, 2018

pblottiere Jan 15, 2018

pblottiere commented Jan 15, 2018

DelazJ commented Jan 16, 2018

pblottiere commented Jan 16, 2018

DelazJ commented Jan 16, 2018

DelazJ Jan 16, 2018

pblottiere Jan 17, 2018

Add documentation for auxiliary storage #2304

Add documentation for auxiliary storage #2304

Conversation

pblottiere commented Jan 3, 2018

DelazJ commented Jan 4, 2018

pblottiere commented Jan 4, 2018

DelazJ left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

haubourg Jan 15, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pblottiere commented Jan 15, 2018

DelazJ commented Jan 16, 2018

pblottiere commented Jan 16, 2018

DelazJ commented Jan 16, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

haubourg Jan 15, 2018 •

edited