Set Attributes extension

Set Attributes extension

What is this extension for ?

You are editing or updating a dataset with features having many attributes. Some of these attributes can take a restricted set of values (ex. type of a building, maxspeed of a road, type of vegetation...). They may also be related to each others (ex. roads of type highway can have maxspeed of 110 or 130 while major roads are limited to 60, 70 or 90, and maxspeed must be empty for pedestrian paths).

Set attributes makes it possible to create a toolbox with buttons which will set one or many attributes in one go with a set of predefined values. When you press the button, attributes of all selected features are set to the desired value(s).

Selected features must be editable.

Tooltip : if you place your mouse above a button, you may get a small tooltip with the complete name of the button or a small explanation.

Advanced Tooltip : if you click on the right mouse button, you get a rich tooltip with the details of button parameters.

How does it work ?

You need to have the extension SetAttributes-x.y.jar in your lib/ext directory, and a xml file defining your toolbox in the lib/ext/set-attributes subdirectory (if this sub-directory does not exist, you'll have to create it with this exact name).

Indeed, you can have as many xml as you want in this directory. Each xml file defines a toolbox. When the plugin is executed (from menu Extension > SetAttributes), a dialog box will ask you which Toolbox you want to display. The list of available toolboxes is made from the list of xml files located in lib/ext/set-attributes sub-directory.

How can I create a new Toolbox to set attributes

The easiest way is to start from an example, but to achieve exactly what you want, you may have to know all the options available. Lets build a toolbox to set attributes in a "road" layer.

Main element : setAttributesToolbox

Your toolbox is defined by a xml file which main element is setAttributesToolbox. This element has 4 optional attributes :

• title : the title of the toolbox (default is empty)

• maxCol : the maximum number of columns or number of buttons in a row (default is 6)

• iconWidth : width if icons or buttons containing text (default is 32)

• iconHeight : height of icons or buttons containing text (default is 32)

Note 1 : all buttons have the same size.

Note 2 : 32 x 32 is a good size for buttons containing images, but for buttons containing text, you'll often need larger buttons.

here is an example of an empty Toolbox

<?xml version="1.0" encoding="UTF-8"?>
<setAttributesToolbox title="My first attribute set" maxCol="5">
</setAttributesToolbox>

The button element

A toolbox can contain as many element as needed. If the number of buttons is more than maxCol, button number maxCol+1 will be the first button in the second row. A button can contain an image (jpg, png or gif images are supported) or a text.

• icon : if an image with the name of the attribute icon can be loaded, this image is displayed in the button. Else, the text of the attribute text is displayed. It accepts 0xFFFFFF or #FFFFFF syntax.

• text : the text displayed on the button if no icon is set or if the icon is not found. You may need to set a larger iconWidth in setAttributesToolbox element to display the text.

• backgroundColor : this optional attribute can be used to set the background color of the button if no icon is defined. Note that the backgroundColor may color the background of the button or the border of the button depending on the selected look and field.

• atomic : a special (optional) attribute to define how the tool behaves if some attributes defined by the button can't be found.
  • If atomic is omitted or set to false, the tool will set as many attributes as it can, even if some attributes are not found.
  • If atomic is set to true, the tool will abandon the modification if it fails to set a single attribute.

• layer : The next (optional) attribute makes it possible to target a specific or several specific layers. This attributes understand
  • a simple layer name (ex. layer="road")
  • a layer name with asterisk (ex. layer="*road" for major roads or minor roads)
  • a regex if the name is written between / (ex. layer="/major roads|minor roads/")

Note that to match any layer, you can omit this attribute or set it to "*".

• dimension : This optional attribute can stop SetAttributes working for features which have not the requested dimension. Example : set dimension="1" if you want to restrict maxSpeed setting to features with LineString/MultiLineString geometries.

• tooltip : an optional attribute to set well.... a tooltip on the button.

And now, an example of a buton definition :

<button icon="img/361[70].png" text="70" atomic="true" layer="road*" tooltip="70 km/h">
   <attribute name="MaxSpeed" value="70"/>
</button>

Ow ! you already discovered how to set the sub-element attribute inside the button element.

The attribute element

Last element is the simplest. It may have three attributes :

• name : the name of the attribute to set. This attribute is mandatory.
• value : the new value for this attribute. This attribute is optional. If you omit the value attribute, the attribute will be set to null.
• prerequisite : This optional attribute makes it possible to set a condition to modify an attribute. It can take 3 kinds of value :
  • isNull : value will be set only if current value is null
  • isNullOrEmpty : value will be set only if current value is null or empty
  • =someText : value will be set only if curent value is someText
  • #someText : value will be set only if current value is not someText

You can associate as many attributes as you want to one button.

Let's put it all together :

<?xml version="1.0" encoding="UTF-8"?>
<setAttributesToolbox title="My first attribute set" maxCol="5" iconWidth="40" iconHeight="32">
   <button icon="img/361[70].png" text="70" atomic="true" layer="road*" tooltip="70 km/h">
       <attribute name="MaxSpeed" value="70"/>
   </button>
</setAttributesToolbox>

Error messages

While using SetAttributes, you can get 3 kind of messages

• No selected feature in an editable layer
• No selected feature in an editable layer matching mask {0}
• Set Attributes : inconsistency between attribute {0} and feature {1} #{2}