Monday, May 05, 2008

PIA_KEYSTRUCT JavaScript Object

I was just looking at the JavaScript that PeopleSoft includes in each PIA page and noticed a JavaScript object I have not seen before: the PIA_KEYSTRUCT object. It looks like this object contains key/value pairs for each level 0 search key, primary and alternate. What can you do with this? I'm not sure yet. I've been thinking about it for a couple of weeks. My two main questions:

  1. Can I use this to create new developer tools (bookmarklets, etc)?
  2. Can I use this to empower users?

For now, the only example I can show you is how to open a query and pass in the PIA_KEYSTRUCT values as query bind parameters. This example passes the Role Administration component's ROLENAME key to a delivered query that displays the role's permission lists. Here is the JavaScript:"/psc/portal/EMPLOYEE/EMPL/q/?ICAction=ICQryNameURL=PUBLIC.PT_SEC_ROLE_CLASS&BIND1=" + escape(frames['TargetContent'].PIA_KEYSTRUCT.ROLENAME))

In the example above, I navigated to PeopleTools > Security > Permissions & Roles > Roles and ran this JavaScript in the Firebug console. Here is a bookmarklet that will do the same thing: Role's Permission Lists. To test this bookmarklet, right click the link and save it as a favorite/bookmark, navigate to your Role administration page, select a role, then activate your new favorite/bookmark. One of the great features about bookmarklets is that they can be added to your browser's links toolbar to "extend" the functionality of your browser. Unfortunately, this particular example is page specific. This particular bookmarklet and code will only work if you are on the PeopleTools Role administration page. Furthermore, you can provide the same functionality by combining PeopleCode with JavaScript in an HTML area or, even better, using a Pushbutton/Hyperlink on a PIA page with full access to the level 0 search keys (in other words, this is a great pedagogical example with little practical value).

Really, as developers, can we obtain practical value from this little piece of JavaScript that the PeopleTools developers generously provided for us? I think so. Here are a couple of ways I think we can leverage this piece of JavaScript:

  • Enhance the Ctrl-J page by adding the level 0 search keys
  • Simplify the Pagelet Wizard link creation process


Madanagopal said...

Hi Jim,

Saw your post on PIA_KEYSTRUCT javascript variable on each PIA html. I know something

about this. I am not sure if you have come across a feature called Context Manager in

PeopleSoft Enterprise Portal.
Let me briefly explain this functionality. When you navigate to a cref, say a hrms cref

that lists the company names, it will be nice if you can show a brief history of the

company, stock code symbol, yearly turnover etc, that helps the user to know something

about the company on hand. This is what Context Manager is doing.

It just uses the component level 0 search and alt search keys to identify the target page

keys and show relevent information in the form of template pagelet in left navigation

Template pagelets are usually to be written by the admin user who decides what kind of

information to show in the left frame. Admin user writes his template pagelet code such

that it reads this PIA_KEYSTRUCT variable (this variable will contain company name/id on

company name cref)use this level 0 key values to find/query the company information table

in hrms to get some relevent information of the company (selected on the target frame)

and show this info as a template pagelet in the left frame. This template pagelet can be

a simple iscript function. Once you complete your template pagelet code, then define it

under PeopleTools> Portal> Structure and Content> Portal Objects> Template Pagelets and

provide appropriate permission to this iscript function.
Once your templatepagelet is registered in the Portal Registry, it will be available for

Context Manager feature to use. Once important thing to remember is that, this Context

Manager feature uses a different template called Dynamic template that reloads the left

frame with the relevent information pertaining to the target frame level 0 keys and it

repeats the same whenever a new level 0 key is selected on the target frame. NOTE: If you

are using Context Manager functionality, you donot need to read the PIA_KEYSTRUCT

variable from the PIA html. Context Manager framework reads it and gives it in the form

of an App class method result. Context Manager App class is EPPLN_TEMPLATE_PAGELET:TPRequest and methods GetTCKey and GetTCKeyValue.

You can find more detailed information on the PeopleSoft Enterprise Portal peoplebooks.

Hope it helps.


Brady said...


Are you aware of any method to control/maintain the operators (=, between, <=, etc) on a component search page when a user selects 'Return to Search'? I have code that preserves non-key search values, but the operators always get set back to whatever the default is for the field type.


Jim Marion said...

@Brady, I am not aware of a delivered method for controlling the comparison operator. I have some ideas though. If my idea is simple, I'll post the response here. If it is complex, I'll post it in my regular blog and include a link here.

Jim Marion said...

@Brady, I still haven't found a solution for you. I can't find any easy, delivered solutions. I have considered a JavaScript solution.

With a JavaScript solution, you would need to inject a JavaScript library containing rules, etc for each component and field. You can see various global injection techniques on my blog. My latest, preferred method of injection: Injecting JavaScript Libraries into PeopleSoft Pages. Once you have a JavaScript library loading on every PeopleSoft page, you can parse the JavaScript variable strCurrUrl to determine the component. You can use the existence of <input type="button" id="#ICSearch"...> to tell if you are on a search page. The search operator drop-down is identified by the name RECORD_FIELD$op.

I haven't written or tested a solution for this. These are just some pointers to help you if you are interested in writing a solution.

Brett B said...

I suspect PIA_KEYSTRUCT is a key element of how popup pages work. I haven't run a full trace but I bet that string is passed into that popup modal.