Difference between revisions of "Tips for editors"

From AIRWiki
Jump to: navigation, search
m (HOWTO add a field to the semantic description of a project)
m
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
''This page is a repository of suggestions, tips and tricks for editors (i.e., all users!) of AIRWiki.''
+
''This page is used to collect suggestions, links to help pages, tips and tricks for editors (i.e., all users!) of AIRWiki.''
  
== Resources ==
+
== Tips for MediaWiki users ==
These resources (internal to AIRWiki or not) can be handy when you are trying to figure out how to do something:
+
AIRWiki is based on [http://www.mediawiki.org/wiki/MediaWiki MediaWiki]. MediaWiki is a free software wiki package written in PHP, originally developed for Wikipedia: its very interesting combination between usability and possibilities makes it a widely used tool. One of the benefits of this is the fact that once you have learned to work with AIRWiki, you have also acquired the ability to work with Wikipedia and all other MediaWiki-based wikis.
  
* [http://www.mediawiki.org/wiki/Help:Contents MediaWiki help]: general help for users of wikis.
+
The main source for help and information about MediaWiki are the [http://www.mediawiki.org/wiki/Help:Contents MediaWiki help pages]. One of the most useful help pages is the one describing the [http://www.mediawiki.org/wiki/Help:Formatting basic formatting syntax] in MediaWiki.
* [http://semantic-mediawiki.org/wiki/Help:User_manual SMW help]: help on the semantic tools provided by the Semantic MediaWiki (SMW) extension used by AIRWiki.
+
* [[SMW_Project_Workflow]]: description of the complete lifecycle of a project in AIRWiki, from proposal to closure. Useful if you are setting up or coordinating a project.
+
* [[Dynamic Page Generation]]: guidelines for the creation of semantic queries within AIRWiki. A collection of useful examples.
+
* [[AIRWiki_Ontology]]: this is the structure of the ontology behind the semantic elements of AIRWiki. Useful to keep in mind when writing queries.
+
* [http://www.mediawiki.org/wiki/Extension:Semantic_MediaWiki SMW extension]: official page of the SMW extension for MediaWiki. It provides a list of the features of SMW.
+
* [http://www.mediawiki.org/wiki/Extension:Semantic_Forms Semantic Forms extension for SMW]: official page of the extension providing SMW with semantic forms functionality, listing its features.
+
  
Also, don't forget that the [[Special:SpecialPages | list of special pages]] includes many useful tools.
+
== Editing the Sidebar ==
 +
The Sidebar is the vertical strip on the left of the text area of the AIRWiki, shown whatever page you are looking at. You ''can' modify its content, of course, though it's not easy to find out how. Well, simply go to [[Mediawiki:Sidebar]] and edit that page.
  
== Tips for inexperienced Semantic MediaWiki users ==
+
== Embedding videos ==
AIRWiki includes semantic elements based on the [http://www.mediawiki.org/wiki/Extension:Semantic_MediaWiki Semantic MediaWiki (SMW)] extension to the established [http://www.mediawiki.org/ MediaWiki] system. The use of SMW enables the user with the possibility of using '''queries''' to extract specific content from the wiki; [[Dynamic_Page_Generation | here]] you can find some examples of queries.
+
You can embed videos from different websites (such as YouTube) inside the wiki, thanks to the MediaWiki EmbedVideo extension. If you want to embed a video inside your wiki page, check the extension documentation [http://www.mediawiki.org/wiki/Extension:EmbedVideo here] or open a page already containing videos (such as the one describing the [[Lurch]] project) and check its wikitext.
  
AIRWiki also uses the [http://www.mediawiki.org/wiki/Extension:Semantic_Forms Semantic Forms] extension to make semantic-level editing of pages easier through the use of customized [[Special:Forms | forms]].
+
== Tips for Semantic MediaWiki users ==
 +
To help MediaWiki users to get to grips with SMW and Semantic Forms, we set up a [[SMW tutorial | '''tutorial page''']]. (If you are not reasonably sure of how a wiki works, it's probably better if you practice that for a while before delving into SMW...)
  
Below you find some tips that should help MediaWiki users to get to grips with SMW. If you don't even know how MediaWiki works, it's better if you take a look to its [http://www.mediawiki.org/wiki/Help:Contents help page] before reading on.
+
== AIRWiki policy ==
 +
The following guidelines represent decisions about the structure of AIRWiki that have been taken. You should comply with them when editing the AIRWiki.
  
=== For newbies ===
+
* All reasonably ''static'' information about the AIRLab should be published in the [http://airlab.ws.dei.polimi.it/ AIRLab website]. All information which need to be modified more frequently (say: at least twice a year) should instead be put into the AIRWiki. The AIRWiki also offers the possibility of building pages which are automatically updated.
[http://semantic-mediawiki.org/wiki/Help:Introduction_to_Semantic_MediaWiki This webpage] gives a short introduction to what SMW is and why it is useful.
+
* The [http://airlab.ws.dei.polimi.it/ AIRLab website] should mention ''all'' the research areas active in AIRLab; but some of these could be absent from AIRWiki, since their researchers decided not touse it..
 
+
=== About the names of semantic properties ===
+
When writing queries, beware! The name of a property can be DIFFERENT from the name used in the semantic part of the wiki pages describing the objects of your query. For instance, any project page includes something like
+
<nowiki>{{</nowiki>Project
+
| [...]
+
| restopic=SomeTopic
+
| [...]
+
<nowiki>}}</nowiki>
+
But if you are writing a query to select the projects with topic SomeTopic you should NOT use
+
<nowiki>[[</nowiki>restopic::SomeTopic<nowiki>]]</nowiki>
+
Instead, you have to use the name of the property corresponding to the "restopic" field in the project page. This name is "prjResTopic": therefore your query should use
+
<nowiki>[[</nowiki>prjResTopic::SomeTopic<nowiki>]]</nowiki>
+
How can you find out the right name for the properties associated to (the content of) a page? When a page includes semantic information, clicking the "''Browse properties''" link in the toolbox on the left  gives you a list of all the properties defined for that page.
+
 
+
''Note 1: the correspondencies between properties and field names in the semantic code of a page are set by the relevant [[Special:Forms|semantic form]]. For instance, for a project they can be seen (and altered, if you know what you're doing...) by editing the [[Form:Project]] page.''
+
 
+
''Note 2: in some cases the name of a property is preceded by a prefix in the form "PREFIX:" this means that the property has been imported from an external ontology, or defined in accordance with it. Examples of such prefixes are "A:" (referring to [http://www.w3.org/2001/Annotea/ Annotea]) and "Foaf:" (referring to the [http://www.foaf-project.org/ Friend-Of-A-Friend project]). In any case, AIRWiki properties having a prefix are used exactly in the same way of the other properties.''
+
 
+
=== HOWTO add a field to the semantic description of a project ===
+
We will describe the operations that had to be performed to add a new field to the description of [[Category:Project | Projects]], in order to integrate the new field with the SMW framework of AIRWiki and to make it fully usable for semantic queries. 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 [[User:AndreaBonarini | 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:
+
 
+
'''1.''' 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.
+
 
+
'''2.''' Choice 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]].
+
 
+
'''3.''' Modification of the form for Project. By editing the [[Form:Project]] wiki page, we must now insert a field associated to the Coordinator category into the form. ''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 adding
+
 
+
! <nowiki>[[Property:PrjCoordinator|Coordinator(s)]]:</nowiki>
+
(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''.
+
 
+
'''4.''' 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.
+
 
+
'''5.''' 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]]:
+
 
+
<nowiki>This property is used to indicate that a [[:Category:Project|Project]] is managed by one (ore more) [[:Category:Coordinator|Coodinators]].</nowiki>
+
<nowiki><!-- Allowed values are all [[:Category:Coordinators|coordinators]]: {{#arraymap: {{#ask: [[Category:Tutor]]|format=list|link=none|sep=;}}|;|</nowiki>
+
<nowiki>x|[[allows value::x]]}} --></nowiki>
+
 
+
'''6.''' Choice of the templates  which are influenced by the change. The templates are used to display in a standardized way the data of a page. Available templates are listed in the [[Special:Templates]] page: in our case, the only form to be changed is [[Template:Project]] (it must be changed because it defines the category Project).
+
 
+
'''7.''' Modification of the template 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. In our case, we  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:
+
 
+
|-
+
<nowiki>{{Tablerow|Label=Coordinator|Value={{#ifeq:{{{coordinator|}}}|||{{#arraymap:{{{coordinator|}}}|; |x|[[prjCoordinator::User:x|x]] ({{#show: User:x| ?Email }})}}}}}}</nowiki>
+
 
+
== AIRWiki special pages dedicated to semantic content ==
+
 
+
The [[Special:SpecialPages]] page includes many interesting tools for the management of the semantic elements of AIRWiki. Below are those which are most useful to non-expert users.
+
 
+
=== Browsing existing elements ===
+
* [[Special:Categories]] list of categories
+
* [[Special:Properties]] list of properties
+
* [[Special:Templates]] list of templates (the interesting ones are those which define a category)
+
* [[Special:Browse]] browse the semantic content of pages
+
* [[Special:SearchByProperty]] search for pages having a specific value for a property
+
* [[Special:Ask]] use your own semantic query to search through AIRWiki
+
 
+
=== Creating new elements ===
+
* [[Special:AddPage]] create a new page with (also) semantic content, using one of the available forms
+
 
+
== Basic ideas behind AIRWiki ==
+
The following guidelines represent decisions about the structure of AIRWiki that have been taken. You should always comply with them when editing the AIRWiki.
+
 
+
* All reasonably static information about the AIRLab should be published in the [http://airlab.ws.dei.polimi.it/ AIRLab website]. All information which need to be modified more frequently (say: at least twice a year) should instead be put into the AIRWiki. The AIRWiki also offers the possibility of building pages which are automatically updated.
+
* The [http://airlab.ws.dei.polimi.it/ AIRLab website] should mention ''all'' the research areas active in AIRLab; but some of these could be absent from the AIRWiki.
+
 
* AIRWiki DOES NOT include a "Projects" page (where the projects of AIRLab are listed). Projects are listed in the pages of the relevant [[Research Areas | research area]].
 
* AIRWiki DOES NOT include a "Projects" page (where the projects of AIRLab are listed). Projects are listed in the pages of the relevant [[Research Areas | research area]].

Latest revision as of 15:48, 29 June 2012

This page is used to collect suggestions, links to help pages, tips and tricks for editors (i.e., all users!) of AIRWiki.

Tips for MediaWiki users

AIRWiki is based on MediaWiki. MediaWiki is a free software wiki package written in PHP, originally developed for Wikipedia: its very interesting combination between usability and possibilities makes it a widely used tool. One of the benefits of this is the fact that once you have learned to work with AIRWiki, you have also acquired the ability to work with Wikipedia and all other MediaWiki-based wikis.

The main source for help and information about MediaWiki are the MediaWiki help pages. One of the most useful help pages is the one describing the basic formatting syntax in MediaWiki.

Editing the Sidebar

The Sidebar is the vertical strip on the left of the text area of the AIRWiki, shown whatever page you are looking at. You can' modify its content, of course, though it's not easy to find out how. Well, simply go to Mediawiki:Sidebar and edit that page.

Embedding videos

You can embed videos from different websites (such as YouTube) inside the wiki, thanks to the MediaWiki EmbedVideo extension. If you want to embed a video inside your wiki page, check the extension documentation here or open a page already containing videos (such as the one describing the Lurch project) and check its wikitext.

Tips for Semantic MediaWiki users

To help MediaWiki users to get to grips with SMW and Semantic Forms, we set up a tutorial page. (If you are not reasonably sure of how a wiki works, it's probably better if you practice that for a while before delving into SMW...)

AIRWiki policy

The following guidelines represent decisions about the structure of AIRWiki that have been taken. You should comply with them when editing the AIRWiki.

  • All reasonably static information about the AIRLab should be published in the AIRLab website. All information which need to be modified more frequently (say: at least twice a year) should instead be put into the AIRWiki. The AIRWiki also offers the possibility of building pages which are automatically updated.
  • The AIRLab website should mention all the research areas active in AIRLab; but some of these could be absent from AIRWiki, since their researchers decided not touse it..
  • AIRWiki DOES NOT include a "Projects" page (where the projects of AIRLab are listed). Projects are listed in the pages of the relevant research area.