Usage Instructions

Creating a Context

ConceptCloud creates tag clouds by extracting information directly from an SVN/GIT repository.
1: Enter the URL of the repository you would like to analyse
2: If this is a private repository enter the user credentials. Otherwise leave these fields blank to anonymously access a public repository.
3: If you would like to restrict the commits analysed to those that have only occured since the last commit of a developer then enter the developer's username. Otherwise leave this field blank.
4: Indicate whether this is a Git or SVN repository. ConceptCloud will not be able to access the repositroy if this information is incorrect.
5: Select the type of context you would like to create. The default context type is the revision-based context.

Tag Cloud Viewer Customisations

After successfully creating a context you will be redirected to the tag cloud viewer. There are various customisations that can be performed on the tag cloud viewer
1: Collapse the viewer menu (buttons 2-12)
2: Add an additional category to the tag cloud. Categories are only available on this menu if they are not currently displayed in the tag cloud.
3: Remove a category from the tag cloud. Categories are only displayed on this menu if they are currently displayed in the tag cloud.
4: Restrict the viewer to showing only one category.
5: Zoom in to make all tags in the viewer larger
6: Zoom out to make all tags in the viewer smaller
7: Limit the number of tags shown to the largest 100, 200 or 500.
8: Show only tags that occur more than the specified amount of times.
9: Drag this viewer
10: Minimise this viewer
11: Create an image of the current tag cloud
12: Close this viewer
13: Resize this viewer
Hover over tag: to see the count (number of occurences of this tag) and category of the tag.

Selecting Tags

Tags in the cloud can be clicked to be selected. If a selected tag is clicked it will be deselected.
1: Selected tags will appear in red in the updated tag cloud
2: The number of remaining in the cloud is indicated here. This is the number of objects that have the selected tag as attribute.
3: The minimum and maximum font sizes used for the tags can be changed here.
4: A list of selected tags is shown here. Tags can also be de-selected by selecting these links.

Examples

To create an authors by year view
1: Right click on the desired year tag and select "Open Viewer wth this Tag Selection"
2: Use button 4 and restrict the cloud to showing only authors
3: Repeat this process for other desirec years
4: Rearrang the viewers by using the drag button (button 9)

ConSL: Concept Cloud Scripting Language

Description

ConSL is a domain specific language that allows the user to define templates for views that are opened and arrange views. The language allows users to create start up scripts that may be run from the landing page of concept cloud or from the tag views.

Running a script

ConSL scripts may be run in two different ways:
1: Using the Upload Script option in the home screen when loading a context from a file
2: Using the Load ConSL Script option in the from the tag view screen after a context has been loaded

Defintions

Defintion statements specify what view templates will be used and what the content of the view template will be. They are used as follows:

define view name as view type {
attribute = value;
}

Users are allowed to assign values to more than one attribute. As example if one wished to define a view where the displayed categories were the year and author, and one wished to limit the number of tags in the view to 10, the following code would be used.

define example_view as tag_view {
category = 'year, author';;
tag_number_limit = 10;
}

Users have access to the following attributes when defining a view. 1: category: This attribute specifies the category to be displayed in the view. For more than one category to be displayed a comma separated list must be used as in the example above. If this attribute is not assigned a value all the categories will be displayed. 2: tag_number_limit: This attribute limits the number of tags displayed in a view. Tags are ordered in descending order by their frequency so in the above example only the top 10 tags with the highest frequency will be displayed. 3: tag_count_limit: When this tag is assigned a value only the tags that occur with a frequency higher than the assigned value will be displayed in the view. 4: sticky_tag_name: This attribute specifies the title that a view has when it is created.

Opening views

Views may be opened in two different ways when using ConSL. The following is the default open statement in ConSL.

open view name(tag name);

If two tags share the same name then one may specify the category of the tag that must be opened as follows.

open view name(tag name) from category;

It is important to note that if a view name has not been defined it cannot be opened as there is no template specification for it. Views may also be opened in group using the following for-loop construct.

for variable name in category name {
open statement;
}

If one wishes to constrain the views that are opened in any way the above for-loop may be amended to reflect the constraints that should be applied.

for variable name in category name where boolean expression {
open statement;
}

As an example consider the definition of example_view above, the following statement will open a view with the example_view template for each year after 2005.

for t in 'year' where 'tags[t].name > "2005"'{
  open example_view(t) from 'year';
}

The boolean expression takes the form of an ordinary JavaScript expression where the user must use the variable tag[variable name] which has the following fields: 1: name: The name of the tag
2: count: The frequency of the tag
3: category: The category of the tag

Layout

A layout specification allows users to specify the layout of views that were created from the same definition. A layout specification also allows users to change any visual aspect of the views. They take the following form:

layout view name {
attribute = value;
}

Users may have as many assignments as they wish. As an example if one wished to arrange the views created by the above example in alphabetical order and also only have 3 views per row, the following code will be required.

layout example_view {
&esnp;views_in_a_row = 3;
order = ascending>; }

Users have access to the following attributes when defining a view:
1: views_in_a_row: This adjusts the width of the views so that the specified number fit in each row. It can be any positive integer.
2: order: This arranges the group of views in ascending or descending alphabetical order. It has values 'ascending' or 'descending'.
3: width: This specifies the width of each view in the group. It has a value which is a string specifying the HTML value for a width eg. '100px' or '50%'.
4: height: This specifies the height of each view in the group. Its values have the same form as for the width attribute.
5: menu: This specifies whether the menus in the views are visible or not. It has values 'visible' or 'hidden'. If this attribute is not set the menus are visible.

Complete Example

As a complete example consider the following script which produces the output below:


define author_view as tag_view {
	category = 'author';
	tag_number_limit = 1;
}

define file_view as tag_view {
	category = 'year';
	tag_number_limit = 5;
}

define file_author_view as tag_view {
	category = 'author';
	tag_number_limit = 3;
}

for some_tag in 'filename' 
    where 'tags[some_tag].count > 120' {
	open file_view(some_tag);
	open file_author_view(some_tag);
}

for some_tag in 'year' {
	open author_view(some_tag);
}

layout author_view {
	order = 'ascending';
	height = '75px';
	views_in_a_row = 3;
	menu = 'hidden';
}

layout file_view {
	order = 'ascending';
	height = '120px';
	views_in_a_row = 5;
	menu = 'hidden';
}

layout file_author_view {
	order = 'ascending';
	height = '150px';
	views_in_a_row = 5;
	menu = 'hidden';
}