Fields: Add/Edit/Copy HTML Widget

The Add/Edit/Copy HTML Widget page lets you insert code that can act on selected search fields into a search result display or detail display. The code is HTML and Javascript that allows the user to act on the information in the display to perform a function.

How to get here in Portfolio

Displays > HTML Widgets > Add HTML Widget

Displays > HTML Widgets > Edit HTML Widget

The widgets that you define here are made accessible in the Manage Search Result Display and Manage Detail Display lists to be assigned to specific displays. For more information, see Fields: Search Result Displays and Fields: Detail Displays

	You should have a moderate understanding of HTML and Javascript before attempting to create an HTML widget.

Type

Specifies how the widget is presented in the display. When you specify a type, the options available for the widget change. You can assign one of the following types:

Standard: Specifies that the widget launches with the display.
Button: Specifies that the widget is launched by a button in the display. The button is placed below any default buttons (that is, buttons such as Place Hold, that are part of Portfolio), and if there are multiple widget buttons, they are arranged in the order defined in the Configure HTML Widgets page for the display (for more information, see Fields: Configure HTML Widgets).
Drop-down Option: Specifies that the widget is launched from the Select an Action menu in the display. The widget option text is placed below any default options (that is, options such as Place Hold, that are part of Portfolio), and if there are multiple widget options, they are arranged in the order defined in the Configure HTML Widgets page for the display (for more information, see Fields: Configure HTML Widgets)
Script Only: Specifies that the widget requires only the JavaScript code that launches with the display. The HTML Content box does not appear when the Script Only is selected.

Note: When editing an HTML widget, you can change the widget from one type to another. Any functions not pertaining to that type are hidden and will not effect the functioning of the widget, even if they had text or code in them. If you are changing between a button and drop-down option type, the text for button or drop-down option will remain as text for the other type.

Code

Specifies a unique code for the HTML widget (up to 30 characters). This code is used to identify the widget on the HTML Widgets page and on any other pages that display the HTML widget code.

Codes are displayed in all upper case letters. If you enter lower case alphanumeric characters for the code, the software automatically converts them to upper case when the code is displayed.

Note: This value must be unique. If you enter a code that is already being used elsewhere on the system and try to save the widget, the software displays an error message indicating that the value must be unique, and informing you that the value you entered is already being used for another widget.

Note: If you copy a delivered widget that has "SIRSI_ERC" in the code, you must include both "ERC" and the suffix from the copied widget this field. For example, if you copy the SIRSI_ERC_PREVIEW widget, you need to include "ERC_PREVIEW" in this field.

Name

Specifies the system name of the HTML widget (up to 80 characters) for the specified language. This name is used to identify the widget on the HTML Widgets page and on any other pages in the Admin console that display the HTML widget name.

For this field, you can also specify an alternate name for a specific language. Choose the language from the drop-down list of supported languages, then enter the localized name in the field.

Note: If your web browser is configured to use a display language that is not supported by Portfolio and you have chosen to display the Admin console in a language other than the default language (en_US), the language that displays in the drop-down list of supported languages defaults to US English.

If a localized name already exists for a specific language, the software displays that language name differently in the drop-down list. When you enter a localized name for a specific language, the language name appears with a “++” suffix. If you clear the localized name for a specific language, the software displays the language name without the different formatting.

Compatibility

Specifies whether the widget is enabled for Desktop Only, Mobile Only, or both Desktop and Mobile.

Note: You must have the mobile theme enabled on the search profile for this setting to apply.

Description

Specifies a text description of this widget (up to 255 characters).

Important: The descriptions for widgets that come with Portfolio may include information for setting up the widget in your system. Further information about configuring the widget can be found in the HTML Content and Custom JavaScript text within the code.

Button Text

This field displays only when the Button Type is selected. It specifies the text (up to 80 characters) that appears on the button that starts the Javascript.

Drop-down Text

This field displays only when the Drop-down Type is selected. It specifies the text (up to 80 characters) that appears in the drop-down menu in the search results and My List. Selecting the text from the drop-down starts the Javascript.

Image URL

This field displays only when the Drop-down Type is selected. It specifies the URL of the image (up to 255 characters) to display to the left of the drop-down text. You can use a URL for any image your library can access, or you can upload an image using the File Uploading tool and copy the URL to the Image URL text box.

Note: The list displays image at the actual size. Large images will affect the size of the drop-down and the spacing between options. The optimum size of an image for the drop-down list is 25 x 25 pixels. If you do not specify an image, the area to the left of the option remains blank.

For this field, you can also specify an alternate name for a specific language. Choose the language from the drop-down list of supported languages, then enter the localized name in the field.

Select fields for use in Widget

Specifies which fields the HTML widget can work with. The widget can act on only the fields that you select. For example, if you are creating a bibliography citation widget, you would want to include the Author and Publication fields, along with others.

	If you select the fields in the HTML widget but do not activate the fields for use in the Search Results Display or Detail Display, the values for the fields will not be available in those displays. For more information on activating fields in the displays, see Adding or editing a search field.

Available

Displays a list of all the available fields in the system.

You can select or multiselect one or more fields and then click Select, or you can double-click individual fields to move them to the Selected list.

Selected

Displays the list of fields can be searched and used by the widget.

You can select or multiselect one or more fields and then click Remove, or you can double-click individual fields to move them to the Available list.

To add or remove fields in the list, choose the field, and then use these buttons:

Option	Description
Select	Moves the selected field from the Available list to the Selected list.
Remove	Removes the selected field from the Selected list and returns it to the Available list.

Option

Description

Select

Moves the selected field from the Available list to the Selected list.

Remove

Removes the selected field from the Selected list and returns it to the Available list.

Note: These buttons are context-sensitive based on which list a field is selected in. For example, the Remove option is disabled when you select fields in the Available list, but it is enabled when you select fields in the selected list.

Localized Strings

Any string defined here will be available for use in the HTML Content and Custom Javascript below. Previous to rendering on the page, any ${<CODE>} in either of those fields will be replaced with the current language's version of the string for that code. E.g. if you had a string with the code "ELEPHANT" with "gray" for the current language, then anywhere that "${ELEPHANT}" appeared in the Custom Javascript or HTML Content it would be replaced by "gray".

Add Row

Opens a row of fields for defining a new translatable string.

Code

Specifies a unique code for the translatable string (up to 30 characters). This code is used to identify the string within the HTML Content and Custom JavaScript of the widget.

Codes are displayed in all upper case letters. If you enter lower case alphanumeric characters for the code, the software automatically converts them to upper case when the code is displayed.

Name

Specifies the string (up to 80 characters) that will appear in the Searching interface when the widget is added to a display. The localized string that displays depends on the language that is chosen for the Searching interface and the language assigned to the string.

Remove

Removes the row of fields from the widget and deletes the string and all of the localized versions of the string from the system. To remove a single localized string, select the Language from the list, then manually delete all of the characters from the Name field.

For this field, you can also specify an alternate name for a specific language. Choose the language from the drop-down list of supported languages, then enter the localized name in the field.

HTML Content

Specifies the HTML code that will be used for the widget. The HTML Content editor is a raw HTML editor. You can type the code directly into the editor or copy raw code from a different source to paste into the HTML Content box. HTML content appears in the display either as part of a record in the search results or in the detail display, unless you specify that the HTML elements are hidden. When they do display, they display at the bottom of the record unless specified otherwise. Portfolio formats all visible HTML content according to the CSS enabled for the profile that patrons log in to.

	You can enter JavaScript into the HTML box; however, depending on the browser, the JavaScript may not run in the order you want. SirsiDynix recommends that you enter all JavaScript in the Custom JavaScript box.

Special tokens

You can use special tokens in the html to identify an item and whether it is in the result list or detail display. All instances of $RESULT_ID in the custom html is replaced by a string identifying the item. The string is composed of either “hitlist” or “detail” followed by the hit number. For federated search targets, the entry code follows the hit number. The token is also used to identify the hidden fields in the widget.

Bound JavaScript Function

Specifies the JavaScript function (up to 30 characters) that initiates the JavaScript in the widget. In the Custom JavaScript box you should have included a function that is called to start the JavaScript functionality. In the Standard type widget, this function is called from within the HTML code. For the Button, Drop-down Option and Script Only types, you specify the function in the Bound JavaScript Function box.

Custom JavaScript

The Custom JavaScript editor is a basic text editor. You can type directly in the editor or paste from a different program. The JavaScript can hook into any of the fields you have selected for use in the widget.

Bound functions receive a context from the page, indicating which item or items are selected. This is relevant to button, drop-down, and standard widgets. Button widgets receive the ID of the associated item in a string format, such as "detail0", when a patron clicks the button. Standard widgets receive a single string ID in this same fashion, but on page load rather than when a button is clicked. Drop-down widgets receive an array of these strings (one for each item selected in a list). For example, when a button widget is bound to the function called "showId" with the following JavaScript, the result would display an alert dialog box showing the ID of the item associated with the button that was clicked (that is, the item corresponding to the button in the item results display or detail display):

A field you selected for use in the widget (referred to here as a hidden field) is added to the document inside a div tag. That div tag contains a separate div tag for each value the field may have. These field value divs can be addressed in the JavaScript by using the widget’s resultId + "_" + the entry code of the search field. For example, the Format field, if included in the hidden fields and added to the hitlist, could be accessed using document.getElementById(resultId + '_FORMAT'). This would return the div that contains the value divs. These child divs that hold the values may be selected directly by class name, as well. The class name these child divs have is the entry code of the search field + “_value”.

Following on the previous example, if you had selected FORMAT as a hidden field, the following code shows how you could create a button widget with the bound function 'showFormat' that would display the FORMAT value of the item associated with the button:

jQuery works best for this, as you can select the specific elements without worrying about whether your widget is on the Search Results Display or Detail Display. However, care should be taken if a widget is added to both the Search Result and Detail Display, as both of the collections of values may be available in the document. The following jQuery example shows how to gather up all of a field’s values.

The full structure of how field values will be put into the document is as follows.

JavaScript

function showId(itemId) {
    alert(itemId);
}

function showFormat(itemId){
    alert(document.getElementById(itemId + '_FORMAT').childNodes[0].innerHTML);
}

function gatherAuthors(itemId)
{
    var authors = new Array();
    jQuery(‘div[id$=’+ itemId + ‘_AUTHOR div’).each(function() {
        authors.push(this.innerHtml);
    });
    return authors;
}

Search Result Display hidden field value locations

<div id="[resultIndex]_hiddenFields" class="hidden">
    <div id="[resultIndex]_[field1CodeName (spaces replaced with _)]">
        <div class="[field1CodeName (spaces replaced with _)]_value">[fieldValue1]</div>
        <div class="[field1CodeName (spaces replaced with _)]_value">[fieldValue2]</div>
        ...
    </div>
        <div id="[resultIndex]_[field2CodeName (spaces replaced with _)]">
        <div class="[field2CodeName (spaces replaced with _)]_value">[fieldValue1]</div>
        <div class="[field2CodeName (spaces replaced with _)]_value">[fieldValue2]</div>
        ...
    </div>
    ...
</div>

Detail Display hidden field value locations

<div id="[resultIndex]_hiddenFields" class="hidden">
    <div id="[resultIndex]_[field1CodeName (spaces replaced with _)]">
        <div class="[field1CodeName (spaces replaced with _)]_value">[fieldValue1]</div>
        <div class="[field1CodeName (spaces replaced with _)]_value">[fieldValue2]</div>
        ...
    </div>
    <div id="[resultIndex]_[field2CodeName (spaces replaced with _)]">
        <div class="[field2CodeName (spaces replaced with _)]_value">[fieldValue1]</div>
        <div class="[field2CodeName (spaces replaced with _)]_value">[fieldValue2]</div>
        ...
    </div>
    ...
    <div id="[resultIndex]_child[childIndex]_[childField1Id (spaces replaced with _)]">
        <div class="[childField1Id (spaces replaced with _)]_value">[childFieldValue]</div>
    </div>
    <div id="[resultIndex]_child[childIndex]_[childField2Id (spaces replaced with _)]">
        <div class="[childField2Id (spaces replaced with _)]_value">[childFieldValue]</div>
    </div>
    ...
</div>

File Uploading

You can upload an image to use in the Drop-down Option menu. After you upload an image to the /custom/web/ directory on the Portfolio server, the relative path to that file on the Portfolio server displays in the Uploaded File URL field. You can then copy and paste that path into the Drop-down Image URL field. Using this method, you can quickly upload and use an existing image.

Choose File

Lets you browse for a file to upload to the Portfolio server. Click Choose File to display the file browsing window. After you select a file to upload, Portfolio displays the filename in the entry field.

Important: Uploading a file with the same name as a previously uploaded file will overwrite the previous file. Administrators who have multiple profiles on an instance should use a naming convention for files on each profile to prevent confusion and overwritten files.

Upload

Copies the specified file to the /custom/web/ directory on the Portfolio server. Any files that you upload will remain on the server until they are deleted from the /custom/web/ directory. After you upload the file, the relative path to the uploaded file on the Portfolio server displays in the Uploaded File URL field.

Important: If you upload an HTML file that contains images, JavaScript, or CSS, you must separately upload those elements into the /custom/web/ directory.

Uploaded File URL

Displays the relative path as a link to the uploaded file on the Portfolio server. You can then do either of the following:

Copy and paste the path into the entry fields on this page.
Click the path to display the contents of the file in a separate window.

Note: Each time you upload a file, its relative path replaces the relative path of the previously-uploaded file in this field. To see a list of all files that have been uploaded and have not been deleted from the server, click the path displayed in the See All Uploaded Files field.

See All Uploaded Files

Displays the /custom/web/ directory path in which the uploaded files are placed on the Portfolio server. Click the path to display a list of the files in the /custom/web/ directory on the Directory Listings page.You can use this page to delete files from the directory.

Note: Only a user with admin privileges can access the Directory Listings page.

Fields: Add/Edit/Copy HTML Widget

Select fields for use in Widget

Localized Strings

HTML Content

JavaScript

Search Result Display hidden field value locations

Detail Display hidden field value locations

File Uploading

Related topics