Difference between revisions of "Adding fields"

Latest revision as of 16:37, 16 February 2010

Sometimes, you have to modify the semantic description of a category. The typical case happens when you find out that you have left out a crucial feature and you have to add it. To do that, you have to add a field to the semantic description of the category... and go through the additional modification to the wiki required to make the new field fully integrated with AIRWiki, and in particular to make it usable for semantic queries. However, think very well before embarking in such an endeavour... as you will quickly understand, it's not a straightforward process.

As an example, we will describe the operations performed to add a new field to the description of, in order to integrate the new field with the SMW framework of AIRWiki. Of course, the procedure can be easily generalized.

IMPORTANT: this kind of operations introduce structural changes in the AIRWiki. They should be performed only after consultation with professor Bonarini.

Let's add the field "Coordinator" to the Project category, to describe the person that is managing the project (while the "Tutor" is in charge of the students participating to it). These are the steps:

Creation of a new category called "Coordinator"

By using the Special:CreateCategory page, this is easy, but we are asked to specify which category (if any) Coordinator should be a subcategory of. The general rule is: define a new category B as a subcategory of a category A which includes all the possible elements of B, but the minimum number of elements outside B. If A doesn't exist, do not define B as a subcategory. By applying this rule, we define "Coordinator" as a subcategory of "Person": in fact the coordinator is most certainly a person, but can be even external to Politecnico di Milano.

Selection of the forms which are influenced by the change

The forms are used for simplified input of data, and are the preferred method to create new pages (when a form is available for the page, of course). Available forms are listed in the Special:Forms page: in our case, the only form to be changed is Form:Project.

Modification of the form for Project

Beware: this is a dangerous operation, if you are not an expert of SMW syntax. The best option is to use copy-and-paste judiciously.

By editing the Form:Project wiki page, we must now insert a field associated to the Coordinator category into the form. By adding

 ! [[Property:PrjCoordinator|Coordinator(s)]]:
 (NameSurname1; NameSurname2; ...)
 | {{{field|coordinator|mandatory|autocomplete on category=Coordinator|delimiter=; }}}
 |-

to the form in a suitable place, we ensure that:

• a new field (called "coordinator") is added to the form: from now on, any page created or edited using this form will possess a box where the coordinator must (note the "mandatory") be specified;
• a new property (called PrjCoordinator) has been introduced but not yet defined.

Creation of the new property PrjCoordinator associated to category Project

After its definition, the value of the property for a specific page belonging to that category will be usable to perform queries. This is done using the special page Special:CreateProperty. This creation mask asks you to specify the kind of values of the property: in our case, we choose one at random since we are going to replace the property page's wiki code immediately after.

Definition of the new property

This is done by editing page Property:PrjCoordinator; in this case we simply substituted the wiki code in it with the following text, adapted from Property:PrjTutor:

This property is used to indicate that a [[:Category:Project|Project]] is managed by one (ore more) [[:Category:Coordinator|Coodinators]].

Selection of the templates which are influenced by the change

The templates are used to format for output, in a standardized way, the data of a page. Available templates are listed in the Special:Templates page. At the time of writing this, the templates which are used to process data associated to a Project are the following:

• Template:Project (used to draw the frame on the right of the page associated to a Project);
• Template:ProjectViz, Template:ProjectVizSlim (used to display data about the items of a list of Projects).

Modification of the templates for Project

Beware: this is a dangerous operation, if you are not an expert of SMW syntax. The best option is to use copy-and-paste judiciously.

For template Template:Project, we have to perform two modifications. First, alteration of the description of the template by inserting the following text:

| coordinator=Leonardo Da Vinci
|         ***NOTE:*** you can specify a LIST of coordinators, separating them with a semicolon (;). Coordinators and tutors can overlap.

Then, alteration of the graphical description of the template to add a table row showing the coordinator(s). This requires adding the following text:

|-
{{Tablerow|Label=Coordinator|Value={{#ifeq:{{{coordinator|}}}|||{{#arraymap:{{{coordinator|}}}|; |x|[[prjCoordinator::User:x|x]] ({{#show: User:x| ?Email }})}}}}}}

Templates Template:ProjectViz and Template:ProjectVizSlim are used to format the output of a semantic query such as

{{#ask: [[Category:Project]]
| ?PrjTitle
| ?PrjImage
| ?PrjDescription
| ?PrjCoordinator
| ?PrjTutor
| ?PrjStarts
| ?PrjResArea
| ?PrjResTopic
| format = template
| template = ProjectVizSlim
}}

(note the reference to the template in the last line). The tricky part is that the wiki code of the template includes references to the single data fields output by the query, and that such references are positional. A template used to visualize data is something like this:

{| style="color:#333333;background-color:#eeeeff;" cellpadding="2" cellspacing="2" frame="border" width="100%"
'''Title:''' {{{1}}} <br> 
'''Description:''' {{{3}}} <br>
'''Coordinator:''' {{#arraymap:{{{4|}}}|, |x|x ({{#ask: x| ?Email= }})}} <br>
|}

Number {N} between curly brackets is a reference to the Nth value output by the query, with reference to the order of the fields in the query. (Note that not all the data output by the query is used by the template.) The point is: as the only connection between data output by a query and data input into a template is the position of such data within the query, if you change the template (e.g., adding a field), you could also have to change the query. So before changing a visualization template, you also have to find all AIRWiki pages which use that template; and possibly modify them too. To search the wiki for such pages, go to the page of the template and click "What links here" in the toolbox on the left of the page. You will get a list of pages linking to the template: then you have to check each of them to see if the template is used within one or more queries contained in the page. If this is the case, the queries should be checked and -if necessary- modified.

Let's return to the modification to that we performed (addition of field "Coordinator"). The first issue to define is this: are the ProjectViz and/or ProjectVizSlim templates in need of a modification? This need emerges if we want them to display the new data (the Coordinator field) added to the Project category. Unfortunately, this is the case for both templates: in fact we want them to show the Coordinator, so we will have to modify both of them by adding a new element.

In the case of ProjectViz, this is done by adding a new field immediately before the Tutor field. This is done by changing the wiki code from

{| style="color:#333333;background-color:#eeeeff;" cellpadding="2" cellspacing="2" frame="border" width="100%"
{{Projectrow|Label=Wiki Page|Value={{{1}}}}}
|rowspan=11 width=40% align="center"|{{#ifeq:{{{3|}}}|||[[{{{3}}}|center|300px]]}}
|-
{{Projectrow|Label=Title|Value={{{2}}}}}
|-
{{Projectrow|Label=Description|Value=[[prjDescription::{{{4}}}]]}}
|-
{{Projectrow|Label=Tutor|Value={{#arraymap:{{{5|}}}|, |x|x ({{#ask: x| ?Email= }})}}}}
|-
{{Projectrow|Label=Students|Value={{#arraymap:{{{6|}}}|, |x|x ({{#ask: x| ?Email= }})}}}}
|-
{{Projectrow|Label=Start|Value={{{7}}} {{#ifeq:{{{7|}}} }} }}
|-
{{Projectrow|Label=End|Value={{{8}}} {{#ifeq:{{{8|}}} }} }}
|-
{{#ifeq:{{{9|}}}|||{{Projectrow|Label=Research Area|Value=[[{{{9}}}]]}}}}
|-
{{#ifeq:{{{10|}}}|||{{Projectrow|Label=Research Topic|Value={{{10}}}}}}}
|-
{{#ifeq:{{{11|}}}|||{{Projectrow|Label=Level|Value={{{11}}}}}}}
|-
{{#ifeq:{{{12|}}}|||{{Projectrow|Label=Type|Value={{{12}}}}}}}
|}

to

[...]
{{Projectrow|Label=Description|Value=[[prjDescription::{{{4}}}]]}}
|-
{{Projectrow|Label=Coordinator|Value={{#arraymap:{{{5|}}}|, |x|x ({{#ask: x| ?Email= }})}}}}
|-
{{Projectrow|Label=Tutor|Value={{#arraymap:{{{6|}}}|, |x|x ({{#ask: x| ?Email= }})}}}}
|-
{{Projectrow|Label=Students|Value={{#arraymap:{{{7|}}}|, |x|x ({{#ask: x| ?Email= }})}}}}
|-[...]

But beware! As you see, the insertion of the new field necessitated that all the numbers associated to the data used by the following lines are modified by adding 1 to them! This means that all the queries in the AIRWiki using this template have to be modified too, otherwise the data they pass to the template to be displayed will be no more correct!

Fortunately, there is only one page using the ProjectViz template. Actually, the template is used by the following query within the page:

{{#ask: [[Category:Project]] 
[[PrjResArea::Social Software and Semantic Web]]|
?PrjTitle |
?PrjImage |
?PrjDescription |
?PrjTutor |
?PrjStudent |
?PrjStart |
?PrjEnd |
?PrjResArea |
?PrjResTopic |
?PrjLevel |
?PrjType |
format = template |
sort = prjStart |
order = desc |
template = Template:ProjectViz
}}

By modifying the query in the way shown below, all should be fixed.

[...]
?PrjDescription |
?PrjCoordinator |
?PrjTutor |
?PrjStudent |
[...]

We don't show the modifications to the ProjectVizSlim template and to the queries which use it, as they are similar.