Summary Manual - Custom Overviews

Custom Overviews and Reports

Custom Overviews

If you have Summary SP Lite or SP you can customize the appearance and content of the various Overview reports. You do this by placing files, with specific names, in Summary's Config folder. These files contain HTML templates that Summary will use to display the corresponding Overview. For details about what can appear in these files, see the Free Form Custom HTML Reports section below.

For each Overview, there is a specific file name you should use, in Summary's Config folder, to override the default appearance. These names are:

over.html - main Overview
over1.html - Time Overview
over2.html - Content Overview
over3.html - Referrers Overview
over4.html - Visitors Overview
over5.html - Behavior Overview
over6.html - Problems Overview
over7.html - Bandwidth Overview
over8.html - Others Overview
over9.html - Prog. Status Overview

Samples of how to create custom overviews appear in Summary's Extras folder.

Custom Reports

Summary SP Lite and SP allow you to create custom reports. These reports do not appear in Summary's report menu, but you can create links to them in custom overviews, in the custom HTML header or footer, in other custom reports, or at some other web site.

You create a custom report by making a file whose name ends in ".html" and placing it in a folder called "userpages" inside of your Summary folder. For details about what can appear in these files, see the Free Form Custom HTML Reports section below. A report created in this way appears in Summary in the custom folder.

For example, if you normally access your Summary report menu with a URL of "http://your.domain.com:9000/~jane/menu" and you create a custom report file named "areport.html", place it in the userpags folder inside of the Summary folder, then this custom report can be accessed in a browser using the URL "http://your.domain.com:9000/~jane/custom/areport.html".

Many of the pages of the tutorial use this feature. You may want to look at the some of the examples there to see how to use the custom HTML tags.

Free Form Custom HTML

Custom overviews and custom reports both allow you to use free form custom HTML to create pages that can look like anything you want. These reports can contain any HTML code you want as well as special codes that cause Summary to insert numbers and tables drawn from it's reports.

Errors in using the special Summary tags will be reported in Summary's log file ('summary.log' in Summary's Data folder) on the Linux, OSX Command Line, Sun, and Windows as a Service versions of Summary or in the Summary console window on the Windows and Macintosh versions of Summary. Errors generally result in blank spots in the output, but the remainder of the file will still be processed and displayed as much as possible.

Summary reads the custom HTML file looking for special tags, which it replaces with values from Summary's reports, and passing everything else through unchanged. Below is a list of the special tags that Summary looks for.

Notes: Tag values can be quoted with single quotes or double quotes, or if they don't contain any whitespace they can be left unquoted. A few of the special tags insert table rows formatted for the standard nine column layout used in Summary's regular overviews.

<sum-header>

Usage: <sum-header title="Report Title">

Insert the normal Summary page heading, based on the current custom HTML configuration if any.

title= Use the specified string as the page title.

<sum-footer>

Usage: <sum-footer>

Insert the normal Summary page footer, based on the current custom HTML configuration if any.

<sum-skip>

Usage: <sum-skip>XXX</sum-skip>

Do not pass the contents through when processing. The tags and everything between them is deleted from the output. This allows you to insert HTML code that will only be seen when the document is viewed directly, that is not through Summary.

<sum-uncomment>

Usage:

The contents is only visible if viewing the page through Summary, otherwise it will be seen as an HTML comment. The HTML comment markers must be directly next to the corresponding sum-uncomment tag. This allows you to insert HTML code that will only be seen when the document is viewed through Summary, that is not directly.

<sum-using>

Usage: <sum-using report="03" sort=hits filter=none filter2=none cols="hits.name" search="match">XXX</sum-using>

Defines which report data should be drawn from. Has no direct effect on output, the tags are deleted and their contents passed through. All <sum-insert> and <sum-table> commands must be contained inside a <sum-using>.

report= is required and takes a two or three digit hexadecimal report code. You can find the report codes by taking the final component of the URL of the correct Summary report. These codes do not change from version to version.

sort= is followed by a sort code from the list below. Not all sorts are valid in all reports. It is optional and defaults to the configured report sort order.

filter= is followed by a filter code from the list below. Not all filters are valid in all reports. It is optional and defaults to the configured report filtering.

filter2= is followed by a filter code from the list below. Not all filters are valid in all reports. It is optional and defaults to the configured report filtering.

cols= specifies which columns to include. It is optional and defaults to the configured report layout. The contents should be a list of column codes from the list below, separated by periods. Note that not all columns are valid in all reports.

search= specifies a search string that the item must match in order to be displayed. Search strings work exactly the same as they do in Summary, and don't work with all reports.

You can use the "Get Custom HTML Example" button on a report configuration page to discover values to use for this command. You get to the report configuration page by clicking on the wrench icon at the top of a report that you want to base your configuration on.

<sum-insert>

Usage:
<sum-insert row=1 col=hits>XXX</sum-insert>
<sum-insert row=1 col=hits />
<sum-insert name="string" col=hits>XXX</sum-insert>
<sum-insert name="string" col=hits />
<sum-insert special=named-field>XXX</sum-insert>
<sum-insert special=named-field />

Replace the contents with the value of the given row and column, or special field. The row/col and name versions must be inside a <sum-using> tag. Only a few of the specials need to be inside a <sum-using> tag. The contents, (XXX) if any, is deleted, and the specified value is inserted.

row= specifies which row of the report to draw the value from. Rows are numbered starting at one. One, and only one, of "row=", "name=", or "special=" must appear.

name= specifies the row of the report whose item name matches the supplied string as the row to draw the value from. For example, in a Referring Domain report this might be "www.google.com". Used instead of a row= tag. Only works in reports that have textural item names. This does not work in the Host report, any of the date reports, etc. If no row matches, the first row is used. The string must be an exact match, ie it is case sensitive and there is no wildcard support.

col= specifies which data type and formatting to use. See the list below for available columns. This field is required unless "special=" is used, and then it may not be present.

special= specifies which special data item to insert. See the list below for a list of special items available. This field is required unless "row=" or "name=" are used, and then it may not be present.

<sum-table>

Usage:
<sum-table rows=3 start=1 hlite-row=2 hlite-col=2>XXX</sum-table>
<sum-table rows=3 start=1 hlite-row=2 hlite-col=2 />

Replace the contents with a table containing the specified rows, highlighted as specified. The content, (XXX) if any, is deleted, and a table is inserted.

start= defines the first row to display. It is optional and defaults to one.

rows= specifies how many rows to display, it is optional and defaults to three.

hlite-row= specifies a row to draw in a highlight color, it is optional and defaults to nothing highlighted. Rows are absolute, so if start is 5, and you want to highlight the first visible row you would set this to 5.

hlite-col= specifies a column to draw in a highlight color. It is optional and defaults to nothing highlighted. Columns are numbered from one at the left increasing to the right.

<sum-tab-bar>

Usage:
<sum-tab-bar report=10>XXX</sum-tab-bar>
<sum-tab-bar report=10 />
<sum-tab-bar title="Report Name">XXX</sum-tab-bar>
<sum-tab-bar title="Report Name" />

Replace the contents with a Summary tab bar as if this was the specified report. The content, (XXX) if any, is deleted, and the tab bar is inserted. Tab bars are the list of related report links that appear at the top of a report.

report= takes a two or three digit hexadecimal report code. Either "report=" or "title=", but not both, are required. You can find the report codes by taking the final component of the URL of the correct Summary report. These codes do not change from version to version.

title= takes a quoted character string. Either "report=" or "title=", but not both, are required. A tab bar is inserted that has a Menu tab, an Overview tab, and a highlighted tab with the name specified.

<sum-topn>

Usage:
<sum-topn report=10 rows=5>XXX</sum-topn>
<sum-topn report=10 rows=5 />

Replace the contents with a table containing the top N items for the specified report. Not all reports are supported. The content, (XXX) if any, is deleted, and a table is inserted.

rows= specifies the number of rows that should be displayed. This field is optional and defaults to three. Legal values range from one to twenty.

<sum-link>

Usage:
<sum-link report=03 attr="extras">XXX</sum-link>
<sum-link menu attr="extras">XXX</sum-link>
<sum-link overview attr="extras">XXX</sum-link>
<sum-link to=place-to-go attr="extras">XXX</sum-link>

Replaces the <sum-link> tag with an anchor to the menu, overview, or specified report. This makes the contained text (XXX) a link to the desired destination.

report= takes a two or three digit hexadecimal report code. You can find the report codes by taking the final component of the URL of the correct Summary report. Either "report=" or "to=", but not both, must appear.

attr= the specified string is copied to the output inside the anchor tag.

to= a place to link to. Allowed places include: menu, config, main, cur-main, process, manual, overview, over-time, over-content, over-referrers, over-visitors, over-behavior, over-problems, over-bandwidth, over-others, and over-status.

<sum-graph>

Usage:
<sum-graph what=bytes units=days>XXX</sum-graph>
<sum-graph what=bytes units=days />

Replaces the <sum-graph> tags and their contents with a bar chart of the given item in the given scale.

what= what to display a graph of. bytes, hits, pages, downloads, errors, visits, value, or unique-hosts. Optional, defaults to hits.

units= what time period each bar of the graph represents. hours, days, weeks, months, quarters, years, or auto. Optional, defaults to days.

<sum-reset-line>

Usage: <sum-reset-line>

Reset the alternate line coloring counter. The next line will be background color.

<sum-tr>

Usage:
<sum-tr attr="Extras">XXX</sum-tr>
<sum-tr attr="Extras" />

Inserts a "<tr>" with the current alternate line background color if needed.

attr= the specified string is copied into the page inside the <tr> tag.

<sum-if>

Usage: <sum-if expr="expression">XXX<sum-endif>

Evaluates the expression. If the expression is true, include XXX in the output. If the expression is false skip XXX.

Allowed expressions include:

email: The output is going to be e-mailed
!email: The output is not going to be e-mailed
file: The output is going to be written to a file (static HTML)
!file: The output is not going to be written to a file (static HTML)
long-time: The current report covers more than 180 days
!long-time: The current report covers 180 days or fewer
enabled(XX): Report XX is enabled (not disabled)
A && B: True if both A and B are true
A || B: True if either A or B are true

%%%

Many of the %%% codes from the Summary custom HTML section will work. You should avoid the button related codes and head-extra, body-extra, and title. The following codes are known to work: art, main, cur-main, admin, bgcolor, version, site-name, logo, overview, menu.

Columns

Name Description

line Line number in report

host-name Host Name

host-ip Host Name as IP addr

name Name

name-limit Name, length limited

name-local Name with local Link

name-loc-nodup Name with local Link, blank if same

name-nodup Name, blank if same

log-line Line number

date Date

name-link Name with Link

name-link-nodup Name with link, blank if same

group Group Name

paths Paths

name-drill Name with drill down

name-drill-nodup Name with drill down, blank if same

name-alt-drill Name with alternate drill down

description Description

description-drill Description with drill down

description-nodup Description, blank if same

range Range for histogram

time-range Time range for histogram

phrase Search Phrase

phrase-drill Phrase with drill down

phrase-nodup Phrase, blank if same

phrase-drill-nodup Phrase with drill down, blank if same

source Source

source-nodup Source, blank if same

source-local Source with local Link

source-loc-nodup Source with local Link, blank if same

source-drill Source with drill down

source-drill-nodup Source with drill down, blank if same

hits Hits

pcnt-hits Percent of Hits

pcnt-max-hits Percent of Max Hits

cum-pcnt-hits Cumulative Percent of Hits

hits-pcnt-par Hits Percent of Parent

hits-day Hits per Day

hits-bar Hits Bar Chart

cur-hits-week Current Hits per Week

pcnt-cur-hits Percent of Current Hits

cur-hits-day Current Hits per Day

cur-hits-bar Current Hits Bar Chart

date-hits Crawl Date - Hits

pages Page Hits

pcnt-pages Percent of Page Hits

pages-day Page Hits per Day

pages-bar Page Hits Bar Chart

downs Downloads

pcnt-downs Percent of Downloads

downs-day Downloads per Day

downs-bar Downloads Bar Chart

errors Errors

pcnt-errors Percent of Errors

errors-day Errors per Day

errors-bar Errors Bar Chart

cur-errors-week Current Errors per Week

pcnt-cur-errors Percent of Current Errors

cur-errors-day Current Errors per Day

cur-errors-bar Current Errors Bar Chart

bytes Bytes

pcnt-bytes Percent of Bytes

bytes-day Bytes per Day

bytes-bar Bytes Bar Chart

bits-sec Bits per Second

cur-bytes-week Current Bytes per Week

pcnt-cur-bytes Percent of Current Bytes

cur-bytes-day Current Bytes per Day

cur-bytes-bar Current Bytes Bar Chart

cur-bits-sec Current Bits per Second

bytes-13-months Bytes over the last thirteen months

first-date First Hit Date

first-date-time First Hit Date and Time

last-date Last Hit Date - Last Visit Date

last-date-time Last Hit Date and Time - Last Visit Date and Time

enters Enters

pcnt-enters Percent of Enters

enters-day Enters per Day

enters-bar Enters Bar Chart

enters-hits Enters percent of Hits

exits Exits

pcnt-exits Percent of Exits

exits-day Exits per Day

exits-bar Exits Bar Chart

exits-hits Exits percent of Hits

1-page One Page Visits

pcnt-1-page Percent of One Page Visits

1-page-pcnt-visits One Page Visits % of Visits

1-page-day One Page Visits per Day

1-page-bar One Page Visits Bar Chart

avg-view Average View Duration

total-view Total View Duration

steps-visit Average Steps per Visit

reloads Reloads

reloads-pcnt-hits Reloads percent of Hits

views Views

goals Goals

pcnt-goals Percent of Goals

goals-bar Goals Bar Chart

goals-pcnt-hits Goals percent of Hits

goals-pcnt-hits-bar Goals percent of Hits Bar Chart

goals-pcnt-visits Goals percent of Visits

goals-pcnt-visits-bar Goals percent of Visits Bar Chart

interest Interest

behavior Behavior

growth Growth

growth-trend Growth Trend

err-growth Error Growth

err-growth-trend Error Growth Trend

log-text Text of line with parse error

visits Visits

pcnt-visits Percent of Visits

visits-day Visits per Day

visits-bar Visits Bar Chart

unique Unique Hosts

unique-bar Unique Hosts Bar Chart

value Value (Plus, SP Lite, and SP Only)

pcnt-value Percent of Value (Plus, SP Lite, and SP Only)

value-bar Value Bar Chart (Plus, SP Lite, and SP Only)

value-day Value per Day (Plus, SP Lite, and SP Only)

value-hit Value per Hit (Plus, SP Lite, and SP Only)

value-visit Value per Visit (Plus, SP Lite, and SP Only)

value-goal Value per Goal (Plus, SP Lite, and SP Only)

leakage Leakage (Plus, SP Lite, and SP Only)

leakage-bar Leakage Bar Chart (Plus, SP Lite, and SP Only)

duration Duration

hijacks Hijacked Graphics Visits

hijacks-pcnt-visits Hijack percentage of Visits

hits-mini-graph Graph of Hits Over Time

hits-mini-graph-lab Graph of Hits Over Time, Labeled

hits-8-days Hits over the last eight days

hits-14-weeks Hits over the last fourteen weeks

hits-13-months Hits over the last thirteen months

log-lines Lines

log-valid Valid Entries

log-corrupt Parse Errors

log-filtered Filtered Entries

log-skipped Skipped Lines

log-not-in-any Not in any Report

log-bytes-read Bytes Read

log-size-disk Size on Disk

log-name Log File Name

details Display Detail Items

Sorts

Name Description

hits Hits, Most - Crawl Date

reverse-hits Hits, Least

hits-day Hits per Day

cur-hits Current Hits

pages Page Hits

downs Downloads

errors Errors

cur-errors Current Errors

first-date First Hit Date

first-date First Hit Date

last-date Last Hit Date

bytes Bytes

cur-bytes Current Bytes

name Name

reverse-name Name, Backwards

name-len Length of Name

enters Visit Enters

exits Visit Exits

1-page One Page Visits

avg-view Average View Time

total-view Total View Time

avg-steps Average Steps per Visit

date Date

reverse-date Date, Backwards

day-week Day of the Week

range Range

visits Visits

uniques Unique Hosts

reloads Reloads

views Views

duration Duration

goals Goals

goals-pcnt Goal percentage

hijacks Hijacks

pcnt-hijacks Hijack percentage

value Value (Plus, SP Lite, and SP Only)

value-hit Value per Hit (Plus, SP Lite, and SP Only)

value-visit Value per Visit (Plus, SP Lite, and SP Only)

value-goal Value per Goal (Plus, SP Lite, and SP Only)

leakage Leakage (Plus, SP Lite, and SP Only)

interest Interest

growth Growth

reverse-growth Shrinkage

phrase Phrase

dest Destination

graphics-others Non Page/Download Hits

sname-hits Phrases by Hits - Destination by Hits

log-lines Lines

log-valid Valid Entries

log-corrupt Parse Errors

log-filtered Filtered Entries

log-skipped Skipped Lines

log-not-in-any Not in any Report

log-size File Size

Filters

Name Description

pages Pages

non-page Not a Page

downs Downloads

graphics Graphics

non-graphic Not a Graphic

others Others

external-ref-2 External Referrers With More Than One Hit

hits Has Hits

three Three or More Hits

five Five or More Hits

errors Has Errors

only-errors Only Errors

external-ref External Referrers

local-ref Local Referrers

resolved Ignore (Unresolved) and (Unknown)

known Ignore (Unknown) and (None)

featured Featured

robots-txt Accessed 'robots.txt'

hijacks Has Hijacks

goal Goals

reloads Has Reloads

goals Has Goals

five-goals At Least Five Goals

failed-ref Failed Referrer

failed-loc-ref Failed Local Refer

in-sub-report Log Included in Sub-report

nest-1 Show Only the First Sub-item

nest-1-non-page Show Only First, Not Page

nest-0 No Nested Items

important Important

search-engine Search Engines

non-search-engine No Search Engines

name-user-one Name on User One List

name-user-two Name on User Two List

name-user-three Name on User Three List (SP Lite and SP Only)

name-user-four Name on User Four List (SP Lite and SP Only)

name-user-five Name on User Five List (SP Lite and SP Only)

name-user-six Name on User Six List (SP Lite and SP Only)

name-user-seven Name on User Seven List (SP Lite and SP Only)

name-user-eight Name on User Eight List (SP Lite and SP Only)

sname-user-one Second Name on User One List

sname-user-two Second Name on User Two List

sname-user-three Second Name on User Three List (SP Lite and SP Only)

sname-user-four Second Name on User Four List (SP Lite and SP Only)

sname-user-five Second Name on User Five List (SP Lite and SP Only)

sname-user-six Second Name on User Six List (SP Lite and SP Only)

sname-user-seven Second Name on User Seven List (SP Lite and SP Only)

sname-user-eight Second Name on User Eight List (SP Lite and SP Only)

next-all Show All Sub-items

search-indexer Search Indexer

Specials

Name Description

memory memory usage by type and sub-report tables (short)

unique-hosts number of unique hosts

countries number of unique countries

page-hits total over all time of page hits

downloads total over all time of downloads

graphics total over all time of graphics hits

other-hits total over all time of other hits

total-hits total over all time of hits

visits total over all time of visits

error-hits total over all time of errors

error-percent percentage of all requests that were errors

unique-failed number of unique failed requests (no valid hits)

distinct-files number of items in the all requests report

pages-visit average number of pages per visit

hits-visit average number of hits per visit

bytes-visit average number of bytes per visit

duration-visit average duration of a visit

time-between average time between visits from the same IP

visits-host average number of visits per IP

bytes-total total over all time of bytes transferred

avg-bits-sec average, over all time, of bits per second transferred

referring-domains number of unique referring domains

referring-pages number of unique referring pages with more than one refer

avg-bytes-month average number of bytes transferred per month

suggested-bandwidth suggested bandwidth (6 * peak bps)

blank a blank table row (colspan=9)

window-size window size needed to support XX% of visitors

bytes-page average number of bytes transferred per page hit, ignoring downloads

known-robot-visits total number of known robot visits

likely-robot-visits total number of likely robot visits

1-page-visits total number of 1 page visits

refers total number of visits referred

known-search-visits known search engine referred visits

first-date date of the earliest log entry reported on

last-date date of the most recent log entry reported on

days number of days included in the report

calculated-date date of the most recent processing run

item-count number of lines in the full report, only valid inside a <sum-using>

note-text help text that would appear at the top of the report, only valid inside a <sum-using>

admin-email administrator e-mail address

program-version level of registration and version number ("Summary 2.3.2", "Summary Plus 2.4", etc)

program-date date of the last Summary executable update MM/DD/YY

site-name current sub-report descriptive name

suggested-line suggested server <-> internet connection speed (T1, 56K modem, etc)

page-hits-day average over all time of page hits/day

downloads-day average over all time of downloads/day

graphics-day average over all time of graphics hits/day

other-hits-day average over all time of other hits/day

total-hits-day average over all time of hits/day

visits-day average over all time of visits/day

error-hits-day average over all time of errors/day

refers-day average over all time of visits referred/day

bytes-total-day average over all time of bytes transferred/day

known-robot-visits-day average over all time of known robot visits/day

likely-robot-visits-day average over all time of likely robot visits/day

1-page-visits-day average over all time of 1 page visits/day

cur-page-hits current page hits/day

cur-downloads current downloads/day

cur-graphics current graphics hits/day

cur-other-hits current other hits/day

cur-hits current hits/day

cur-visits current visits/day

cur-error-hits current errors/day

cur-refers current visits referred/day

cur-bytes-total current bytes transferred/day

cur-error-percent percentage of all current requests that were errors

log-files number of log files read(scanned)

log-lines number of log file lines read

corrupt-lines number of corrupt log lines

skipped-lines number of skipped log lines

valid-entries number of valid log entires

filtered-entries number of filtered log entries

not-in-any-entries number of log entries not in any report

total-log-size total size of all log files (uncompressed)

disk-log-size total size of all log files (on disk)

time-crunch time to crunch

speed-meg-min processing speed in meg/min

speed-lines-sec processing speed in lines/sec

memory-used memory used

physical-memory physical memory in machine

available-memory memory still available (Mac Carbon only)

memory-usage memory usage by datatype and sub-report tables (short)

memory-usage-long memory usage by datatype and sub-report tables (long)

units-total-log-size units name of size of logs read

units-disk-log-size units name of size of logs on disk

known-search-visits-day number of visits from known search engines/day