From a Table to Views

...

Document Properties Marker

override	false

Short Description

Short introduction on using data tables or using views on data.

Doctype

topic

hide

Name

From a Table to Views

Short Name

Parent

Parent Property

property-name	Name

hide

Audience

Name List

doctype	role
render-no-hits-as-blank	true
property	Audience
empty-as-none	true

Subject

Name List

doctype	subject
property	Subject

Sponsors

Name List

doctype	stakeholder
render-no-hits-as-blank	true
property	Sponsors

Sort Key

hide

...

Section

show-title	false
title	Description

This short introduction shows how a table of data information can be transformed into a web of documents on your Confluence wiki using the PDAC1.

Although we will show tools of the projectdoc Toolbox, what we present here can also be achieved with other tools.

Section

title	Summary

Section

title	Table of DataInformation

Suppose you need to list some data contact information about your team mates: Tina, Mike, and John.

You create a new page in Confluence and put the currently relevant information in into a table like this:

Name	E-mail	Phone
Tina	christina@example.com	-123
Mike	michael@example.com	-204
John	john@example.com	-451

Next you realize that the skype ID and mobile phone number are also relevant. There for you add new columns to your table.

Name	E-mail	Phone	Mobile	skype
Tina	christina@example.com	-123	+01 123 23451	tina.m
Mike	michael@example.com	-204	+01 123 23671	super.mickey
John	john@example.com	-451	+01 123 24656	delibunknownmycorporationme

Next you learn that this information is relevant to freelancers that are also members of your team. So you decide to state the full phone number and the full name.

Name	E-mail	Phone	Mobile	skype
Christina Meyer	christina@example.com	098 321-123	+01 123 23451	tina.m
Michael Suba	michael@example.com	098 321-204	+01 123 23671	super.mickey
John Doely	john@example.com	098 321-451	+01 123 24656	mycorporationme

Now you can add more information for a team member by adding additional columns and more team members by adding additional lines to this table.

This is quick and easy and is often fair enough. But processing this information or showing information for different contexts in different views is not easy to do.

Section

title	Additional Requirements

There are usually some use cases that you encounter dealing with this kind of information.information for some of which the tabular form put some limitations.

Here is just a short collection of a few:

Selecting on Information
1. Not all team members may need to be on the table for some users .of the address book
2. Not all users are interested or should have access to all information about a team member.
3. Users may want different views on information such as internal staff has access to the extension phone number while external freelancers have the full number.
Referencing Information
1. You can reference the whole address book of team members, but ...
2. ... users Users may want to pass a link to a team member or ...
3. ... use a reference to a team member use it in their documentation (e.g. in meeting minutes)
Adding more Information, for instance:
1. Notes on the team member, e.g. special interests or availability for the project
2. Fields of expertise
3. History of projects
4. References to topics in the wiki the team member is one of the authors

...

Selecting on information in a table can be done by filtering. Filters may reduce the amount of columns and the amount of lines.

Another way to solve the problem would be to create a page in the wiki dedicated to only one person

The alternative is single sourcing: Instead of adding lines to a table we see each line as an entity for which we create a new page. Information form these pages, single sources of truth for a particular information like the connection information for a particular team member, can be accessed and compiled in different contexts. Each representation for such a context we call view. So in different contexts you may have different views on the same information.

Section

title	Handling these Requirements

So what are the options to handle these requirements with the tabular approach and what is an alternative?

Section

title	Selecting on Information

Section

Column

width	33%

Panel

title	Page for Tina

Name	Christina Meyer
E-Mail	christina@example.com
Phone	098 321-123
Mobile	+01 123 23451
skype	tina.m

Section

title	Fields of expertise

...
...
...

Section

title	History of projects

...
...
...

Column

width	33%

Panel

title	Page for Mike

Name	Michael Suba
E-Mail	michael@example.com
Phone	098 321-204
Mobile	+01 123 23671
skype	super.mickey

Section

title	Fields of expertise

...
...
...

Section

title	History of projects

...
...
...

Column

width	33%

Panel

title	Page for John

Name	John Doely
E-Mail	john@example.com
Phone	098 321-451
Mobile	+01 123 24656
skype	mycorporationme

Section

title	Fields of expertise

...
...
...

Section

title	History of projects

...
...
...

Let's have a look at how we can engage the additional requirements we have listed above!

Section

title	Selecting on Information

Selecting on information on a table can be done by filtering. Filters may reduce the amount of columns and the amount of lines. You can have controls where you type and automatically prune the table.

How can we approach this requirement using single sourcing?

The page holding the contact information for a person can be based on a blueprint to make it easier to add new members and provide the information that is most relevant to the team. A blueprint is therefore a tool to support authors to compile similar information in a similar way and it shows the author which information is typically expected on such a page. This guidance is implicit with the table approach. The format and layout is defined by the order and number of columns of the table.

Note Box

There is a doctype for Person that provides a blueprint with common information one expects to find in an address book.

This doctype is part of the Core Doctypes, a free doctype add-on for the projectdoc Toolbox.

Information that should only be visible to team members in having certain roles could be added on separate pages. The access to these pages is restricted by the wikis access control and are transcluded on the public page. Therefore the transclusion will only happen if the user has sufficient access to the restricted information. This feature is difficult to master with a table approach. You would need to have a tool that allows to grab information from an alternative location and render it into the page at request time. This is what transclusion does with Confluence tools.

You can add information in different formats. For instance the telephone number in form of its extension and in full format. You may also define different type of team members where different types of information is relevant.

Tip Box
Not shown here, but you can use the Display Document Property Ref Macro to render a property value and append or prepend additional information. This way you could have a property Phone Extension and a property Phone Number where the Phone number reuses the extension information. If the extension for a team member changes, the update is only needed in one place.

To automatically render the information of all team members in tabular form, use the Display Table Macro. This macro allows you to query for team members with certain properties and select to show only the personal information that is relevant to your use case. That is you have the information of team members in one place and then have multiple views on this information by using the Display Table Macro.

With the table approach this table is automatically provided. But since it is hard wired, there is only one view on that table (with some considerable variations if you add code for filtering and sorting to that table).

Section

title	Referencing Information

To reference a single member you would need to reference a single line in the table. This can be done with a named anchor, but this is usually troublesome.

If you have each team member on a separate page, the URL to that page references the team member. Via this URL all information about the team member that is relevant to the team is accessible. This URL can be easily added to other documents to create a web of information.

Since the URL points to a page in Confluence, changes to the name of the page will automatically update all references. This is not the case for named anchors. If the named anchor changed, the references are not updated automatically.

Section

title	Adding more Information

In tabular form it is often unwieldly unwieldy to have short information like a name in the same line as a list of special interestes interests or other multi-line notes. It makes the table less readable since all cells in a row need to have the same height. And although the height of rows may differ, a table with rows of the same height is usually more pleasant to read.

If the information for a team member is on a separate page, any information can be added. The projectdoc Toolbox distinguishes between Document Properties, which are typical single line and used to filter on team members for a search result and Document Sections which comprise multiple blocks like paragraphs or tables. Since each view selects on information, the information can be rendered in the most appropriate layout.

Having defined fields of expertise on could also collect names of team members who are provicient proficient in that field. That is by clicking on an expertise on a team member page, the user would have access to a list of team members that also have knowledge in that area.

If you document projects and link to the people who are part of the team, a history of projects can be automaticall automatically rendered on the team member pages. The same is true for topics the team members are authors of if they are mentioned as as authors on the topic page.

The page for contact information of a team member becomes a portal to related information by itself.

Section

title	Conclusion

Having each information on a separate page makes it referencablereferable. Think of having a separate page for each line of the original table. You can add any number of views on this information and some information will be collected automatically. There are We have discussed briefly the many advantages to have a single source for each piece of information.

On the other hand compiling a table with a couple of columns is very easy and can be conducted in an ad-hoc manner. Single sourcing requires some form of planning as to decide how such a page should look like by defining a blueprint (instead of . This is in contrast to instantly guessing the relevant columns )of a table. For many people it is often more cumbersome to create a new page than to add a new line to an existing table.

So – as often – there is no right or wrong. Choose
And therefore – as always – choose the tools that are most appropriate to your task at hand!

Section

title	Prerequisites

...

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 7

New Version Current

Key

About

Keep up-to-date!

Powered by