Using the Notepad plug-in with FSI Pages

Setting up the notepad plug-in

To start using the notepad plug-in in your FSI-Viewer, you must first edit your configuration file for your FSI Pages instance (*.xml). Each image collection used with the notepad plug-in must have a custom, unique ID set in the configuration file. Using the same or no unique ID with several image collections (catalogs) will present unrelated bookmarks in the notepad.

You might want to look at the sample configuration file “notepad.xml” below:

Note, how the parameter ‘UniqueID’ is set in the configuration file. As mentioned above, each configuration file should have a different UniqueID set.
Please use characters and letters for the UniqueID value only and do not use the following characters : [Space] ~ % & ; : ” ‘ , < > ? #.

Once you have added these lines to your configuration file, FSI Viewer will present the notepad button in the user interface.
(You may need to restart your bowser or empty the browser cache to see the new button.)

This adds single user notepad functionality to your on-line catalog. The bookmarks in the notepad will be stored client side, similar to a cookie, so that the bookmarks are available the next time the user opens this instance of FSI Pages.

Clicking the button brings up the bookmark window. The user can now use the buttons in the lower left corner of the bookmark window to bookmark entire pages, links or even certain areas of a single page.

 

Advanced Feature: Sending Bookmarks by email

You might have noticed the yellow e-mail icon when the bookmark window is opened in the example above. Using the “EnableSendBookmarks” Parameter, the following optional steps can be done, to enable users sending their custom bookmarks to another user by email. From a technical point of view, the user sends an email containing a reference to the bookmark data by e-mail rather than sending the actual data. Enabling this feature requires a little server side scripting, as FSI Viewer cannot store files or send emails on his own. You can find script samples in PHP below that could easily be created in other server side scripting languages as well. An archive containing all required scripts and configurations is available for download at the very bottom of this page.
The figure below illustrates how sending bookmarks by e-mail works:

This requires a few additional things that have to be set up:

  • Enable the option to send the bookmarks by mail (EnableSendBookmarks)
  • Have a server side script to retrieve and store the bookmark data on the server (SendXMLStoreURL)
  • Have a server side script to actually send the email (SendXMLUrlSuccess)
  • Have some error fallback HTML document (SendXMLUrlFailed)

The FSI configuration file with these features enabled should look like this:

Please note, how the ‘%%serverresult%%‘ variable is passed on to the javascript. This is the space holder for either the filename of the stored XML-file or the error message returned by the server side script. The JavaScript used in the .xml is listed below.

Technically, FSI Viewer posts the bookmark data to the URL defined using the SendXMLStoreURL parameter.
That URL must end up at a little server side script which retrieves that data, writes it to an XML file and returns the filename of that file (<result success=”true”>$filename</result>), or an error message (<result success=”false”>Could not save file</result>) in XML format.

The PHP example script below illustrates how a script like that looks like:

When the user clicks the “send bookmarks” button, FSI Viewer posts the bokmark data to the getdata.hml document above and checks the result the script returns.
Subsequently FSI viewer opens either

  • the page defined by the SendXMLUrlFailed parameter, if anything went wrong and FSI Viewer got<result success=”false”>(errormessage)</result> as a result,

or

  • the page defined by SendXMLUrlSuccess, if <result success=”true”>filename</result> was returned.

FSI Viewer hands the retrieved info over to the result HTML page in ‘%%serverresult%%’, which we added to the JavaScript in the .xml-file and which is being passed on to the script via HTTP GET (success.html?xmlfile=%%serverresult%%).
Unless an error occurs when saving the XML data, eg. a wrong path or something similar, FSI Viewer will redirect to the SendXMLUrlSuccess address, which displays a form to actually send the email containing the hyperlink to the recipient.

The PHP example script below contains the form and script to send the email. Of course this document can be adjusted to your needs regarding content and design:

 

In the case something went wrong while retrieving and storing the data on the serverside, the SendXMLUrlFailed page is loaded instead to inform the user about the error. Please see a corresponding PHP script to output the error below:

Once the user sent his bookmark reference to someone else, that user gets an email which contains a link to the catalog along with a reference to the XML file containing the actual bookmark data.

Example:

http://www.fsi-viewer.com/bookmarks.html?dataref=foo.xml

The sample server side script below reads the “dataref” reference to the stored XML file from the link’s query and adds the parameter ‘Notepad_LoadXML=filename’ to the FSI Viewer query dynamically.

 

The “LoadXMLPrefix” parameter added in the file above is needed, to determine the full path of the XML-filename on the web server that has previously been stored (see “getdata.html” script above). The path has to be accessible by the browser, so that the recipient’s browser can load the bookmarks from this XML-file. With ‘Notepad_Visible=1’ set, the Notepad is shown right after the FSI Viewer has loaded.

Files used in this tutorial

If you want to enable the “Send bookmarks by email” feature on your server, you might want to download the following archive containing all required configurations and PHP scripts. If you are running a server supporting PHP, you can just copy the files to your web server and edit all URLs in the files beginning with “sample”.

sendbookmarks_ressources.zip