Format XML for Result Entry

Format XML Files are standard XML files, whos markup contains data which PC School can interpret, and use to create a View of selected Data. Generally this is used in creating views for Result Entry by Spreadsheet, but can also be used in a more limited mode in Absent Rolls.

 Overview

Format XML files contain a Definition node, a series of section nodes, each of which may contain several object nodes, and finally several optional Result Table nodes. Note throughout the document, for elements that are not mandatory, the default setting is highlighted in Bold.

Definition Node

The Definition Node contains a series of settings for the Format XML file. A format XML will only ever have one Definition Node. In most cases, all that really needs to be defined in the Definition node, are the Type and Section Break. Usually Font Name and Size are also set to suit your schools own style.

List of Definition Elements

Name Type
XML <type>
Mandatory Yes
Sample <type>ClassTree</type>
Options ClassTree,ClassStudentPage,ClassBreakPage
Description Defines how the data should be presented
Name Type
XML <type>
Mandatory Yes
Sample <type>StudentAllSubjectsPage</type>
Options
Description Will result in all subjects for the student being displayed on a single page.

 

Name Auto Format
XML <autoformat>
Mandatory No
Sample <autoformat>false</autoformat>
Options true,false
Description Forces the cells to automatically resize based on their content. This node may be added more than once if you want to allows multiple types.
Name Ignore Break Set
XML <ignorebreakset>
Mandatory No
Sample <ignorebreakset>true</ignorebreakset>
Options true,false
Description When set tp true, forces the data to include the Breaks defined in the appropriate subjects Default Areas of Assessment.
Name Font Name
XML <fontname>
Mandatory No
Sample <fontname>courier new</fontname>
Options any installed truetype font (default is Arial)
Description Defines the font to be used by default in all objects. Is overridden when a fontname value is declared in an object.
Name Font Size
XML <fontsize>
Mandatory No
Sample <fontsize>10</fontsize>
Options any valid font size (default is 8)
Description Defines the font size to be used by default in all objects. Is overridden when a fontsize value is declared in an object.
Name Section Break
XML <sectionbreak>
Mandatory No
Sample <sectionbreak> <type>break</type> <field>Classification</field> </sectionbreak>
Options see Description
Description Section Break node contains to items, type and field. At this stage the only valid values are type ‘break’ and field ‘Classification’. When this value is set, the Results will be seperated into sets of Breakdowns with identical Classifications
Name Freeze Columns
XML <freezecols>
Mandatory No
Sample <freezecols>2</freezecols>
Options any valid column number
Description Makes the spreadsheet freeze the columns to the left of the number set. Useful for forcing data such as the student name to always appear on the left of the sheet.
Name Freeze Rows
XML <freezerows>
Mandatory No
Sample <freezerows>1</freezerows>
Options any valid row number
Description makes the spreadsheet freeze the rows above the identified value. Useful for setting a permanant header section.
Name Comment Length
XML <commentlength>
Mandatory No
Sample <commentlength year=” 8″ subject=”1″>250</commentlength> <commentlength subject=”20″>250</commentlength>
Options any valid number. Default in no maximum length.
Description Note: Feature not yet implmented. Please use maxvalue in the Object node. Defines the maximum length in characters that a comment may contain. year, subject and class attributes may be define for situations where specific areas need differing lengths.
Name maxstudentcount
XML <maxstudentcount>
Mandatory No
Sample <maxstudentcount>10</maxstudentcount>
Options any valid number.
Description Define the maxmimum students possible in a page in “Classtree”. This will override what is mentioned on “Results per page” on screen. The advantage is that, if the class is a small one, the teachers don’t need to click on the textbox and change the value from 5 to 10 in order to show 10 students in a page.

 

Name Include In List
XML <includeinlist>
Mandatory No
Sample In Teacher Result Entry: <includeinlist>true</includeinlist><includeinlist>pcschool:default</includeinlist><includeinlist>pcschool:true</includeinlist><includeinlist>spider:default</includeinlist><includeinlist>spider:true</includeinlist>In Student Result Entry: <includeinlist>spiderfamily:true</includeinlist><includeinlist>spiderfamily:default</includeinlist><includeinlist>spiderstudent:true</includeinlist><includeinlist>spiderstudent:default</includeinlist>
Options true, default, false
Description When set to true or default, this Format XML will appear in the Style dropdown menu in Result Entry by Spreadsheet. When set to default it will be automatically selected. if set to false or not set, it will not appear in the list. The use of Spider: or PCSchool: will determine in which environment the xml will be restricted to. Format xmls marked Spider: will only appear in the Spider, and  those tagged PCSchool: will only appear in Back Office. Where neither tag is included then the xml will appear in both environments.
Name Break Period
XML <breakperiod>
Mandatory No
Sample <breakperiod>1</breakperiod>
Options any valid Breakset period
Description Only applicable when ignorebreakset is set to false, this value is used to identify which Break Set should be used.
Name Indent Row
XML <restrictclassification>
Mandatory No
Sample <restrictclassification>PA</restrictclassification>
Options C, A, M, P, L, I, J
Description Only used when for Break sectionsShould be defined in conjuction with a Section Break in the Definition node. When defined, all Breaks that match the classification set will be output using this format. Note that each classification type should only be defined once per Format XML.
Name Tab Label
XML <tablabel type=”ClassBreakPage”>
Mandatory No
Sample <tablabel type=”ClassBreakPage”>%1 (%2)</tablabel >
Options %1, %2, %3, %4, %5, %6
Description Only used for ClassBreakPage type formatsIs used to change the information contained in the Tab Label of each page. Inside that node you can define a string which can have the arguments %1-6. These arguments can be used to create a formatted string, and they stand for:

  • %1 = Area.Item
  • %2 = Area.Classification
  • %3 = Area.Areacode
  • %4 = Area.Abbrev
  • %5 = Area.Boardcode
  • %6 = Area.Standard

When Undefined, the default value is %1 (%2) which equates to Area.Item (Area.Classification).

 Sample Defintion Node

From ResultEntryByClass.xml:

<definition>
    <type>ClassTree</type>
    <fontsize>8</fontsize>
    <fontname>tahoma</fontname>
    <sectionbreak>
	<type>break</type>
	<field>Classification</field>
    </sectionbreak>
    <includeinlist>default</includeinlist>
</definition>

Section Nodes

Format XML files may contain a series of Section nodes. Each section is used to define how a Sub, Break or Level record is displayed in the spreadsheet. By using values such as breakfield and typeid you can define sections to create different layouts for different Subjects or Break Classifications. Result Entry Section nodes are comprised of types Header, Sub, Sub Footer Break Header, Break and Levelsnodes. A typical Result Entry Format XML will consist of the following sections:

  • a Header Node
  • One or more Sub nodes
    • It’s not unusual to have only 1 Sub section, the only reason to have multiples are when you want different styles for different subjects.
  • One or more Break and Break Header Nodes

Level section nodes are less commonly used, as very few schools use the Levels functionality within PC School. Sub Footer sections can also be used to show further subject information after all the break data has been output. Absent Roll Format XMLs only use a single Header and Sub section. Any other sections will be ignored. Section Nodes are made up of one or more Object Nodes. Each of these object nodes represent a field to be output. The positioning of these objects can be defined as either Relative or Absolute. Relative objects are positioned next to the previous object based on a set of elements in the Section node. Absolute objects are positioned on a position on the screen designated by a column and row number. Generally, when outputting data sections such as Sub, Break and Level sections, Relative positioning is used. This allows a flexible approach to displaying data, which is especially important when dealing with subjects which may have different Areas of Assessment allocated to them Absolute positioning is usually reserved for Header and Footer sections. Using absolute positioning in Sub, Break and Level sections is usually not advised, unless you know that all subjects you wish to view with this Format XML contain the exact same number of Areas of Assessment, and all have been allocated correctly. If this is not the case then the spread could end up being at best ugly, at worst not functional.

List of Section Elements

Name Type
XML <type>
Mandatory Yes
Sample <type>Sub</type>
Options Header, Sub, Sub Footer, Break, Break Header, Break Footer, Level
Description Defines the type of section.
Name Default
XML <default>
Mandatory No
Sample <default>true</default>
Options true, false
Description When set to true, this Section will be used for all records that don’t match the criteria set in other nodes of it’s type.
Name Type ID
XML <typeid>
Mandatory Yes
Sample <typeid>10</typeid> <typeid>APM</typeid>
Options For Sub sections a Subject Number. For Break Sections one or more Classification Codes (C, A, M, P, L, I, J)
Description Should only be declared in Sections that are not Default ones. By defining this element and subject matching this number, or breakdown matching this classification will use this node for formatting rather than the default one.
Name Format
XML <format>
Mandatory Yes
Sample <format>relative</format>
Options relative, absolute
Description Defines that objects within this section should be defined as being positioned relative to the previous object, or on an absolute position on the screen.
Name Relative Position
XML <relativeposition>
Mandatory No
Sample <relativeposition>down</relativeposition>
Options down, right
Description Only used when Format is Relative. Defines whether or not the object should appear below or to the right of the previous section.
Name Object Direction
XML
  • Declares a simple string object pointing to the Effort Application field in the Sub file
 Declares a Percentage object pointing
 to the Percentage field in the
 Sub file.


  • An example of a label cell, usually output in a header section.

Checkbox Groups

Checkbox Groups are a series of cells containing values read from a Result Table. These cells each contain a checkbox, and only one item may be selected at a time. Each checkbox corresponds to an item in the Result Table assocaited with it. When positioning elements around Checkbox Groups it is important to understand that these items will span a number of cells equal to the number of items in the result table. Image:FormatXML_CheckboxGroup.png

A sample of a Checkbox Group.

Samples
 A sample Checkbox Group object 
pointing to table 6, which stores 
data in field Result3 (in the Break
 file). As no object direction is 
defined, the checkboxes will 
automatically be displayed from 
left to right.

Combo Forms

Combo forms are objects which contain a drop down list of selectable items. These items are derived from the Result Table to which this cell is linked. Combo forms are responsive to keyboard entry and will automatically select the first value in the list that matches the key pressed. Image:FormatXML_ComboCells.png

A collection of Combo Form Cells.  
Samples

  • This example shows a combo form linked to Result Table 3, which records data in the Grade field (in the Sub file).

Pictures

Picture cells can be used to display images within the spreadsheet. Pictures must be of the format bmp, jpeg or png. Various settings can be applied to picture cells to control whether or not they strech or keep their scale. The image files are normally used in conjuction with the StudentImage field, which autmatically returns the path to the appropriate student image. This type of cell is relatively uncommon, due to the difficulties assocaited with sizing and positioning the image on the screen.

Checkboxes

Checkboxes are rarely used in the Format XMLs, and superior functionality can be found by using Checkbox Groups and Combo forms.

List of Object Elements

Name Field Type
XML <type>
Mandatory No
Sample <type>field</type>
Options field, datalabel, value
Description Defines what type of data the cell should contain. Field is a database field that can be changed. Datalabel is a read only database field. Value is a static text field.
Name Value
XML <value>
Mandatory Yes
Sample <value>2</value>
Options Any string. Database fields need to match one of the values described in the the Data Fields list
Description Defines the value of a cell. When a value type is declared, the value of this element is displayed in the cell.
Name Cell Type
XML <celltype>
Mandatory No
Sample <celltype>Percentage</celltype>
Options Percent/Percentage, Checkbox, Numeric/Number, Picture, Combo/ComboForm/ComboBox, Button, Textbox, CheckboxGroup, String
Description Defines the type of data that will be presented. See the section on Cell Types for more information.
Name Label
XML <label>
Mandatory No
Sample <label>Grade</label>
Options any valid text
Description Inserts a cell containing the defined value in the cell immediately before the one to be output. In the case of a Button cell type, the label will become the Text on the button.

Cell Type Specific Options

Buttons
Name Button Message
XML <buttonmessage>
Mandatory No
Sample <buttonmessage>SubComment</buttonmessage>
Options see Comment Button section below
Description see Comment Button section below.

Pictures
Name Picture Stretch
XML <picturestretch>
Mandatory No
Sample <picturestretch>true</picturestretch>
Options true, false
Description Forces the picture to strech to meet the size of the cell.
Name Picture Maintain Scale
XML <picturemaintainscale>
Mandatory No
Sample <picturemaintainscale>true</picturemaintainscale>
Options true, false
Description The picture will resize to maintain the it’s scale.
Name Picture Full Path
XML <picturefullpath>
Mandatory No
Sample <picturefullpath>true</picturefullpath>
Options true, false
Description When set to true, it will presume the value element contains a full path to the picture file.

Checkbox Group
Name Object Direction
XML
  • a Combo object pointing to Result Table 1
<resulttable>
    <tableid>1</tableid>
    <result>
      <value>A+</value>
    </result>
    <result>
      <value>A</value>
    </result>
    <result>
      <value>B+</value>
    </result>
    <result>
      <value>B</value>
    </result>
    <result>
      <value>C+</value>
    </result>
    <result>
      <value>C</value>
    </result>
    <result>
      <value>D+</value>
    </result>
    <result>
      <value>D</value>
    </result>
    <result>
      <value>E</value>
    </result>
    <result>
      <value>UN</value>
    </result>
    <result>
      <value>NA</value>
    </result>
    <result>
      <item>-</item>
    </result>
</resulttable>
  • A result table with no defined Items
<resulttable>
    <tableid>2</tableid>
    <result>
      <value>1</value>
      <item>1st Quartile</item>
    </result>
    <result>
      <value>2</value>
      <item>2nd Quartile</item>
    </result>
    <result>
      <value>3</value>
      <item>3rd Quartile</item>
    </result>
    <result>
      <value>4</value>
      <item>4th Quartile</item>
    </result>
    <result>
      <value>NA</value>
      <item>Not Applicable</item>
    </result>
    <result>
      <item>-</item>
    </result>
</resulttable>
  • A Result table with Items defined.

  • A Comment based Testimonial Checkbox
  • Referenced Area of Assessment must be tied to a Comment Category

Testimonial Result Entry

TestimonialXMLSection

  • A Result table with <CommentCategory> defined

TestimonialResultTable

Comment Buttons

Comment buttons can be used to access the Comment Bank dialog from the Result Entry by Spreadsheet. Only specific comment fields can be accessed using this method. When declaring a button type, the type should be datalabel, the celltype should be Button, and value recnum, and then the buttonmessage defines the field that will be accessed. The only valid fields for comment buttons are SubComment, SubAuditComment,BreakComment and AncillaryComment. The label field can also be used to define the text on the button. Note that comments can also be viewed as String objects inside the spread, however advanced Comment Bank features such as a spellchecking won’t work, and multi paragraph comments will be hard to maintain. Comment lengths can be defined by using the maxvalue node inside the object. See the code below for an example.

Sample Comment Button Object


A button with the text Comment on it will be shown on the cell, pointing to the Subject comment.

Data Fields

Each section is associated with either the Sub, Break or Levels file. To access data the object type must be either field (editable) or datalabel (read-only). The tables below list the available fields in each of the three sections. Not all fields are editable and this is noted in the table. Fields which are not editable are always treated like datalabels. Note that these field names are Case Sensitive. For example StudentHash will work, while studenthash and Studenthash will not.

Sub fields

Sub fields relate to the Sub file in PC School. This file holds the general subject information, and some of the overall grades such as achievement and effort/application. A Sub section will only be output once per subject.

Field Code Editable
Class Information Class No
Subject Description Subject No
Sub Recnum Recnum No[1]
Studkey Studkey No
Age Age No
Student# StudentHash No
Subject Period ID PeriodID No
Sex Sex No
Surname Surname No
Known As Name KnownAs No
Date of Birth Birth No
Sub Achievement Achievement Yes
Sub Attitude Behaviour Attit_Behaviour Yes
Sub Effort Application Effort_Applic Yes
Full Student Name (Surname, First Name)[2] StudentName No
Full Student Name (First Name Surname)[3] StudentNameFirstLast No
Sub Percentage Percentage Yes
Sub Rank Rank Yes
Sub Organisation Organisation Yes
Sub Average Average Yes
Sub Parent Contact ParentContact Yes
Sub Comment SubComment Yes
Sub Comment ExpectedOutcome Yes
Student Image StudentImage No
  1. ^ Used for Sub Comment buttons
  2. ^ Displays the student name as Surname, Given/KnownAs. Uses the System file preference to determine whether Given Name or Known As Name should be used.
  3. ^ Displays the student name as First Name Surname. Uses the System file preference to determine whether Given Name or Known As Name should be used.

Break fields

Break sections represent the Areas of Assessment allocated to a Subject. Generally there are several Areas of Assessment for each subject, so there will normally be several Break sections output. Areas of Assessment are divided into Classifications such as Academic, Personal, Criteria, Modules/Standards, Internal and External. It is not unusual to see Format XMLs set up to have different break sections for each different classification used by the school.

Field Code Editable
Area Item AreaItem No
Break Recnum Recnum No[1]
Studkey Studkey No
Age Age No
Student# StudentHash No
Subject Period ID PeriodID No
Sex Sex No
Surname Surname No
Known As Name KnownAs No
Date of Birth Birth No
Full Student Name (Surname, First Name)[2] StudentName No
Full Student Name (First Name Surname)[3] StudentNameFirstLast No
Area Board Code AreaBoardCode No
Area Code AreaCode No
Area Classification AreaClassification or Classification No
Area Critera AreaCriteria No
Area Column Heading 1 AreaColHeading1 No
Area Column Heading 2 AreaColHeading2 No
Area Column Heading 3 AreaColHeading3 No
Student Image StudentImage No
Break Date Completed DateCompleted Yes
Break Exclude Upload ExcludeUpload No
Break Result Result Yes
Break Result 2 Result2 Yes
Break Result 3 Result3 Yes
Break Result 4 Result4 Yes
Break Result 5 Result5 Yes
Break Sort Order Sort_Order Yes
Break Grade Grade Yes
Break Expected Outcome ExpectedOutcome Yes
Break Expected Outcome ExpectedOutcome Yes
Break Comment BreakComment Yes
Break Ancillary Comment AncillaryComment Yes
  1. ^ Used for Break Comment buttons
  2. ^ Displays the student name as Surname, Given/KnownAs. Uses the System file preference to determine whether Given Name or Known As Name should be used.
  3. ^ Displays the student name as First Name Surname. Uses the System file preference to determine whether Given Name or Known As Name should be used.

Level fields

Levels are Levels of Achievement within Areas of Assessment. These items are quite uncommon, as the vast majority of schools don’t need this depth of reporting, and therefore don’t use levels. As with Break sections, these items will normally be output several times. If you’re unsure of whether or not your school uses levels, contact the PC School Help Desk.

Field Code Editable
Area Code AreaCode No
Levels Result 1 Result1 Yes
Levels Result 2 Result2 Yes
Levels Result 3 Result3 Yes
Levels Sort Order Sort_Order Yes

Colour Table

The Spread control can display a wide variety of colours. The following are presented as a standard list of colours available for use. Additional colours can be found here. If you have a specific requirement for a different color, then contact the PC School Help Desk.

Colour Code
Red clRed
Black clBlack
Blue clBlue
Green clGreen
Yellow clYellow
Aqua clAqua
Dark Gray clDkGray
Fuchsia clFuchsia
Gray clGray
Lime clLime
Light Gray clLtGray
Maroon clMaroon
Nayv clNavy
Olive clOlive
Teal clTeal
Purple clPurple
White clWhite

Notes Regarding Width

Width can be defined for each cell, however setting the width of a column is not neccessarily straight forward. Given the dynamic nature of Result Entry screens, it is possible that the same column can have it’s width set more than once. This is fine if the width is the same value both times, however when the two width values are different, the value that is set last will take precedent.

Quick Guide to Creating Format XML’s

Creating Format XML files can be a complex task. There is a great deal of variety in what can be presented and in what way. Before starting to create a Format XML, consider the following:

  • How well do you understand the Result setup of your school? It is critical to understand the make up of your schools Subject Allocations and Areas of Assessment. If you are unfamiliar with how you school is setup, or the way that Result Entry works in PC School, then it’s a good idea to speak with one of our support staff to discuss your setup, and any training options if required.
  • Decide if you need to start from scratch. PC School supply several standard Format XML files (found inside the PCSchool\Documents folder on your PC School Server). All of the examples found in this document are taken from these samples. Normally the best way to create a create Format XML is to start with an existing one and modify it to your liking. We also have a series of Format XMLs that have been created for other schools. If you have pa particular requirement it’s always a good idea to discuss this with one of the Support Staff, as we may be able to supply you with an existing XML file.
  • How well do you understand XML? XML is a text file, however it can be quite easy to create invalid XML. If you’ve never used XML before it’s worth reading about it. Some excellent tutorials can be found at w3 Schools.
  • How are you going to create the XML? XML is a text file, which can be edited in Notepad. However this is normally not the easiest way to edit XML files. At PC School we use a range of tools including the commercial XML Editor [9] and the Open Source tools Eclipse and Notepad++.
  • Have an idea of what you want to achieve before you start. The options in creating Format XMLs are quite varied, so it’s a great idea to have a vision of how you want the spreadsheet to look. One way to start is to create a mockup in a tool such as Excel. With this in hand, you’ll have a better idea of where to go, and will also be useful to use should you require assistance with your setup.
  • Keep backups! When working on a Format XML, it’s a great idea to keep a copy of the original file you’ve been working on. This way you’re able to make incremental (and possibly dramatic!) changes to the file, and have the original to fall back on in case you can’t fix it.
  • Feel free to ask for help! Matt and Trev all regularly work with Format XMLs, and we’re always happy to help out with any queries or suggestions!

When starting from scratch (or even from an existing file):

  1. Create the Definition Node, defining the default settings you require for your XML.
  2. Create a Header section. There should only ever be one. Make sure it includes useful information such as the Teacher name, Class and Year level.
  3. Create the Sub section. Always include the Student Name or Studkey in some form to help you identify each record.
    1. If neccessary, create Sub sections for any subjects with different setups.
    2. If you want to display some Sub information after all the Breaks have been output, use a Sub Footer section.
  4. Create a Default Break Section. This should reflect the most common type of Area of Assessment used.
    1. Create Break Sections for each Classification in use. Generally each school has a different layout for different Classifications.
    2. Use Break Header sections if you want to have a different header for each Classification type.
  5. once you’ve got the layout of all your areas of assessment right, start adding any formatting features (colours, fonts, borders etc.) that you’re after.

The above information is for users of PCSchool Student Management School Software.

Advertisements

About studentmanagementsoftware

Director Student Management School Software PCSchool
This entry was posted in Result Entry, XML Files and tagged , , . Bookmark the permalink.

3 Responses to Format XML for Result Entry

  1. Pingback: PCSchool XML Files | PCSchool Student Management Tech Support

  2. Pingback: Multi-Subject Information in Result Entry by Spreadsheet | PCSchool Student Management Tech Support

  3. HomeRoom has been added to the Subject Tags

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s