PSU 2014

Customizations 501:
PowerSchool Customizations Academy

Customizations 501
PowerSchool has taken a significant step forward in the ability to create and manage
customizations. With the recent addition of database extensions and page fragments, you
now have much more flexibility in creating your own fields, as well as a cleaner way of
customizing pages that does not conflict with other pages.
The ability to modify existing tables as well as create new tables has been a request of
advanced customizers for some time. If you have worked with PowerSchool customizations,
you know the limitations of the legacy custom field structure. Learning to use database
extensions effectively will greatly improve your power to customize PowerSchool.
You also know that customizing PowerSchool pages creates its own problems because of
conflicts with future updates. You may have run into the situation where you have already
customized a page and want to add an additional customization that someone else created.
Your only option is to combine the two files into a single customization, which is not always
an easy task. With the addition of insertion points and page fragments, you can now keep
all customizations separate and out of the original file, which means when a page is
updated, your customization will be inserted into the new page automatically.
With these new features comes a new level of complexity. Creating custom fields in previous
versions of PowerSchool was simple and did not require an understanding of database
design. This is no longer true for database extensions. It is critical that you develop a solid
foundation in database design and follow best practices when creating your custom fields.
The use of page fragments is no different. Since you are inserting data into a page,
controlling where the data is placed is critical to the success of your customizations. This
requires the use of JavaScript and jQuery. Once you have a solid understanding of these
tools and how they can control page fragments, you will see the full power of their use.
For these reasons, we have moved these topics into a new format called the PowerSchool
Customizations Academy. After listening to participant feedback and evaluating the new
course offerings, it was decided that the best format for teaching this new advanced
material was a two-day course. This allows more flexibility in both time and class structure.
This will not be like any other class you have taken at PSU. Participants in this class should
be well versed in customizations, SQL, HTML, CSS, and JavaScript. You do not have to be
an expert in every area, but rather, be comfortable in each subject and be well versed in
the foundations of each. This class will build on your existing knowledge, which is not
always possible in core customization classes, due to varying levels of experience. For this
reason, the self-assessment tool was offered to help you determine both your strong and
weak areas, allowing you to adjust your class schedule to prepare for the academy.
The Academy will not follow the normal format of class activities. Instead, you will be
working as a group on a large customization. You will be doing everything from planning the
customization to packaging the final product to take home. This allows you to see all the
steps necessary, and, more importantly, put into practice the things you have learned in the
core customization classes. Because of this, you will find very few activities in this handout.
Those that are included are intended to explain and provide practice on a specific concept.
Hopefully, you will find this new format not only beneficial but also an enjoyable way to
learn about advanced customization topics.

Copyright 2014 Pearson

Customizations 501
Introduction of Database Extensions
With PowerSchool 7.10, Pearson provided districts and schools with the ability to extend the
PowerSchool database in new ways. Migrating existing custom fields both Pearson core
fields and user-defined fields and creating new tables and fields are complex topics that
need to be fully understood before diving into their use.
During this class, you will:

See how to migrate existing custom fields to the new system

Learn how to interact with custom fields once they are migrated

Create new custom fields and tables

Add pages to PowerSchool to interact with your new database extensions

A Little History
In earlier versions, PowerSchool supported creating custom fields in four tables: students,
teachers, courses, and sections. There were several issues with the way this was
implemented, though:

Legacy custom fields are created in a CLOB (character large object). And because of
this:
o

Data is harder to access

Data cant be retrieved through direct SQL

Server performance was impacted

Legacy custom fields do not have data types

One-to-many records are not supported

PowerSchool now provides the ability to create real database extensions rather than legacy
custom fields, which solves all of the problems described above with legacy custom fields.
Database extensions allow you to create real tables and fields, are easy to access, and
significantly improve performance. This new database extension functionality supports oneto-many and one-to-one data as well as field data typing, and may be based on most
database tables in PowerSchool. In addition, PowerSchool provides the ability to migrate
Pearson-provided custom fields to become database extensions. And, you are able to
migrate user-created custom fields to this new, more robust technology.

Database Extensions
There are three types of database extensions possible in PowerSchool: one-to-one, one-tomany, and standalone. Each has a specific purpose.

One-to-One Table Extensions

One-to-one table extensions add new logical data elements to a parent table. For example,
you can add a field to a database extension in the Students table in order to store unique
data for each student. In PowerSchool, legacy custom fields hold additional data for a given
record, and this data can be migrated to a one-to-one database extension.

Copyright 2014 Pearson

Customizations 501
One-to-Many Tables
A one-to-many table extension creates a child table to the designated parent table and
allows multiple records to be created that are tied back to a single parent record. For a
given child table, one row in the parent table is related to zero or more rows in the child
table. Examples of existing one-to-many tables in PowerSchool where the Students table is
the parent are Special Programs, Logs, and Historical Grades.

Standalone Tables
A table that does not have a one-to-one or many-to-one relationship with an existing
PowerSchool table is a standalone table. For example, an asset management table can be
created to inventory district assets such as computers or sports equipment. They can also
be used to provide consistent data entry by providing a list of choices for an input.

Extension Groups
Extension groups provide a structural method to group tables of like purpose. Each group
can only have one one-to-one table, but can have many one-to-many and standalone
tables. How you group tables can vary, depending on your purpose. Finding a logical
structure will make it easier to work with your data.

Datatypes
Fields can be defined as one of seven possible datatypes. These allow the database to
properly store and retrieve information in PowerSchool.

String: Fixed-length character string

Integer: Number that can be written without a fractional or decimal component

Date: Point-in-time value (date and times)

Double: Number with up to 15 place values to the left of the decimal and up to 10
decimal places to the right

Boolean: Data has two values (1=true and 0=false)

CLOB (Character Large Object): Data stored in a separate location referenced by the
table

BLOB (Binary Large Object): Collection of binary data stored as a single entity

Reserved Words
There are some words that you cannot use when creating tables and fields. They are
reserved because they have specific meaning in Oracle, which PowerSchool uses for its
database, and Java, which is the language that PowerSchool is written in. These words are
documented in the System Administrator User Guide, available on PowerSource. The
document is listed at the end of this handout.

Copyright 2014 Pearson

Customizations 501
A Small, Healthy Dose of Database Design Concepts
As you now have the capability to create more extensive data tables, it is important to
make sure that what is created is based on sound database design. That topic alone could
be the subject of more than four days of training.
Its like building a school. You dont start with buying concrete, wire, and pipes. You start
with gathering information, developing a design, and verifying that it meets all the needs of
all users before you start construction.
The same design process must go into building a database extension, so here are some
starting concepts.

Define the project completely on paper before you even touch PowerSchool

Create a naming standard for extension groups, tables, and fields

First create the system on a test server and work out all the bugs
If something feels wrong, refresh the server and start over. Keep doing this until it
all works correctly.

Remember that there is no delete ability, so get it right

Dont duplicate data that is already in another table; create a way to link to it

Use standalone tables as sources for data that should be consistent

Find a good database design book and start learning

Using Database Extensions in Page Customization

Once you have created database extensions, you need to provide a way to enter data into
those fields and tables. Each extension type requires different input methods. Here is the
basic information on each type.

Use a One-to-One Field on a Page

To work with a one-to-one table extension on a page in PowerSchool, refer to the primary
table, the database extension group name, and the field name in the following format:
[PrimaryTable.ExtensionGroupName]Field_Name

Create a Page with a One-to-Many Table

Tlist_child is a new tag created to work with one-to-many tables. This tag will auto-generate
an HTML table to display rows of records from the designated child table, including an Add
button and Delete buttons for each row that has been created.
The following is the format for the tlist_child HTML tag:
~[tlist_child:<CoreTableName>.<ExtensionGroup>.<ExtensionTable>;displaycol
s:<List of Fields>;fieldNames:<List of Column Headers>;type:<FormatName>]
The following provides additional information on this tag:
The <CoreTableName>.<ExtensionGroup>.<ExtensionTable> narrows the query down to a
single child table.

Copyright 2014 Pearson

Customizations 501
The displaycols is a comma-separated list of fields from the one-to-many table, and can
include any or all of the defined fields in that table. Two special ID fields may also be
referenced: ID and <CoreTableName>DCID. In the example above, this would be
STUDENTSDCID.
The fieldNames is a comma-separated list of the labels that should appear in the autogenerated table heading. These labels may contain spaces.
The type parameter specifies a format. Currently, the only valid format is "html".

Create a Page with a Standalone Table

Tlist_standalone is a new tag created to work with standalone tables. This tag will autogenerate an HTML table to display your rows of records, including an Add button and Delete
button for each row that has been created.
The following is the format for the tlist_standalone HTML tag:
~[tlist_standalone:<ExtensionGroup>.<ExtensionTable>;displaycols:<List of
Fields>;fieldNames:<List of Column Headers>;type:<FormatName>]
The following provides additional information on this tag:
The <CoreTableName>.<ExtensionGroup>.<ExtensionTable> narrows the query down to a
single child table.
The displaycols is a comma-separated list of fields from the one-to-many table, and can
include any or all of the defined fields in that table. Two special ID fields may also be
referenced: ID and <CoreTableName>DCID. In the example above, this would be
STUDENTSDCID.
The fieldNames is a comma-separated list of the labels that should appear in the autogenerated table heading. These labels may contain spaces.
The type parameter specifies a format. Currently, the only valid format is "html".

Improving the Usability of Tlist_child and Tlist_standalone

Tlist_child and tlist_standalone will automatically format date fields, using the standard PS
Date Picker, and boolean fields, using a check box. All other fields will be formatted as input
boxes, about 20 characters wide. It is possible to format an input field to use a drop-down
menu, radio buttons, text area, or just static text.
To use any of the above input types, you need to include an external JavaScript file at the
beginning of the page, after the commonscripts wildcard. The code would look like:
<script language="JavaScript" src="/scripts/tlistCustomization.js"
type="text/javascript"></script>

Creating a Drop-down Menu in Tlist_child and Tlist_standalone

Once the external script is included, you can create a script below each tlist_child or
tlist_standalone. A drop-down menu would look like this, with different values for the value
and label:
< <script type="text/javascript">
var ValName = [];
ValName.push(['','Select a Value']);
Copyright 2014 Pearson

Customizations 501
ValName.push(['Value 1','Label 1']);
ValName.push(['Value 2','Label 2']);
ValName.push(['Value 3','Label 3']);
tlistText2DropDownValNamePair('FieldName',ValName);
</script>
The variable ValName can be any name but must be unique. The field name is matched to
the variable object in the tlistText2DropDown function.

Adding a Drop-down Menu with Values from a PowerSchool Table

Now that you can create a drop-down menu, lets extend that by using tlist_sql to create a
drop-down menu with values from a table in PowerSchool. This could be an existing table in
PowerSchool (such as the States table) or it could be a one-to-many or standalone table
that you have created.
var queryValues = {};
queryValues.push(['','Select a Value']);
~[tlist_sql;
SQL Query;]
queryValues.push(['~(column1)','~(column2)']);
[/tlist_sql]
tlistText2DropDown('FieldName',queryValues);

Adjust Input Field Display Lengths

Now go a step further. Because the new tlist functions create equally sized columns, about
20 characters wide, you will want to make adjustments so your table is more user-friendly.
You can fix that with CSS.
In both tlist_child and tlist_standalone tags, each input has a class named for the field it
represents. You can define styles to change the look of each of those classes. When you
define an input field, you can use the size parameter to define the box in characters. Using
CSS, you need to use pixels, so you have to do some figuring to determine the appropriate
width. Enter an approximate width, then use Firebug to determine the exact width desired,
and edit your page to use that new value.
<style>
.Zip {width:55px;}
.Phone {width:140px;}
.StartDate {width:90px;}
.EndDate {width:90px;}
</style>

Insertion Points and Page Fragments

Customizing PowerSchool has always been a great advantage for users. By customizing
pages you make PowerSchool work for your schools particular needs. The challenge in the
past has been in managing those customizations when updates were released. Once a page
was customized, updates to that page were no longer seen. This meant you had to track all
of your customizations and compare your list with the page change list in the release notes.
The other challenge was that you had to include all customizations on a single page. This
meant that if you had already customized a page and wanted to implement a new
customization that someone had written, you had to manually combine the two
customizations into one.

Copyright 2014 Pearson

Customizations 501
Page fragments eliminate both of these issues by using insertion points to insert custom
code into existing pages. Insertion points are special locations in the source code of a page
where customizers can more easily insert dynamic content (page fragments).
PowerSchool insertion points have the following characteristics:

The original source page does not have to be customized in order to add new content
to a page (this can help dramatically cut down on the number of updates when a
new version of PowerSchool is released)

Page fragments are inserted dynamically into the default source page

Multiple standard Pearson-provided insertion points can exist on a page

Additional insertion points can be added

You can physically move fragments around on the page using client-side DOM
manipulation

How It Works
Pearson has specified a set of standard insertion points. This set of insertion points is
expandable, but consists primarily of a small number of predefined places on the page. The
standardized insertion points are generally placed in common header and footer wildcards
and significant navigation menus. Below is a list of the more common files that contain
insertion points:
Wildcard

Explanation

admin_header_css.txt

The standard admin portal header for unframed

pages

admin_header_frame_css.txt

The standard admin portal header

admin_footer_css.txt

The standard admin portal footer for unframed

pages

admin_footer_frame_css.txt

The standard admin portal footer

teachers_nav_css.txt

PowerTeacher portal left navigation frame

guardian_footer_yui.txt

The standard parent/student portal footer

/admin/students/more2.html

Admin portal left navigation frame for student

pages

/admin/faculty/more2.html

Admin portal left navigation frame for staff pages

These insertion points allow a page fragment to be used for a single page or for multiple
pages in PowerSchool with minimal effort.
You decide which page(s) to customize and then choose an insertion point on the page.
With these two pieces of information, a page fragment file can be created on the local file
system (often referred to as the custom web root) or in the Custom Web Page Management
feature in the PowerSchool System Administrator application. When rendering the page,
PowerSchool will gather all the page fragments for that page and render them as inline
HTML with the page. Note that each insertion point may have multiple inserted page
fragments for any given page, and will all be rendered on the page.

Copyright 2014 Pearson

Customizations 501
Page Fragments
A page fragment is simply a snippet of content to be added to a target page. It could be
something simple like the following example:
<p>Hello world! I'm an auto-inserted page fragment.</p>
Or, a page fragment could be a complex combination of HTML code and JavaScript. Because
page fragments will be inserted into existing PowerSchool HTML pages, they do not require
any of the standard HTML <head>, <body>, or other tags. The main page contains those
tags already.

Standard Insertion Points

PowerSchool defines a set of standard insertion points available on every page. This means
that, typically, you never need to think about insertion points; the common ones will be
available to you. This also has a benefit in allowing standardized naming; you will not have
one page where the footer insertion point is called content.footer and another where it is
called content_footer.
The following is a list of common insertion points:
Insertion Point

Location

content.header

Right below the School and Term selection

content.footer

Near the bottom of the page, above the copyright

bar in the content area

leftnav.footer

Right below the left navigation but above any

PowerSource or Mobile App content

page.header

The last line in the wildcard commonscripts.txt

report.tabs

After the last </li>, before the </ul> in the report

tabs

student.alert

After the ~[studentalert] tag in the file

title_student_end_css.txt

The following example displays the first few lines of code from the admin_footer_css
wildcard:
<div id="cust-content-footer">~[cust.insertion_point:content.footer]</div>
<div id="legend" style="display:none;">
<h3>~[text:psx.txt.wildcards.admin_footer_css.legend]</h3> </div>
</div><!--end content-main-->
The first line defines an insertion point with a name of content.footer.

Special Cases
On the Visual Scheduler and Seating Chart pages, the content.footer will be hidden and
unsupported.

Copyright 2014 Pearson

Customizations 501
Auto-Insertions: How to Use Defined Insertion Points
An auto-insertion is simply the act of taking one or more defined page fragments and
dynamically loading them into the designated PowerSchool page at the specified insertion
points. There are two ways to define auto-insertions:

URL-based: The page fragment chosen is based on the URL (Uniform Resource
Locator) used by the browser to request the page from the system

Wildcard-based: The page fragment chosen is based on wildcards that are included
on the page using the HTML ~[wc:WILDCARD_FILE] syntax

These essentially operate identically. The only difference is in how the system constructs the
conventional file name to fetch the fragment from the file system or Custom Web Page
Management application. It is important to note that data validation and language
translation functionality can be applied to page fragments.

URL-Based Auto-Insertion of Page Fragments

When creating a page fragment, the name of that file is critical for proper operation. In
URL-based auto-insertions, the source page URL is used in constructing the name of the
page fragment. For example, the URL of the page to be customized is the following:
http://<server_address>/admin/some_directory/some_page.html
Note: The file's extension may be any of the typically used PowerSchool URL extensions,
including .html, .htm, and .action.
Upon processing a page with this URL, the customization module considers all of the
insertion points on the page, looking for a page fragment with the following path and name:
/admin/some_directory/some_page.FRAGMENT_NAME.INSERTION_POINT_NAME.txt
The page fragment file name is constructed from several parts:

/admin/some.directory A page fragment file must be placed in the same directory

as the source page's file

some_page Prefix must be the same as the name of the source page, without the
extension (for example, html)

FRAGMENT_NAME Any arbitrary name to help identify the page fragment and keep
its name unique. It is possible to insert multiple fragments into the same page
without having the fragments impact each other. If multiple page fragment
insertions are defined for a page, the insertion order is intentionally undefined.

INSERTION_POINT_NAME Must match the name of the insertion point to be used

in the page to be customized (for example, "content.footer")

txt Page fragments are always named with extension ".txt"

Example: District administrators have requested that a table with emergency phone
numbers be placed just below the What's New box on the Start Page. Examining the HTML
source code for /admin/home.html shows you:
</div>
~[wc:admin_startpage_whats_new]
</div>
~[wc:admin_footer_css]

Copyright 2014 Pearson

Customizations 501
The second to last line inserts the wildcard /wildcards/admin_startpage_whats_new.txt.
The last line inserts the wildcard /wildcards/admin_footer_css.txt, which begins with a
content.footer insertion point. If you create a page fragment and use the content.footer
insertion point on the Start Page, the table of emergency numbers would be displayed just
below the What's New box as requested.
This is the file name you should use for your page fragment assuming you use a fragment
name of "Emergency_Numbers":

The page fragment file would be placed in the /admin folder because that is the same
location as our targeted file, /admin/home.html.

Activity 1 Creating a Page Fragment

Create a simple page fragment and insert it into the Other Information page. This will
demonstrate the correct filename structure to insert content into the footer of a single
student page.
1. Log in to PS Administrator and navigate to Custom Pages
2. In the custom page directory, navigate to /admin/students
3. Create a new file by clicking Add and selecting Create File, and name the file
misc.00cf.content.footer.txt replacing 00 with your number
4. Click your file in the left navigation menu to make it active
5. On the Customized Page tab, enter the following (replacing 00 with your number):
<p>Content footer for 00</p>
6. Publish your page
7. To test your page, select a student and navigate to Other Information and look at
the bottom of the page for your insertion point

Wildcard-Based Auto-Insertion of Page Fragments

Wildcard-based auto-insertions are exactly the same as URL-based insertions, except for the
filename and location:
/wildcards/some_wildcard_name.FRAGMENT_NAME.INSERTION_POINT_NAME.txt
Note that the content will be inserted on every page where this wildcard is used. This means
you can cause the same inserted content to show up on many pages by associating the
content with a common wildcard file that is used on all of those pages. For example, since
admin_footer_css.txt is included on almost every PowerSchool HTML page, you can cause
content to be inserted at the bottom of almost every page by creating a file named:
Copyright 2014 Pearson

10

Customizations 501
admin_footer_css.EXTENSION_NAME.content.footer.txt
The page fragment file will always be placed in the /wildcards folder for wildcard based page
fragments.

Activity 2 Creating a Wildcard Page Fragment

Insert a page fragment into a wildcard, which will be inserted into all pages using that
wildcard. The page fragment should be deleted when the activity is over so it does not
interfere with later activities.
1. Log in to PS Administrator and navigate to Custom Pages
2. In the custom page directory, navigate to /wildcards
3. Create a new file by clicking Add and selecting Create File, and name the file
admin_footer_css.00cf.content.footer.txt replacing 00 with your number
4. Click your file in the left navigation menu to make it active
5. On the Customized Page tab, enter the following (replacing 00 with your number):
<p>Wildcard content footer for 00</p>
6. Publish your page
7. To test your page, navigate to the PowerSchool home screen and look at the bottom
of the page for your insertion point, then navigate to a different page and look for
your insertion point
8. Go back to Custom Page Management and delete your wildcard insertion point so the
training server pages are not cluttered

Creating Custom Insertion Points

You can add your own insertion points if you find that the existing ones do not fit your
needs. It is important to understand that once you add a custom insertion point, the page
you added it to is now customized and will need to be maintained when updates are
released. Because of this, it is better to use the existing insertion points if at all possible.
Note that the standard insertion points use this same naming scheme just in standard
header and footer files. To define an insertion point in the HTML of a PowerSchool page, use
the following tag:
~[cust.insertion_point:POINTNAME;DEFAULT_CONTENT]
The POINTNAME is required and is the name of the insertion point. It should be in dotseparated form, such as "page.header", "leftnav.footer", or "content.footer". When adding
your own insertion points to a page, be sure to use new, unique names.
The DEFAULT_CONTENT is an optional block of content that will be inserted in the page if no
insertions are found for this insertion point. This should be used rarely. If there is no
associated content with an insertion point on a page, the point should be invisible.

Copyright 2014 Pearson

11

Customizations 501
Activity 3 Creating a Custom Insertion Point
Duplicate the existing Demographics page and create a custom insertion point on the page.
Then insert content into this new point with a page fragment.
1. Using CPM, navigate to the folder /admin/students and find the
generaldemographics.html file
2. Click the Original Page tab, select all the code, and copy
3. Navigate to the folder /admin/00, replacing 00 with your number
4. Click the Add button, then click Create File, and name the file
generaldemographics.html
5. Select the file you just created, and paste your code into the page
6. Find the last <tr> tag in the table of student inputs
7. Insert a new insertion point after the last </tr> tag with a name of student.fields
The code will be:
~[cust.insertion_point:student.fields]
8. Publish your file
9. Now create your page fragment by clicking Add and selecting Create File, then
name the page generaldemographics.myfragment.student.fields.txt
10. Create a new student input field for locker number
An easy way to do this is to copy an existing student input field from <tr> to </tr>.
The final code will look like this:
<tr>
<td class="bold">Locker Number</td>
<td><input type="text" name="[01]locker_number" value="" size="5"></td>
</tr>
11. Publish your page and test to see if your fragment is inserted
Note: Because of caching, customizations may need to be turned off and back on to
see your page. Your instructor will do this for you.

Using jQuery Selectors

You have probably noticed that unless you want to insert your content in one of the
predefined insertion points, the use of page fragments is limited. This would be true if it
werent for JavaScript. By using JavaScript and jQuery selectors, you can place an object
almost anywhere on the page.
Before using jQuery selectors to place content, you must first understand the DOM. To help
explain the DOM, think of a simple HTML page. This page is made up of objects like the
head, body, tables, div, and span tags. These objects all have relationships: parent, child,
and sibling. The structure of these elements and their relationships is referred to as the
DOM. Using the DOM, you can identify objects by referring to their position in relationship to
another object. For example, you could identify the first child of a table. In many cases, this
may be the first <tr> tag in that table.

Copyright 2014 Pearson

12

Customizations 501
In the previous customization classes, you have seen the use of the ID selector, for
example:
$j(#someId)
This is probably the most commonly-used selector and provides direct access to an object
that has an ID. For example, to insert a new field before the home phone field, you could
use the following code:
$j(#fieldHomePhone).closest('tr').before(Some New Code);
This uses the ID selector in combination with .closest and .before to place Some new
code before the closest <tr> tag to the element with an ID of fieldHomePhone.
This may be the first time you have seen the selector .closest(). In the case of the
previous example, the ID is for the input of home phone. Since you do not want to insert
code in this input tag, the selector .closest() was used to find the nearest <tr> tag, and
insert the code before that tag. When using .closest(), the direction of the lookup will
always be up in the DOM.
In many cases, it is desirable to simply add additional fields to the end of a page. In
PowerSchool, most input pages are contained in a table with a class of linkDescList. This is
the class that provides the alternating white and blue lines. While on most pages, there
might only be one table, it is better to be safe and narrow down the table you want to insert
content into. Assuming there is only one table with a class of linkDescList, the following
code would add Some new code to the end of the table:
$j('table.linkDescList > tbody:last').append(Some New Code);
This example uses a class selector, which can also be very useful. The period in front of
linkDescList indicates that you are selecting a table that has a class of linkDescList. As in
this case, jQuery selectors can be combined to narrow the selection of an object. If the
selector would have been $j('table) then all tables would have been selected. Similarly,
if the selector $j('.linkDescList) would have been used, then all elements with a class
of linkDescList would have been selected. By combining the two, you select any tables with
a class a linkDescList. You will also notice that this selector indicates to find the last
<tbody> and append the new code there. Again, in most cases, simply appending new
content to the end of the table would work, but if there were a table footer, then this would
cause problems. It is always best to be as specific as possible when using selectors. While
your code may work today, a future update may add new code that you did not expect, and
which would break your customization.
Common jQuery selectors when working with PowerSchool pages are:
Selector

Example

Selects

Element

$j(input)

All <input> elements

#id

$j(#fieldDOB)

The element with the ID fieldDOB

.class

$j(.linkDescList)

All elements with the class

linkDescList

:first

$j(tr:first)

First <tr> tag

:last

$j(tr:last)

Last <tr> tag

Copyright 2014 Pearson

13

Customizations 501
Selector

Example

Selects

parent > child

$j(div > table)

All <table> elements that are a

direct child of a <div> element

parent descendant

$j(div tr)

All <tr> elements that are a

descendant of a <div> element

closest

$j(#fieldDOB).closest(tr)

Travels up the DOM from the

element with ID fieldDOB to the
nearest <tr> element

While it is not possible to cover every possible combination of selectors, the goal of this
class is to introduce you to the use of selectors for inserting page fragments exactly where
you want them. For a full list of selectors, visit the jQuery website at:
http://api.jquery.com/category/selectors/

Activity 4 Appending a Custom Insertion Point

Using your custom Demographics page, create an insertion point that will insert the
homeroom field at the end of the existing input fields.
1. Using CPM, navigate to your folder admin/00 replacing 00 with your number
2. Create a new file named generaldemographics.homeroom.content.footer.txt
This will be inserted into the file in the same directory named
generaldemographics.html at the content.footer insertion point.
3. Create a new div that is hidden and has an ID of homeroomContent
While the ID can be anything, it is good to use the name of the fragment in the ID to
avoid future naming conflicts. This is done because you do not want to see the code
before it is inserted. The code will look like this:
<div id="homeroomContent" style="display: none">
</div>
4. In this div, create a new table with an ID of homeroomTable, and inside the table,
create opening and closing <tbody> tags
The code will be:
<div id="homeroomContent" style="display: none">
<table id="homeroomTable">
<tbody>
</tbody>
</table>
</div>

Copyright 2014 Pearson

14

Customizations 501
5. Create a new table row with the label and input box for homeroom
The final code will be:
<div id="homeroomContent" style="display: none">
<!--content to be appended to table-->
<table id="homeroomTable">
<tbody>
<tr>
<td class="bold">Home Room</td>
<td><input type="text" name="[01]home_room"
value="" size="25" id="fieldHomeRoom"></td>
</tr>
</tbody>
</table>
</div>
6. Next, create opening and closing <script> tags with a document ready function in
them, like this:
<script>
$j(document).ready(function() {
});
</script>
7. In the document ready function; use jQuery selectors to copy the body of the table
above, to the end of the main table
The code will be:
<script>
$j(document).ready(function() {
$j('table.linkDescList >
tbody:last').append($j('#homeroomTable > tbody').children());
});
</script>
8. Finally, clear the content of the hidden div with the ID of inserted_content
This is done so there are not two elements with the same ID on the page. The code
will look like this:
<script>
$j(document).ready(function() {
//Insert data at the end of the table
$j('table.linkDescList >
tbody:last').append($j('#homeroomTable > tbody').children());
//Delete content from inserted_content div
$j('#homeroomContent').empty();
});
</script>
9. Publish your page and test

Copyright 2014 Pearson

15

Customizations 501
Creating Plugins
Create plugins as a way to package customizations into a single file. Similar to zipping files
for importing into the Custom Page Management, this will zip the files you select, but will
also include the XML files necessary to create table extensions so you can package all the
files necessary for a customization into a single zipped file. This file can then be installed as
a plugin on another PowerSchool server. Once installed, the plugin can be enabled or
disabled as a package making it easy to turn an entire customization on or off.
When creating a package, there are multiple fields to complete. Below are each of those
fields and a description:
Field

Description

Plugin Name

Enter a name for the plugin file.

Plugin Version

Enter the version of this plugin file.

Plugin Description

Enter a description of the plugin.

Publisher Name

Enter the name of the person who is creating this plugin.

Publisher Contact
Email

Enter the contact email for the person creating this plugin.

Plugin File Name

Enter the file name for the plugin. The .zip extension will
automatically be added.

Select Individual
Files

Navigate to and select the files to be included in the package.

Only modified or added files appear. The list includes web files
and exposes the schema root so database extensions also appear.
When a file is selected, it appears in the Selected Files box.

Select Files By
Search Mask

Enter a search term and click Search. All files matching the term
appear in the Selected Files box.

Selected Files

A list of all selected files appears. Click Remove Selected to

clear all selections from the list.

An important note when creating the zip file: Disable the browser preference to open safe
files after downloading before creating the .zip file. Otherwise, you will have to re-zip the
package files before you import the package on the Plugin Install page.
Known issue note: When a plugin containing a database extension is installed or modified,
you must restart PowerSchool/PowerTeacher and ReportWorks services. To restart these
services, open the PowerSchool Installer. On the Start Page, click Restart ReportWorks
Services and Restart PowerSchool/PowerTeacher Services.

Copyright 2014 Pearson

16

Customizations 501
Installing a Plugin
Plugin Management is used to import, house, and manage packaged database extensions
and web customizations. You can import zipped plugin packages that contain a plugin
definition file and at least one database extension or web file.
The plugin package can include one or more of the following file assets in the .zip file:

Database extension definition

XML files

Custom pages

Page fragments

Page fragment meta files

Image files (GIF, PNG, JPEG, JPG) or PDF files (PDF)

CSS files

JavaScript files

Other web directory artifacts

Because a plugin can only be installed once on a server, your instructor will demonstrate the
process for installing a plugin. Below are the steps you would follow to install on your own
server.

How to Import a Plugin Package

Use the following procedure to import a plugin package from another PowerSchool system.
1. Sign in to PowerSchool
2. Navigate to System > System Settings > PluginManagementConfiguration
3. Click Install
4. Click Browse and locate the .zip file that contains the plugin package and click
Open
5. Click Install
Note: If the asset file(s) you are importing already exist(s) in the Custom Web Page
Management site structure, it is considered an error and the existing file will not be updated
with the new content. This is to help ensure that different plugins do not overwrite each
other.

Important Information on Plugin Package Enable/Disable/Delete

When the Disable function is selected for a plugin on the Plugin Management Dashboard, all
associated assets (database extensions, page customizations, etc.) are disabled as well.
Custom pages and files associated with a plugin package will not be served from the Custom
Web Page Manager while a plugin is disabled. Currently, PowerSchool does not have a
mechanism to indicate if a custom page is associated with a plugin when viewed in the
Custom Web Page Manager.

Copyright 2014 Pearson

17

Customizations 501
When the Delete function is selected for a plugin on the Plugin Management Dashboard, all
file assets associated with a plugin are deleted. However, deleting the plugin will not delete
any tables and fields from the Oracle database that were created by a database extension
definition.

Key Points

Database Extensions Remember to plan and test thoroughly

One-to-One Table Extensions Add a new data element to a parent table

One-to-Many Tables Create a child table that is designated to a parent table

Standalone Tables Create a table that is not directly related to another table

Page Fragments When used with JavaScript and jQuery, you can create custom
pages that are not affected by updates or other customizations

Plugins Used to package database extensions and page fragments into a single
package that can be easily shared and enabled or disabled as

PowerSource Resources

System Administrator User Guide, Article #63495

Database Extensions Visual Walkthrough, Article #70768

New in PowerSchool 7.9: Database Extensions, Article #70809

Upgrade to Database Extensions in PowerSchool 7.9, Article #70810

Database Extensions FAQ, Article #71966 Database Extensions Best Practices, Article
#71545

Advanced User Guide for Database Extensions, Article #70667

Copyright 2014 Pearson

18