SportTracks Plugins by Old Man Biking

Activity Documentation - Manual

Activity Detail Pages
1. Activity Documentation Detail Page
2. Custom Fields Detail Page
Components
Reports
1. Saving and Loading a Report scheme
Graphical Reports
Templates
'Edit activity' Actions
'Export' Actions
The Find and Replace Window
1. Regular Expressions
Settings Pages
1. Activity Documentation Plugin
2. Custom Fields
Appendix: Placeholders for the "Custom HTML Component"
Appendix: Goodies for Advanced Users

Activity Detail Pages

Activity Documentation Detail Page

This page hosts the documentation editor. You use it to create, modify and view the documentation of your activities.
The editor should be mostly self-explanatory. Have a look at the Features and Getting Started pages and you should be ready to use it.

The following sections give a brief overview and then focus on features that are somewhat more advanced and might need some explanations:

sending documentation via email
uploading of your documentation to a web server
components
templates

Text Formatting

The plugin provides all text formatting capabilities that you know from rich text or HTML editors.

You can:

insert several levels of headings
change the font size
format text in bold, italics, underlined or any combination of these styles
insert lists, both unordered ("bullet list") and ordered
indent text
justify text: left, center, right or full
insert horizontal rulers as well as page breaks for printing

Besides these text formatting capabilities, you can:

cut, copy and paste text (within the plugin and to and from other applications)
Note: Ctrl-X, Ctrl-C and Ctrl-V as well as Ctrl-A for "select all" can be used as well
search for text (Ctrl-F)
undo (Ctrl-Z) and redo (Ctrl-Y) your last changes
create hyperlinks to local files as well as resources on the internet
insert images, both local files and images from the web
insert tables with arbitrary numbers of rows and columns

Context Menu

When you click into the editor pane with the right mouse button, a context menu opens. Depending on the items under the mouse cursor, the context menu provides different functions to manipulate the particular item.

Navigation

When you browse from activity to activity, you can easily navigate back to previously visited activities and navigate forward again.

Printing

The plugin supports printing.
Simply click on

and you can:

setup the page layout (paper size and orientation, headers and footers, margins)
view a print preview and change the zoom level for printout
and of course print

Sending your Documentation to Friends or your Trainer via Email

Click on

and the "Send as email" action will be triggered. Please read on here.

Uploading your Documentation to your Homepage or Webserver

Click on

and the "Upload activity documentation" action will be triggered. Please read on here.

Saving your Documentation to your Local Disk

Click on

and the "Save documentation to local disk" action will be triggered. Please read on here.

Components and Templates

The most powerful features of this plugin, however, are:

Components
Components allow you to add e.g. an activity summary with one mouse click
There is a set of prefabricated components for several aspects of the activity. See further down for details.
Templates
Templates allow you to save the documentation of an activity as a template and create documentations for other activities based on this template.
In combination with components you can create a full documentation for an activity with just one mouse click.
See further down for details.

Help

The editor provides a few helpful features:

elements in the editor's tool bar are disabled (greyed out) when they cannot be used in the current situation
all elements have tool tips to help you understand what they do
many functions can be accessed through keyboard shortcuts (Ctrl plus another key)
a help button takes you to the online manual
note that most dialog forms of this plugin provide a "?" help button in the upper right as well
click on the icon and an info panel pops up that tells you,
- when and from which template the documentation was created,
- when it was modified the last time
- and which space it occupies in the saved logbook file

Custom Fields Detail Page

Once you've defined a set of custom fields of your liking (you do this on the "Custom Fields" settings page), you can enter values for "your" fields on this page.
Note: simply click on the

button in the upper right to open he settings page.

These values appear in the "Summary" component on the "Activity Documentation" detail page, and they can be used in "Report" components.

Components

Documentation components are pre-fabricated units, provided by this plugin or by other plugins that allow you to add (mostly activity-related) pieces of documentation with just one button click.

For now there are components for:

an "Activity name" that can e.g. be used in headings
"Athlete" information with infos concerning the athlete's physical condition on this particular day
a "Custom HTML component" that advanced users can insert to embed hand crafted HTML snippets into the documentation;
placeholders in the HTML snippet can be used to insert activity attributes (start time, distance, ...) into your HTML snippet;
see this appendix for a list of placeholders that you can use
an "Equipment" component with information on the equipment used in this activity
a "Map" component that displays the acitivity's GPS track on an arbitrary map
a "Splits" component
a "Stopped Times" component that shows segments of your activity with a speed/pace below the "stopped" threshold of the activity's category
a "Summary" component with the major indicators of the activity
a "Table of contents" of all headings that you've created in the current documentation
"Tracks" for ascent/descent, cadence, elevation, grade, heart rate, power and speed/pace
power analysis data (you must have the Power Analysis plugin installed for these)
Reports ? Report for tabular reports that resemble the SportTracks "Reports" view ;
please see here for details
Reports ? Graphical Report for a graphical report (bar/line charts) like the lower part of the SportTracks "Reports" view ;
please see here for details

When you hover the mouse over a component in the menu, a tooltip pops up which gives you a brief explanation for this component and tells you which plugin provides this component.

When you select a component, a dialog may pop up which allows you to configure parameters of this component (e.g. if charts shall be per-time or per-distance).
You can as well change these settings later: right click on a component and select "Edit" from the context menu.

This is an example how the Summary Component and the Split Component look like:

A few notes on components:

The contents of a component is read-only, you cannot edit it. It's generated by the plugin from activity data.
A component is marked as such by a red border on the editor pane - this border will not appear on print outs or when you email or upload a documentation.
Components are rendered on-the-fly when you open the documentation. Hence, components always reflect the current state of your activity.
E.g. when you manually add splits to an activity in SportTracks after you created your documentation, these splits will appear in your documentation, when you open it the next time or click on the button.
Other plugin authors can easily add components. I provide open interfaces which make it trivial to add a component to the Activity Documentation plugin. When you think that your favourite plugin could add value to your plugin documentation, approach its author.

Reports

Reports are created with the "Report" component. It's such a powerful component that it deserves a chapter of its own in this manual.
While most other components provide information for one activity only, the "Reports" component spans many, possibly all, activities in your logbook. It resembles the

"Reports" view of SportTracks.

There is just one Report component for now, but it offers nearly endless possibilities. Much more than can be layed out in a brief manual.

This is the configuration dialog for a report, which pops up when you insert a report.

First of all, you select a date range for the report.
This example selects all activities in the current month of the activity.
You can select weeks, quarters and years as well or specify a custom date range.
You can narrow down the selection so that only activities of a given category will be reported, "Biking" in this example.

You can then select the columns of the report. Click on this button and select the columns and their order.
There are about 70 different attributes that you can select.
How shall your report be sorted. When you select "don't sort", the activities will be listed according to their start time.
You can use ascending or descending sort order and you can decide if all activities shall be displayed or just the top or bottom x% or x items.
Last but not least you can select to create rollups: weekly, monthly, quarterly or yearly. Rollups per date range can only be selected, when you don't sort.
You can even choose to display only rollups, e.g. for a report showing your weekly training times and distances.

This page shows just a few reports that can be created.

Saving and Loading a Report scheme

Like all other components, the Report component edit dialog remembers the last settings that you used. So when you create a new report, it will have the very same date range, category, column selections, sorting and rollups like your last one.
But what, if you want to reuse such a report scheme later? The "Saved reports" area in the lower part of the Report edit dialog provides 3 buttons to "Save" the current report scheme, to "Load" a previously saved report scheme and to delete a saved report scheme.

Graphical Reports

Graphical reports are very much like the tabular ones, but display a graphical representation (bar chart, line charts) of the selected data.

This is the configuration dialog for a graphical report:

selection of date range, category and columns are exactly like the ones for tabular reports

"Display by" allows you to select a criterium for the x axis; you can either have a value for every single activity, or you can have one aggregated value for e.g. "Day of week" or several other criteria
selecting "show table" adds a tabular representation to the graphic
you can of couse select width and hight of the chart
The "Saved reports" area is the very same as for tabular reports

Templates

Using Templates
Whenever you create a new activity documentation you do this by selecting a template. So every documentation is created from a template.

Note: When you click on the left part of the

button, you'll get a documentation created from the last template that you have previously used. Clicking on the down arrow opens the template selection menu.

There are two kinds of templates:

Standard Templates - templates that are shipped with the plugin
E.g. the simplest of all templates: "Empty page"
Custom Templates - templates that you can easily create yourself

Your new activity documentation will be a copy of the template that you selected. So you can prepare your own custom templates with the contents that you like to see in your documentation.
But you don't want that every activity's documentation is exactly alike, right?
This is where the power of components drops in. Remember that components are always rendered on-the-fly, when the activity documentation is opened?
So just add an "Activity Summary" and a "Map" component to your template and the newly created activity documentation will show the summary and the map of this particular activity. Easy, isn't it?

Creating Templates
Creating a template is straightforward:

Edit an activity documentation and add the desired components, text and formatting to it
Save it as a template with a click on the button and chose the desired template name

The next time you create a new activity documentation, your new template will appear in the "Custom Templates" sub-menu.

Deleting Custom Templates
Right click on a template in the "New" menu. A "Delete" entry pops up that lets you delete the template.

Modifying Templates
A simple process:

create a new document from the template that you want to modify
change the document
save it as a template again and enter the original template name

After asking you for confirmation, the plugin will save the modified contents.

Note: When you have created generic templates that could be used by others as well, I can add them to the set of standard templates. Please send me a personal message ("PM") in the SportTracks forum.

'Edit activity' Actions

Add Activity Documentation (template name)

This action is available whenever you have selected one or many activities that don't have a documentation yet.
It adds a new documentation to all selected activities that don't have a documentation. It does not overwrite existing documentations.
The new documentation is created from the last template that you've used in the documentation editor. Its name is displayed in the action menu entry.

Delete Activity Documentation

This action is available whenever you have selected one or many adtivities with an activity documentation.
It deletes the documenation from all selected activities. Before doing so it asks you a last time if you're sure.
Note that the documentation is part of the logbook, so when you delete a documentation the deletion will no sooner be persisted than you save the logbook - very much like all other things that you do in SportTracks.

Update Documentation

As you've learned before, every documentation is created from a template. A "new born" documentation is an exact copy of the template it was created from. Of course you can then modify the activity documentation if you like so.
If you don't modify a documentation after it has been born, it keeps its 1:1 relationship to its template. So, when you change the template, the documentation can be updated to reflect the change in the template.
And this is exactly what this action is for: update unchanged activities to a new version of the template they were created from.

Find and Replace

This action allows you to search for text and replace the found text with a given string.
The action opens the "Find and Replace" window. Please read on here.

'Export' Actions

Print Activity Documentation *

This action is only available when you have selected one or many activities with an activity documentation.
Sends the documentation of the selected activities to the printer and prints a cover sheet as well.

Save Documentation to Local Disk *

This action is only available when you have selected one or many activities with an activity documentation.
Prompts you for a folder name and saves the documentations of the selected activities to this folder.

Create MS Outlook Appointment *

This action is only available, when Microsoft Outlook is installed on your PC.
It creates an appointment item (calendar entry) for this activity. The body of this item is filled with information like the one you find in component "Summary". The settings page of the plugin lets you choose, which Outlook category shall be assigned to the item and if the appointment item shall be opened after creation.

Send as Email *

This action is only available when you have selected exactly one activity with an activity documentation.
It sends out the documentation of the activity as an email. Depending on your plugin settings, the email is either sent through your local Microsoft Outlook client (if installed) or via direct access to your email server ("SMTP"). For SMTP you need to know the credentials of your email account: mailserver, your email address, mail account user name and password.

When your credentials are available, the plugin will open a dialog to let you enter the recipients of the email:

Enter the recipients. You can either type the address or select among the addresses that you've used recently. Change the prefilled subject if necessary and click on "Send".
When Microsoft Outlook is installed on your PC, you can check "use MS Outlook contacts" which puts your Outlook contacts into the email address selection lists.

The dialog closes immediately, but it might take a while for your email to be sent (depending on the complexity of the documentation and the speed of your internet access).

When you send the mail via Outlook, it will be opened in Outlook so that you can modify it as you like, before clicking on "Send" in MS Outlook to finally send it.

Upload Activity Documentation *

This action is available whenever you have selected one or many activities which have an activity documentation.
It uploads the documentation to your home page or your webserver via FTP. All you need to know are the credentials of your web space account: host name, your user name and your password.

If necessary, the plugin will take you to the plugin's settings page to let you enter the credentials.

When your credentials are available, the plugin will prepare the documentation for upload and ask you for confirmation. Upload will start no sooner than you click on "OK".

The plugin will then ask you for the password of your FTP account. It will remember the password until you close ST. For security reasons the password will however not be saved when you close ST. Yes, I know that this is not purely comfortable, but according to my humble opinion security comes first.

It will start uploading and open a status window that will report progress while the files of your documentation are being uploaded.

Upload takes place in parallel while you continue working in ST. You can even upload other activities while an upload is still active. The additional files are simply added to the list of files to upload.

What is uploaded to your web server:

an HTML file for your activity
image files for all the images that were either added to you from local files () or were generated by components (maps, charts for heart rate tracks, ...)
copies of local files that you linked to with thecommand. So you can easily add additional files (PDFs, documents, spread sheets, fitlog files, ...) that will be uploaded as well.
Note: be careful not to link to local files that you don't want to disclose to the internet community!

The upload manager is smart. It tries to upload all necessary files. If it detects that a file is already present (and its contents need not be changed), it will skip the file.

OK, but where the heck have these files been uploaded to?
How can I open them in my web browser and what is the address that I can pass on to others?

When you have ticked the "Show Uploaded Documentations" checkbox in the upload dialog, a window will have popped up that gives you access to this information.
You've forgotten to set the tick? No problem, simply click on the

item in the editor toolbar.
Or use "Export:

Show Uploaded Documentations".

Open Upload Status Window

This action is available, whenever the upload status window is closed.
It opens a status window which shows you the progress of the FTP upload and gives an estimate, how long the upload will take. Because the plugin has no idea which files it will be able to skip during upload, this estimate might not be exact.

It provides buttons to:

abort the upload:
and hide the status window (); you can reopen it with "Export: Open Upload Status Window"

Show Uploaded Documentations

This action will be available whenever you've uploaded documentations since you started SportTracks.
It pops up this window:

This window lists all activities that you've previously uploaded since you've started SportTracks.
You can select one or many activities in the list and then

open them in your browser () or
copy the address to the Windows clipboard ()
Note: when you've selected just one item in the list, its address will be copied,
when you've selected multiple items, a HTML snippet will be copied that you can add to another HTML page

The Find and Replace Window

This window is opened, when you click on the

Find and Replace action.
It can stay open, while you continue working with SportTracks.

The major parts of this window are:

an area for:
1. the text you're looking for; the down arrow to the right of it lets you select among the recently used texts
2. a flag to ignore character case when searching
3. a flag that switches on regular expression matching (see below)
a tree list where you can specify which objects shall be searched: activities, athlete information, equipment, routes, zones, categories and the activity documentation. Several of these have different fields that can be added or left out.
Tick the items that you want to include into the search.
The and buttons will tick/untick all selected tree list entries and their descendants.
a "Find" button that triggers the search
the results will be displayed in the "Found items" tree list
the in the upper right lets you "pin" this window to the front, above all other windows on your screen
the "Close" button will close this window

Once you've clicked on "Find", the "Found items" list (4) will display the results and a "Replace" area will open at the bottom:

The "Found items" tree list displays a hierarchy of entries:
with item types as toplevel entries, items (e.g. equipment items) as 2nd level entries and fields (e.g. "Diary") as 3rd level entries.
The search pattern is highlighted in the "text" column.

The "Replace" area lets you enter the replacement text (7) and trigger the replacement of all found texts (8). You can even undo your replacements (9) as long as you've not yet closed this window.

When you right click in the "Found items", a context menu for the selected entry pops up. Clicking on "Replace ..." in the context menu will only replace the selected entry and its branches.

Regular Expressions

Regular expressions provide very powerful search and replace mechanisms. The search string will no longer be searched for literally. Instead, it is used as a pattern that is matched against the texts in your logbook.
Some examples:

"bikes?" will match "bike" and "bikes"
"bike|bicycle" will match "bike" and "bicycle"
"USA *: *Colorado *: *Denver" will match "USA:Colorado:Denver" with arbitrary numbers of spaces around the colons

When you click on the down arrow at the very right of the search text field, a context menu will pop up that lets you pick from all elements that are available for regular expressions. This lets you create your search pattern with a few clicks:

See

here for more information concerning regular expressions.

Settings Pages

Activity Documentation Plugin

The most important parts of the plugin's settings page deal with the configuration of your FTP and email credentials that are necessary to upload or email your documentation.

FTP Configuration

You must configure this, when you want to upload documentations to your webserver or home page.
Enter the host name and user name of the FTP access to your web space. You can add a "Folder" name so that the plugin won't upload into the root folder of your web space but into a subfolder.
You don't enter the password here. You will be asked for the password, when you start an upload.
There are two buttons:

"Check FTP Access ...": use this to test if the entered data are correct and the plugin can connect to your FTP server
"Open Browser ...": to let the browser open the index.html page in the subfolder that you've entered

Email Configuration

You need to configure this, when you want to send documentations as email.

You have two choices how to send email:

when Microsoft Outlook is installed on your PC, the email can be sent using your local Outlook;
tick "Microsoft Outlook" in this case
otherwise, the email will be sent through direct access to your email server;
tick "SMTP" and enter the SMTP server (1) and the user name (3) of your email account as well as your email address (2).
You don't enter the password here, You will be asked for it, when you send an email.
Depending on your ISP/email provider you might as well have to tick "SSL" (5) and enter a port number (6).

Where do you find these data? For sure, you use an email client on your PC and you once configured your email account in this email client.
These are screen shots from the email account configuration in MS Outlook and MS Outlook Express.
Quite often the username (3) equals your email address (2).

MS Outlook:

MS Outlook Express:

Plugin Information

The "Plugin Information" panel is standard for all my plugins. See the General Features page for details.

Donation Wallet

The donation wallet is standard for all my plugins. See the "Donation Wallet" section on page General Features for details.
See page Validate your Donation for a step-by-step explanation how to validate your donations.

Custom Fields

This is where you can create and modify your personal fields for SportTracks activities.
Note: these settings are stored in the current logbook.

When you don't need custom fields, untick the check box "enable custom fields ...". The particular detail page will disappear, and custom fields will no longer appear in the activity documentation.

To add a custom field, click on the "New" button. Change it's name from "New" to your desired name, set it's type, choose the category that it shall be used for.
The "type" can be one of "text", "number value", "choice" and "duration". Depending on the type you can enter additional attributes. E.g. a "choice" lets you enter and modify the values by clicking "Edit values".
When you're finished with this field, save it to the logbook with "Save".

To modify a custom field, select it in the list and proceed as above.

To delete a custom field, select it and click on "Delete".
Attention: When you delete a custom field from this list, it will be deleted from all activities.

Appendix: Placeholders for the "Custom HTML Component"

You can use these placeholders in the hand crafted HTML files that you feed into the component. They will be replaced by the current activity's value. The names should be self-explanatory.

%%AverageCadence%%
%%AverageCadenceEntered%%
%%AverageGrade%%
%%AverageHeartRate%%
%%AverageHeartRateEntered%%
%%AveragePace%%
%%AveragePower%%
%%AveragePowerEntered%%
%%AverageSpeed%%
%%Category%%
%%CategoryLong%%
%%Description%%
%%Distance%%
%%DistanceMoving%%
%%DistanceNonPaused%%
%%EndTime%%
%%FastestPace%%
%%FastestSpeed%%

%%GPSPoints%%
%%Intensity%%
%%Laps%%
%%Location%%
%%MaximumCadence%%
%%MaximumCadenceEntered%%
%%MaximumGrade%%
%%MaximumHeartRate%%
%%MaximumHeartRateEntered%%
%%MaximumPower%%
%%MaximumPowerWattsEntered%%
%%Name%%
%%Notes%%
%%SlowestPace%%
%%SlowestSpeed%%
%%StartDate%%
%%StartTime%%
%%StoppedTime%%

%%Time%%
%%TimeMoving%%
%%TimeNonPaused%%
%%TimeNotMoving%%
%%TimeNotMovingNonPaused%%
%%TimePaused%%
%%TimerPauses%%
%%TotalAscendEntered%%
%%TotalCalories%%
%%TotalDescendEntered%%
%%TotalDistanceEntered%%
%%TotalTimeEntered%%
%%UseEnteredData%%
%%Weather.Conditions%%
%%Weather.ConditionsNotes%%
%%Weather.ConditionsText%%
%%Weather.HumidityPercent%%
%%Weather.TemperatureCelsius%%

Appendix: Goodies for Advanced Users

For now, only donators who have given at least the "suggested advanced user donation", can

adding documentation to more than one activity at a time
upload more than one activity documentation at a time
print more than one activity documentation at a time
save more than one activity documentation to local disk at a time
send documentations as email
create Microsoft Outlook appointment items
using "Reports" components