Admin's Got a Brand New Widget
I've got time for one last Version 11 article before Version 12's release, and while it isn't a ton of code, it's a whole new feature you can provide for administrators. A 'Bookmarks' widget that appears under the admin navigation menu that provides a saved list of links back to specific profiles, programs, and applications.
I couldn't keep this one to under 4000 characters so it involves having to implement changes in a few different places. You're going to be adding script, style, and hidden input tags to a handful of text interface fields. You will also be uploading a javascript file to the document center. Here are the instructions for implementing the feature:
This implementation involves downloading and saving two files to your local drive:
AdministrativeBookmarks.html - Script and style tags that you will be embedding in your text interface
AdministrativeBookmarks.js - JavaScript file that you will be uploading to your Document Center
Both of these files are stored in the GitHub repository.
Upload the javascript file to the doc center
The file 'AdministrativeBookmarks.js' is a JavaScript file that has all the various functions that build, add, and delete bookmarks on your site's pages. It will only be loaded in when it needs to be, but in order to make it available, you'll need to upload it to Website Admin -> Document Center as a file.
Don't copy/paste the content into the WYSIWYG Editor when adding it to the Document Center; it should be uploaded using 'Option 2' on that page so that it appears in the document center as type 'JS'.
Get the URL of the javascript file and put it into the script
After you've uploaded the JavaScript file, you'll need to right-click on the filename and get the URL of the file on your site. It will be URL that looks like this:
http://studyabroad.terradotta.com/_customtags/ct_FileRetrieve.cfm?File_ID=6291
Now, you'll need to open up the HTML file you downloaded (AdministrativeBookmarks.html) in a plain-text editor and change the following line:
var bmjsurl = "#DOC CENTER OBJECT URL OF THE BOOKMARK SCRIPT#";
You'll need to paste in the URL of the Document Center JavaScript object but without the 'http:'. The end result should be something like this:
var bmjsurl = "//studyabroad.terradotta.com/_customtags/ct_FileRetrieve.cfm?File_ID=6291";
Add the script to the text interface
That modified version of AdministrativeBookmarks.html should be appended to text interface field #1161 ('Admin Home' link in the logged-in user line of the page).
NOTE: This is one of those one-liner text interface fields, so you'll need to edit the interface field twice to get it to stick properly.
Add the input tags to the text interface fields to identify bookmark-able pages
Finally, there are three text interface fields that you'll need to edit. You'll be adding a hidden 'input' tag to each of them so that when the script runs, it can find out if you are on a page that can be bookmarked by an administrator.
Add the following to text interface field #5066:
<input type="hidden" id="bookmarkable" value="YesA">
Add the following to text interface field #13701:
<input type="hidden" id="bookmarkable" value="YesU">
Add the following to text interface field #8544:
<input type="hidden" id="bookmarkable" value="YesP">
Now, whenever an administrator is in the program builder, application admin interface, or profile admin interface, there will be an 'add bookmark' button just under the admin tool navigation menu. Clicking on that button will create the widget of 'Bookmarks' that appears on all their pages. They can then click on the bookmark to return to that page they bookmarked.
When an administrator is logged in, the 'Admin Home' link contains the script that will, first, check to see if localstorage is available on the browser. If it is available, it is then checking a couple things to see if the additional bookmarking JavaScript is needed. This includes seeing if the user has bookmarks stored in localstorage that need to be rendered and then, if the page that the user is currently on is one that can be bookmarked (checking for those 'input' tags we added to the interface in the last step).
If it turns out that the bookmarking feature functions are needed, it uses this line of code to import the JavaScript file you uploaded to the Document Center:
$.getScript(bmjsurl, function() {
Once it is done loading that script, it will execute the necessary functions to build the bookmark widget (if necessary) and add the button for bookmarking the page (if necessary).
As I mentioned before, the details of the bookmarks are kept in the browser's localstorage. So this means there is a limiting aspect to this widget's functionality. When an admin stores a bookmark, it will only appear for that admin when using the browser in which it was stored. I can't bookmark a bunch of pages at work, go home, and login to the site there and expect to see my bookmarks. They've been saved in my work browser's cache, and I won't see them until I go back to work and login with my browser there. However, as a simple little tool that you can use to stick an application or program off to the side of your page so that you remember to get back to it later, it can be pretty useful. I could see this being easier than having multiple browser tabs or windows open and having to click through them to location the page you're looking to find.
Another little caveat, there is not anything in the code that makes this specific to your site. So if you happen to operate in multiple accounts that have this feature implemented, you might get some strange results... basically, you'll see all your bookmarks in both sites and clicking on the bookmark from another site will take you over to that other site.
This is because of the way that the data is being stored. You can take a look at it by going to your browser's console and entering localStorage. There is one key/value pair in localstorage that will look like this:
BM|SteveSweitzer: "P1317|A7801|A7802|U2070"
(except with your name of course)
This is how it identifies your bookmarks. It checks for your name on the page, and then, it loads in the list of ID#s that you've got stored (along with what type of record each is). For each of these ID#s, there will be a key value pair that looks like this:
U2070: "Penumala, Sashidhar|http://studyabroad.terradotta.com/index.cfm?FuseAction=ProfileAdmin.ProfileEdit&userid=2070"
This is the actual bookmark data. The first node or two is going to be the name of the user or program information, and the last node will be the URL of the page that was bookmarked.
This would be why if you logged into another site with the 'bookmark' feature implemented, you would see the same bookmarks there ... so long as your name on the site is the same.
It wouldn't be a radical bit of code without a little bit discussion about the security issues involved.
As mentioned before, this is using the localStorage API in HTML5 to store a list of program, application, and user id#s along with an profile/application/program name, and URL that will take you to either the program builder, application admin, or profile admin of those users. This data is not encrypted or under any sort of authentication. If someone were to get physical access to your browser, they would be able to navigate to your site's domain, go into the console, and read these things. In addition, it is possible that there could be a security hole in the localStorage API that permits another domain to read the data stored there.
Is this reason for being scared? Not really.
While it would permit someone to see the URLs, they won't be able to navigate to those locations unless they are logged-in and already have permission to get to those locations. So these URLs are still subject to all the security checks and restrictions that are normally in place when using the site.
There two aspects of this which might be considered suspect. One is that it is revealing the URL structure that can be used to access specific pages and data... but that's something the software really doesn't obfuscate. If that were to change in the future, this widget might require re-engineering. The other is that it does store applicant names in localStorage in association with programs and app cycles. However, it doesn't include any personally identifying information like email address or date of birth.
It is possible that you might have some difficulty getting this to work. If you do, it is most likely because of one of two things:
1.) Your layout doesn't have the same navigation column structure and the widget isn't rendering properly.
This is the line in the script that places the container for the widget:
$("#leftColumn").append(bm_container);
It is possible you don't have a section with the ID of 'leftColumn'. So the widget isn't going to appear as intended because it is not ever being place in the browser window. All you need to do is use your browser's page inspecting tools to find the most appropriate container and replace the selector '#leftColumn' in that line with your layout's proper container ID.
2.) You've encountered a bug - and now your localStorage cache has something in it that is causing the widget to fail.
As much testing as I've done on this, I'm sure it isn't bulletproof. There are likely some ways that an improper URL or ID# can get caught in the mix and result in the page not being able to render the widget.
When this happens, the best thing to do to get things back to square-one is to clear out the localStorage cache for the domain. This can be done by simply going to your browser's console and running the following line:
This will empty out the contents of your localStorage and allow it to be rebuilt by the widget. If you are confused by what I mean by "going to your browser's console", I would recommend learning about the developer tools that are included in your browsers these days and how to turn them on. They can be incredibly helpful in troubleshooting rendering issues, but they are also really great ways to just learn more about how your pages function in a more general sense.
My favorite at the moment is Chrome, and Google provides detailed instructions for using the console in their developer documentation.
This has been tested in Version 11.