Insertion points are special locations within the source code of a page where customizers can more easily insert
dynamic content (page fragments). PowerSchool insertion points have the following characteristics:
-
With insertion points, the original source page does not have to be customized in order to add new content to that page.
This can help dramatically cut down on the number of custom pages that need to be created and subsequently updated when
a new version of PowerSchool is released.
- Page fragments can be dynamically inserted in to the default source page.
- Multiple standard Pearson-provided insertion points can exist on a page, and new insertion points can be added.
- You can physically move fragments around on the page using client-side DOM manipulation via standardized meta-data.
- You can customize every existing and new page in PowerSchool.
Several core PowerSchool pages and wildcards now have custom insertion points that can be leveraged to insert custom content.
custom insertion points will have the following format:
~[cust.insertion_point:pointname]
The following code is an example a custom insertion point as it exists on the student pages' left navigation menu
(admin/students/more2.html)
<div id="cust-leftnav-footer">~[cust.insertion_point:leftnav.footer]</div>
An auto-insertion is simply the act of taking one or more defined page fragments and dynamically loading them
in to the designated PowerSchool page at the specified insertion points. The page fragment chosen is based on the
URL (Uniform Resource Locator) used by the browser to request the page from the system.
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:///admin/some_directory/some_page.html
Upon processing a page with this URL, the customization module considers all the insertion points on the page, looking for a page fragment with the following 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 (i.e. html)
-
FRAGMENT_NAME - any arbitrary name to help identify the page fragment and keep its name unique.
PowerSchool allows multiple fragments to be inserted in to the same page without impacting 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 (i.e. "content.footer")
- .txt – page fragments are always named with extension ".txt"
Example: To insert a page fragment into the student left navigation menu custom insertion point (called leftnav.footer) shown above,
the following file would need to be created.
/admin/students/more2.student_navigation_insert.leftnav.footer.txt
The fragment name shown in the above example (student_navigation_insert) can be any descriptive value that the developer chooses.
The rest of the file path and file name must be configured exactly as shown to successfully insert the page fragment into the insertion point.
When adding custom content to a page that has no custom insertion points defined, the developer may choose to modify the page by
inserting custom content where desired. Alternatively, the developer may choose to define custom insertion points in the page
and leverage those insertion point to include custom page fragments. The later of the two options is recommended as it simplifies
maintenance of custom pages as new versions are released in PowerSchool updates.
Sample Page Fragment Code
<table>
<tr id="trIdentifier">
<td>Column 1</td>
<td>Column 2</td>
</tr>
</table>
<script type="text/javascript">
$j(document).ready(function(){
$j('tr:contains("target text")').after($j('#trIdentifier'));
});
</script>
In the example above, we are adding a table row to a page via a page fragment.
First, a table is placed in the fragment containing a table row with an id attribute.
The value of the id should be descriptive and unique.
The javascript on the page to moves the table row (based on the id) to a desired location.
This is known as DOM manipulation.
The $j(document).ready() function ensures that the code will not run until the page has finished rendering.
$j('tr:contains("target text")').after($j('#trIdentifier'));
The first part of the DOM manipulation line will identify a target
on the page.
Replace target text with some text contained within the target element.
$j('tr:contains("target text")').after($j('#trIdentifier'));
after() is a jQuery function that indicates we want to place something after the element matched by the first part of line.
$j('tr:contains("target text")').after($j('#trIdentifier'));
The code within the after() function indicates the element that should be moved to the selected location.
Useful jQuery functions for DOM manipulation
- $j().before()
- $j().prepend()
- $j().append()
- $j().after()
.before()
.prepend()
.append()
.after()
~[x:insertfile;footer.html]
~[wc:admin_footer_css]