Help:Contents

From Referata

Welcome to Referata. Referata is a host for semantic wikis; those are wikis that contain data, and not just text - data that can be queried, aggregated, mapped, exported, etc. In other words, you can think of a semantic wiki as a collaborative database.

The majority of this help page is intended for site administrator, as opposed to users. If you're a regular user, adding and editing information on a Referata wiki might even be easier than on a regular wiki, since there tends to be less free text and more structured data; often there will even be forms to help you with the editing.

Contents 1 Application-specific help 2 Administrator pages 2.1 The "Site settings" page 2.2 The "Admin links" page 3 Setting up a Referata site 3.1 An example 3.1.1 Book Example 3.1.2 Author Example 3.2 Templates 3.2.1 Book Templates 3.2.2 Author Templates 3.3 Creating Forms 3.4 Creating Categories

[edit] Application-specific help

Referata uses the wiki application called MediaWiki, along with some of its extensions.

For an overview of the MediaWiki application, see here. For help with MediaWiki editing, see the basic editing guide and the advanced editing guide.

For help with the individuals extensions used in Referata, see their respective help pages:

Semantic MediaWiki, Semantic Result Formats, Semantic Forms, Semantic Drilldown, Semantic Google Maps, Widgets, Header Tabs, Replace Text.

Also check out the Semantic MediaWiki quick reference guide, available both as an image and a PDF file.

For a complete list of extensions used in Referata, see Special:Version.

[edit] Administrator pages

If you are the administrator, or one of the administrators, of a Referata site, you will see two additional links at the top of any page on that site: "Site settings" and "Admin links". Each of these will take you to a special page that provides administrative functions.

[edit] The "Site settings" page

This page, located at /Special:SiteSettings, allows you to set various aspects of the site, like its name, language, default skin, logo etc. It also lets you set various privacy levels: whether the site is readable by everyone or just by registered users; whether anyone can register, or registration is by invitation only; and whether any can edit pages, or just users, or just site administrators. It also has Semantic MediaWiki-related settings, like whether the "semantic infobox" should be shown at the bottom of all pages. Finally, it also lets you upgrade a site, using a PayPal subscription.

[edit] The "Admin links" page

This page, located at /Special:AdminLinks, provides links for creating and viewing properties, templates, categories, forms and drilldown filters, in addition to other important miscellaneous links, including:

• a link to edit the sidebar for your wiki; for more help with this, see Editing the sidebar
• a link to edit the global CSS file, to make style changes
• a link to change the name of the main page for your wiki (which defaults to "Main Page")
• a "Create user" link to add new users (this is especially important if you have a private wiki - it is the only way to add users to your site)
• links for managing existing users, including setting their permissions
• a "Replace text" link, that brings you to a page where you can do a global find-and-replace on text in your wiki

[edit] Setting up a Referata site

Once your Referata site is up, it's time to create the structures to hold, display and enable adding and editing of your data; thankfully all of this can be done simply by creating various wiki pages. You can take the following steps:

• Figure out your data structure. What types of pages will the site have? What data will be contained on each one? You can change all of this around later, but it's good to have a starting plan.

• Create properties. The basic building blocks of any semantic site are the connections between data, which are known as properties. A property is used to specify a single piece of information about the topic of this page. Every property used should be defined on its own page, in the "Property:" namespace, on your wiki. The easiest way to do that is using the 'Special:CreateProperty' page, which, for your site, you can reach from your "SMW Panel" page.

• Create templates. A template sets the display of the data on a page, holds the markup to turn the data into actual semantic information, aggregates relevant data from other pages, and (often) defines the page as being of a certain category, and thus of a certain page type. There will generally be one template per page type, although sometimes a single page type will have more than one template, especially if certain fields can have more than one value. The easiest way to create templates is using the 'Special:CreateTemplate' page, which, again, you can reach from the "SMW Panel" page.

• Create forms. Now you can create forms to allow users to easily add and edit pages of various types. There should be one form per page type; a form should populate the template or templates that this page type contains. As before, there's a special page to create new forms: 'Special:CreateForm'; as before, you can reach it from the "SMW Panel" page.

• Enable links to forms. Once you have the forms in place, you need to have ways for the users to access them. These include: adding links to add data in the sidebar and elsewhere; enabling each page that's editable with a form to have an 'edit with form' tab at the top; and having red-links to nonexistent pages point to a form for creating them.

• Add aggregation. You can add aggregation to different templates - displaying all the pages that have the same relationship to a page or a set of values. The 'Special:CreateTemplate' page helps with adding aggregation, but you can always add more. See the inline queries page in the SMW documentation for more information on how to do this.

• Customize. Once the structure is in place, you can customize all you want - changing the look-and-feel of the entire wiki, of the various templates, and of the forms, and adding and changing fields. You should also add data to the site (using your new forms), to make sure that everything is displaying the way you would want it to.

For more help on data structure issues, see the Semantic Forms documentation; they are all explained further there.

Once you have some data on your site, you can also help users find data more easily:

• Create filters. Your site will have an automatic drilldown page at 'Special:BrowseData'. By default, this page shows a list of all categories on the site, their subcategories, and the pages they each contain. However, you can add additional filters, to allow users to drill down on various properties of the pages in each category, like country, year, genre, theme, etc. The easiest way to create filters is to use the 'Special:CreateFilter' page.

For more help on the drilldown, see the Semantic Drilldown documentation.

[edit] An example

Let's go through a specific example of setting up a wiki from scratch. Let's say that you want to create a wiki that shows all the books you have at home. We'll go through the steps previously specified.

Figure out the data structure. You want two kinds of pages on your wiki: one for books, and one for authors. You decide that each book page should hold a title, an author name, a genre (or genres), a year of publication, and a number of pages; and that each author page should hold the author name, their country of origin, and a list of all the books they have written that are in your library.

Create properties. Properties are the basic building blocks of a semantic wiki - they hold a single value for a page.

[edit] Book Example

For books, we want to represent a book's title, author(s), genre(s), year of publication, and number of pages. That is five fields, also there is no need to create a property for the title, since the title of each page representing a book will be the title of that book. That leaves four fields, each of which require a defined property:

• Author - using the "Create a property" page, you create a property called "Was written by", of type "Page" (since each author will have his/her own page).
• Genre - you create a property called "Has genre", of type "String", and give it the following allowed values: "Art, Cookbook, Fiction, History, Poetry, Science".
• Year of publication - you create a property called "Was published in year", of type "Number".
• Number of pages - you create a property called "Has number of pages", of type "Number".

[edit] Author Example

For author pages, you only need to create one more property:

• Country of origin - you create a property called "Is from country", of type "String".

[edit] Templates

You need to create two templates, one for books and one for authors:

[edit] Book Templates

Using the "Create a template" page, you create a template called "Book", and set it to define the category "Books". You add to it four fields, and for each field you specify three values: its field name in the template source code, its display label on each page, and the semantic field it populates. For the first field, you set the field name to be "Author", the label to be "Author" and the semantic field to be "Was written by"; for the second field, you set the three values to be "Genre", "Genre" and "Has genre"; for the third, you set the values to be "Year", "Year of publication" and "Was published in year"; and for the fourth field, you set them to be "Number of pages", "Number of pages" and "Has number of pages". For the "Genre" field, you also check the box saying that the field can hold a list of values, since you want to be able to select more than one genre for a given book.

[edit] Author Templates

Using the "Create a template" page, you create a template called "Author", and set it to define the category "Authors". You add to it a field for which you set the three values to be "Country", "Country of origin" and "Is from country". For this template, you also fill out the "aggregation" fields in the form, since you want each author page to list all the books the author has written. Under "Semantic property", you select "Was written by", and for "Title for list" you put "Books by this author".

[edit] Creating Forms

You need to create two forms, one for books and one for authors:

• Books - using the "Create a form" page, you make a form called "Book", and add to it the template "Book". You do not do any further customizations on this form, but just save the form once you have created it.
• Authors - using the "Create a form" page, you make a form called "Author", and add to it the template "Author". As before, you do not do any further customizations - you just save the page.

[edit] Creating Categories

You need to create two categories, one for books and one for authors; you have already specified these categories' names before:

• Books - using the "Create a category" page, you make a category called "Books", and give it the default form "Book".
• Authors - using the "Create a category" page, you make a category called "Authors", and give it the default form "Author".

Enable links to forms. You add the text "This property uses the form [[Has default form::Form:Author]]." to the "Was written by" property's page.

Add data. Using the new "Book" form, you create pages for some books; you check to make sure that both the form and the resulting pages look alright. Each book page will now have a red link to its author, that should point to the "Author" form for adding that author (you may need to refresh the page for the right link to show up). You can then add a few authors, either through these links or on the form page directly, to make sure that this setup works correctly too. Each created author's page should show a list of the books you've saved that have that person as the author.

Add links on sidebar and elsewhere. Your structures are now all set up, and you can add links to the sidebar for easy adding and viewing. You can add links to the "Book" and "Author" forms to make it easy to add new ones, and links to the "Books" and "Authors" categories to be able to see the full list of either one at a glance. See Help:Editing the sidebar for how to do this. You can also add these links to the main page and elsewhere.

Customize. You edit the form and template pages to make them more in look nicer, more in line with what you want the overall look of your site to be, and more informative.

Create filters. Using the "Create a filter" page, you create new filters to improve the drilldown in the "View data" page:

• Books - you create four new filters:
  • "Author" - this filter covers the property "Was written by", and gets its values from the category "Authors".
  • "Genre" - this filter covers the property "Has genre", and gets its values from that property's enumerated values.
  • "Year" - this filter covers the property "Was published in year", and uses the time period "Year" for its values.
  • "Number of pages" - this filter covers the property "Has number of pages", and you specify the following values for it: "< 100", "101-200", "201-400", and "> 400".

You then add these four filters to the "Books" category, using the "Has filter" property.

• Authors - you create one new filter:
  • "Country" - this filter covers the property "Is from country", and you specify for it the values of whatever countries you want.

You then add this filter to the "Authors" category, using the "Has filter" property.