Working With Data Part 1
In this tutorial, you will:
- Define a named item
- Create a view
- Add the view to a page
- Use the view.
To follow this tutorial, you should have completed the previous tutorial Creating and Editing Pages. When you have completed this tutorial, you will have have an initial understanding of how to use views to work with data. You can deepen that understanding by following the next tutorial: Working With Data Part 2.
Define a Named Item
1. Items represent things and relationships. You can define named items to represent particular things or relationships that are important for your application.
2. We'll start by defining a named item to use in the categories view, to represent the relation between a category and its name. It will be used as a verb in the categories view.
3. Make sure you are logged in and have home:admin role. Navigate to your home source. In it's Context section, click the Items link.
4. The items page lists the named items on the home source. You will see one defined to start with, the item representing your main home page.
5. Click the add button, and enter the name notecategoryHasName. You could change the item's access levels, but it is easiest to leave them as public read and home:admin write. You don't want anyone else to change the item, but there's no harm in letting everyone see it. There are other, better ways to control access to your note categories than restricting read access to the notecategoryHasName verb.
6. When you click the proceed button, you will see the new item listed with its numeric identifier. (Don't worry if this is not the same as the one shown here, there could be various reasons why a different numeric identifier is assigned to the item on your system.).
Create the Categories View
1. Views enable you to create, read, update and delete data. The categories view is a simple view that enables you to create, read, update and delete categories that notes can have.
2. Views are members of workspaces. Create a views workspace in your home source to hold the categories view and the notes view, which you will create later.
3. In the views workspace, add a member categories with type View.
4. When you have clicked the proceed button and returned to the views workspace, click the categories link to go to the new view.
5. You will see a new view page, with headings for Description, Unknowns, Constraints, Columns, and Characteristics.
6. Click the page edit button. Buttons will appear to enable you to define the view.
7. Click the Description add button, enter the description "The categories that notes can have" and click the proceed button.
8. The view will have two unknowns, CATEGORY and CATEGORYNAME.
9. Click the add button in the Unknowns section and define the CATEGORY unknown. A value of this unknown is an item that represents a category. Define it as follows.
- Name: CATEGORY (you can pick any name - for example x or y - but it helps to have a name that is meaningful)
- Type: Itemid (this is the basic item type - if you wanted to specify an item of this type you could do so by giving its identifier)
- Description: "A category that a note can have" (this is useful documentation so that others can understand what the view is about)
- Editable: false (you won't be able to use the view to change the item representing a category)
- Priority: 0 (when data obtained by the view is sorted, the CATEGORY item has zero sort priority)
- Reverse Sort Order: false (when data obtained by the view is sorted, the CATEGORY item values are sorted in ascending order)
10. Click the proceed button. You will see a red warning message. Don't worry about this, it will disappear when you have defined the constraint linking CATEGORY and CATEGORYNAME.
11. Click the add button in the Unknowns section again and define the CATEGORYNAME unknown. A value of this unknown is a text string that is the name of a category. Define it as follows.
- Name: CATEGORYNAME
- Type: String
- Description: "The name of the category"
- Editable: true (you will be able to use the view to set and change category names)
- Priority: 1 (when data obtained by the view is sorted, the CATEGORYNAME string has sort priority 1. Because it has the highest priority, the categories are sorted by their names.)
- Reverse Sort Order: false (the names are sorted in ascending order)
12. Click the proceed button. You will now see two red warning messages. They are reminding you that each unknown should appear in a constraint - or there is no point in defining it. Click the add button in the Constraints section to add a constraint linking the CATEGORY and CATEGORYNAME unknowns.
13. A constraint has a subject, a verb, and an object. Each of these can be given - meaning that you know its value - or unknown - meaning that you don't. A view shows all the possible combinations of values of unknowns satisfying the constraints, from the data in the connected sources that you can see given your role. This view shows all the categories with their names.
- Enter Unknown as the subject type, and select CATEGORY as the subject.
- Enter Named Item as the verb type. You can then select from all visible named items in connected sources. Select the one that you defined earlier - home:notecategoryHasName.
- Enter Unknown as the object type, and select CATEGORYNAME as the object.
14. Click the proceed button. You will see that the constraint has been defined, and the warnings will have gone.
15. The view data will be displayed in a table, with the rows sorted according to the priorities and sort orders that you set for the unknowns. You now define the columns of the table. For this view, there is only one column: the category name. Click the add button in the Columns section, then set the following values:
- Header: leave blank (as there is only one column, and it is obvious what it is, it doesn't need a header)
- Unknown: CATEGORYNAME
- Action: None (the only possibility).
16. Click the proceed button. Finally, click the add button in the Categories section to set some important attributes of the view. These are:
- Read Level: public (there is normally no problem with anyone seeing a view definition, and making it public means that it can be used at all access levels)
- Write Level: home:admin (you don't want anyone else to change the view)
- Key: CATEGORY (when rows are added to a displayed view that has a key, new items are created for the key values - so new named categories will be created when this view is displayed and rows are added)
- Key Selector: CATEGORYNAME (this enables the view to be used to select categories by name in other views - you will see how this works later)
- Use default access levels: true (when rows are added, the items created will have the default access levels)
- User can add rows: true (this means you can add rows and create new categories).
17. Click the proceed button. The view definition is complete.
Add the Categories View to a Page
1. In the Creating and Editing Pages tutorial, you created a pages workspace and a categories page in that workspace. Navigate to that categories page.
2. Make sure you are logged in with home:admin role, and click the page's edit button.
3. Click the New Block add button.
4. Type "Categories" and give it style Header 1, then go to a new line.
5. Click the view button.
6. Select the home:views workspace and then the categories view. The categories view will be added to the page.
7. By default, the view will just display data. To be able to use it to change data, you need to set its user write level. Once this is done, users with roles superior to that write level will be able to use the view to change data.
8. Click on the categories view. A Select user write level pop-up will appear. Click it. A list of access levels will be shown.
9. Select the home:admin level. (Ignore the "Styling views is not allowed" message.) This sets the view's user write level to home:admin.
10. Click the proceed button. (The view will be blank as it has no headers and no data.)
Use the Categories View
1. Click the view page button. An add button will appear for the categories view.
2. Click the categories view add button.
3. Enter "Undefined" as a category name (this is a good catch-all category for notes that are hard to categorize).
4. Click the proceed button.
5. Add more categories in the same way:
- Action: for notes that you make about things you will do
- Discussion: for notes that you make about meeting discussions
- People: for notes that you make about people.