Manual Chapter : Advanced Customization Coding

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0
Manual Chapter

Advanced Customization Coding

About advanced customization

With advanced customization, it is possible to change almost anything with a certain knowledge of HTML, CSS, and JavaScript. UI templates, which consist of HTML and PHP files, and CSS files, are available for edit directly from the Advanced Customization view.

About customization variables

Customization variables are special symbols, such as %[
variable_name
], in a UI template. A customization variable is a placeholder for actual customization and localization values. When a UI page is generated from a UI template, customization variables are replaced with actual values.
Customization uses the same UI templates for all languages. Therefore, F5 recommends that when you customize UI templates, you reuse customization variables for localized texts. Otherwise, you risk creating localization conflicts.

About PHP code

Customization uses PHP code inside UI templates.
F5 recommends that when you customize UI templates, you do not delete or modify PHP code.

About CSS code

In the hierarchy of the advanced customization user interface, all CSS code is located under
Access Profile
Common
. The folder contains various versions of the Access Policy Manager (APM) CSS code with names such as
apm_mobile.css
and
apm_full.css
. When displaying generated UI pages, APM picks the correct
.css
file for the client (mobile browser, full browser, BIG-IP Edge Client).
If you create a UI template that partially or completely replaces the default structure provided by F5, F5 recommends that you do not change existing CSS definitions but add your own with different names (IDs). Otherwise, you run the risk that other non-customized pages will be misrendered.
To replace a main table with your div, on the logon page for example, replace
<table id="main_table" class="logon_page">
with your
<table id="cust-main" class="cust-logn-page">
.

Coding recommendations

With advanced customization, you can partially or completely replace the default structure for pages. To avoid unexpected problems however, follow these recommendations when editing
.css
and
.inc
files.
.css file
  • Do not change existing CSS definitions but add your own with different names (IDs). Otherwise, you run the risk that other non-customized pages will be misrendered.
  • In your new code, reuse existing customization variables (%[
    variable_name
    ]) rather than creating new ones; doing so prevents localization conflicts.
  • Do not change PHP code.
.inc file
In most cases, you can safely replace the code in .inc files.
Updating a .css file with additional code to customize a logon page table
The first line of the code for the existing logon page table is:
<table id="main_table" class="logon_page">
. Retain that code and add code for a div or a table that you want to use instead. For example, the code for a new table might start like this:
<table id="cust-main" class="cust-logn-page">
.

Access profile common .css and .inc files

You can customize the following files for access profiles in the Advanced Customization view.
Name
Description
apm_full.css
File that contains all CSS for desktop browsers; also contains this PHP:
  • apmCssCustomizationReg
    - array with variables that come from general customization data.
  • parsedVersionMajor
    and
    parsedVersionMinor
    - versions of Mozilla, used to fix specific issues with CSS .
apm_mobile.css
File that contains all CSS for mobile browsers. If you want mobile pages to look exactly the same as full browser pages, you can replace the contents of apm_mobile.css contents with the contents of apm_full.css.
footer.inc
The include file that specifies the footer text line.
apm_edge.css
File contains all CSS for BIG-IP Edge Client pages.
F5 recommends that you do not edit this file.
javascript_disabled.inc
File that is included with every page and displayed only when the browser does not support JavaScript.
header.inc
File that specifies the page header content for access profile pages on all devices. The file includes this PHP:
  • viewport_data
    – contents of meta name
    id="viewport"
    .
  • label_position
    – position of labels against corresponding input fields (see general customization Access Profile/Common/Layout Settings)
  • page_layout
    – position of input cell (see Access Profile/Common/Layout Settings)
  • page_image_default
    – default image cell image (see Access Profile/Common)
  • header_logo
    – corporate logo
The file includes JavaScript:
setViewport()
– function that changes scale basing on orientation.
apm_mobile_ppc.css
Styles for old Windows mobile device.

Access profile logout .inc files

You can customize the following files for access profiles in the Advanced Customization view.
Name
Description
my.acl.inc
ACL denied page if user tries to access prohibited URL.
urlfilter_blocked.inc
Secure Web Gateway (SWG) access denied page if user tries to access prohibited URL.
access_notfound.inc
The HTML, JavaScript, and PHP code that presents a page when access is not granted.
logout.inc
Default logout page.

Access profile logon .inc files

You can customize the following files for access profiles in the Advanced Customization view.
Name
Description
logon.inc
Customization of logon page.
http_401.inc
Customization of HTTP 401 error (unauthorized) page.
view.inc
Customization of VMware View logon page.

Access profile decision box .inc files

You can customize the following files for access profiles in the Advanced Customization view.
Name
Description
decision_box.inc
Specifies the layout for the HTML that appears in a decision box.

Access profile message box .inc files

You can customize the following files for access profiles in the Advanced Customization view.
Name
Description
message_box.inc
Specifies the layout for the HTML that appears in a message box.

Access profile ending page .inc files

You can customize the following files for access profiles in the Advanced Customization view.
Name
Description
my.acl.inc
ACL denied page if user tries to access prohibited URL.
urlfilter_blocked.inc
Secure Web Gateway (SWG) access denied page if user tries to access prohibited URL.
access_notfound.inc
The HTML, JavaScript, and PHP code that presents a page when access is not granted.
logout.inc
Default logout page.

Webtop .css and .inc files

You can customize the following files for webtops in the Advanced Customization view.
Name
Description
hometab.inc
Not applicable; file pop up.
webtop_popup.css
Pop up file CSS.
webtop_help.inc
Help file for webtop.
desktopClass.js.inc
Main JavaScript file for webtop.

About advanced customization images

In the General Customization view, each access profile, access profile page, and webtop includes an Advanced Customization Images setting. The setting provides storage for up to ten images that are then available for use in the Advanced Customization view. An image specified in the setting is managed with the parent object; it is exported, imported, copied, or deleted along with the parent object. It persists with the parent object through backup and upgrade procedures. An image is specified as a name-value pair.
Name
Images names (image00 through image09) are fixed; they are only placeholders. An image name, for example image00, does not correspond to a location on a page or to an image that is already used in the UI. The numerals, 00, do not indicate order or precedence. The image name can used as a variable in the code for a parent object in the Advanced Customization view. This code specifies image00 as a variable:
<img src="%[
image00
]"/>
.
Value
Image values provide file paths and the file names for image files. To use the image, the value can be copied from the setting in the General Customization view into the code in the Advanced Customization view. A default value
/public/images/my/tr.gif
indicates that a customized image has not been specified.
Advanced Customization Images settings for some customization objects
Advanced customization image library in general customization view

About best practices for advanced customization images

You can think of the Advanced Customization Images settings as libraries of images. Each library has a scope: the object that manages the library can always use images from it; sometimes child objects can also use images from the library of a parent object. Advanced Customization Images settings offer a lot of flexibility. When deciding where to store images, consider how much flexibility you need and whether using images from a parent object library provides adequate control.
Access Profile Advanced Customization Images
If you store images in the Advanced Customization Images setting for an access profile, you can use the images not only in the access profile code but also in the code for access policy pages. The advantage of this approach is that if you need to update images, you only need to change them in one setting. However, if you want to ensure that images on an access policy page remain the same regardless of changes to images in the access profile Advanced Customization Images setting, this might not be the approach you want to use.
Access Policy pages Advanced Customization Images
If you store images in the Advanced Customization Images setting for an access policy page, you can use the images in the code for that page only. You can store the same images that are stored at the access profile level, different images, a mix of both, or no images.
Webtop Advanced Customization Images
If you store images in the Advanced Customization Images for a webtop, you can use the images in the code for that webtop only. However, general customization provides many settings in which to specify icons; it might be simpler to use it.

Example: Adding an image to an access policy page

In this example, a custom image is stored in the Advanced Customization Images settings for one of the access policy pages, a message box page. In the Advanced Customization view, the code for the message box page is updated to add a custom image to the right side of the page.
Sample custom image
Image of a large capital C
Default message page
Message page without image
Customized message page with image
Message page with large capital C in right pane
This example includes tasks to complete in the General Customization view before you update the code and code changes to make in the Advanced Customization view.

Uploading images for use in customization

You can add images for Access Policy Manager customization with the image browser. You can then select and use these images by means of settings within the Customization tool.
  1. On the Main tab, click
    Access
    Profiles / Policies
    Customization
    General
    .
    The Customization tool appears in General Customization view, displaying
    Form Factor: Full/Mobile Browser
    settings.
  2. On the menu bar, click
    Image Browser
    .
    The image browser opens in a new screen.
  3. Select the image filter method from the
    Filter Messages
    list.
    • Select
      Default Images
      to view the included default Access Policy Manager images.
    • Select
      User Uploaded Images
      to view the custom uploaded images.
  4. Add and remove images.
    • To add an image, click
      Add Image
      , select the image, and click
      Open
      .
    • To remove an image, select the image in the image browser, and click
      Delete Image
      .

Storing images for advanced customization of a specific page

This example explains how to store a custom image for use in the advanced customization of an access policy message page. To follow this example, you need an access profile with an access policy that contains a Message Box action item.
Specify an image in the
Advanced Customization Images
setting for an object so that the image can be used in advanced customization of the object.
  1. From the General Customization view, expand the
    Access Profiles
    folder.
    Folders for each access profile display.
  2. Expand the folder for an access profile.
  3. Expand these folders
    Access Policy
    Message Pages
    Message Box
    .
    Message Box is the default name for a message box item. You might see a different name, or names if the access policy includes multiple message boxes; expand one of them.
    Settings for the message box access policy item display.
  4. Click the
    Advanced Customization Images
    setting.
    Image names and values display in the right pane.
  5. Click the value for one of the images.
    If not already updated for use in advanced customization, the value is
    /public/images/my/tr.gif
    .
    A pulldown menu icon displays.
  6. Click the pulldown menu icon and click
    Replace
    .
    A popup screen displays images.
  7. To choose an image, click it; then click
    Change
    .
    The popup screen closes. A new value displays for the image.
  8. Press Enter to finalize the change, and click
    Save
    .
  9. Make a note of the image name; you need it when you perform advanced customization.
    You can use the image name as a variable in advanced customization of the parent object only. A message box page is the parent object in this example.
The image is now available for use in advanced customization of the message box item.

Updating message box code with a custom image

You need to have the value of the name of image available from the Advanced Customization Images setting for the particular message box that you want to update.
You remove and replace the code that specifies the image to display so that a customized image displays instead.
  1. From the
    View
    list, select
    Advanced Customization
    .
    The advanced customization (tree) view displays.
  2. Navigate to the message box item to be customized.
    1. Expand the
      Access Profiles
      folder and expand the folder for the access profile you want to customize.
    2. Expand these folders
      Access Policy
      Message Pages
      Message Box
      .
      Message Box is the default name for a message box item. You might see a different name, or names if the access policy includes multiple message boxes; expand one of them.
      Settings for the message box access policy item display.
  3. Click
    message_box.inc
    .
    Code displays in the Advanced Customization Editor.
  4. Scroll down to this code.
    <table id="main_table" class="message_box"> <tr> <? if( $GLOBALS["page_layout"] == "form_right" ){ ?><td id="main_table_image_cell"><img src="<? print( $GLOBALS["page_image_default"] ); ?>"></td><? } ?> <td id="main_table_info_cell"> <table id="interaction_table"> <tr> <td id="interaction_table_header"><? print('%[form_message]'); ?></td> </tr> <tr> <td class="interaction_table_text_cell"><? print('<a href="#" onclick="javascript:SubmitResult(1);return 1;">%[link]</a>'); ?></td> </tr> <tr> <td class="interaction_table_footer"></td> </tr> </table> </td> <? if( $GLOBALS["page_layout"] == "form_left" ){ ?><td id="main_table_image_cell"><img src="<? print( $GLOBALS["page_image_default"] ); ?>"></td><? } ?> </tr> </table>
  5. After the first table row open tag (
    <tr>
    ), remove this line of code.
    <? if( $GLOBALS["page_layout"] == "form_right" ){ ?><td id="main_table_image_cell"><img src="<? print( $GLOBALS["page_image_default"] ); ?>"></td><? } ?>
    The code that checks the page layout and specifies the image cell is removed.
  6. Before the last table row close tag (
    </tr>
    ), remove this line of code.
    <? if( $GLOBALS["page_layout"] == "form_left" ){ ?><td id="main_table_image_cell"><img src="<? print( $GLOBALS["page_image_default"] ); ?>"></td><? } ?>
    Code that checks the page layout and specifies the image cell is removed.
  7. Before the last table row close tag (
    </tr>
    ), insert this line of code, replacing
    nn
    with the image number.
    <td id="main_table_image_cell"><img src="%[image
    nn
    ]"/></td>
  8. In the Advanced Customization Editor area, click
    Save Draft
    .
    In the navigation tree,
    message_box.inc
    now displays in italics.
  9. On the menu bar, click
    Save
    .
    In the navigation tree,
    message_box.inc
    is no longer italicized. In the screen header, the
    Apply Access Policy
    link displays.
  10. In the screen header, click the
    Apply Access Policy
    link.
    A screen displays the access profile list with the access profile you have been editing selected.
  11. Click the
    Apply Access Policy
    button.
You can now verify the result of this customization from a browser by trying to access a virtual server in which this access profile is specified.

Example: Adding an image to a profile and a page

In this example, a custom image is stored in the Advanced Customization Images settings for an access profile. Then, the value of the image is used in advanced customization of the access profile page header. The header displays on all access policy pages, including the logon page. Then, the value of the image is used in additional advanced customization of the access policy logon page.
Sample custom image
Large capital C

Uploading images for use in customization

You can add images for Access Policy Manager customization with the image browser. You can then select and use these images by means of settings within the Customization tool.
  1. On the Main tab, click
    Access
    Profiles / Policies
    Customization
    General
    .
    The Customization tool appears in General Customization view, displaying
    Form Factor: Full/Mobile Browser
    settings.
  2. On the menu bar, click
    Image Browser
    .
    The image browser opens in a new screen.
  3. Select the image filter method from the
    Filter Messages
    list.
    • Select
      Default Images
      to view the included default Access Policy Manager images.
    • Select
      User Uploaded Images
      to view the custom uploaded images.
  4. Add and remove images.
    • To add an image, click
      Add Image
      , select the image, and click
      Open
      .
    • To remove an image, select the image in the image browser, and click
      Delete Image
      .

Storing images for advanced customization of policy pages

To follow this example, you need an access profile with an access policy that contains a Logon Page action item.
Specify an image in the
Advanced Customization Images
setting for an access profile to use the image in advanced customization of the access profile and any access policy pages.
An image stored in the
Common
settings for an access profile can be used in the advanced customization of any access policy page provided that you use the image value instead of the image name to specify the
src
attribute for the image.
  1. From the General Customization view, expand the
    Access Profiles
    folder.
    Folders for each access profile display.
  2. Expand the folder for an access profile.
  3. Expand the
    Common
    folder.
    A list of settings displays.
  4. Click the
    Advanced Customization Images
    setting.
    Image names and values display in the right pane.
  5. Click the value for one of the images.
    If not already updated for use in advanced customization, the value is
    /public/images/my/tr.gif
    .
    A pulldown menu icon displays.
  6. Click the pulldown menu icon and click
    Replace
    .
    A popup screen displays images.
  7. To choose an image, click it; then click
    Change
    .
    The popup screen closes. A new value displays for the image.
  8. Press Enter to finalize the change, and click
    Save
    .
  9. Click the value for the image again; copy the value in the field and paste it into a text file.
    The value should be something like this:
    /public/images/customization/Common/
    ProfileName
    _general_ui/image
    00_en
    .png
    . You need to know the value when you perform advanced customization.
The image is now available for use in advanced customization of the message box item.

Adding an image in the page header code

In this example, an image is added to the access profile page header. Make sure that the value of the image is available exactly as specified in the
Advanced Customization Images
setting for the particular access profile that you want to update.
Add code to specify an image to display in the page header.
  1. From the
    View
    list, select
    Advanced Customization
    .
    The advanced customization view displays.
  2. In the navigation tree, expand the
    Access Profiles
    folder and expand the folder for the access profile you want to customize.
  3. Expand the
    Common
    folder.
  4. Click
    header.inc
    .
    Code displays in the Advanced Customization Editor area of the screen.
  5. Scroll to the end of the file to this code.
    <table id="page_header"> <tr > <td id="header_leftcell"><img src='<?=$GLOBALS["header_logo"]?>'/></td> <td id="header_rightcell"><? if( !empty( $GLOBALS["header_show_disconnect_button"] ) ){ ?><button id="disconnect" onclick="javascript: /* window.onbeforeunload=window.document.onbeforeunload=window.document.body.onbeforeunload=null; */ if(top.F5_HT_logOut){ F5_HT_logOut(); }else{ window.location.href='/my.logout.php3'; }"><img src="%[disconnect_icon]"/><span>%[disconnect_text]</span></button><?} if( !empty( $GLOBALS["webtop_header_message"] ) ){?><span id="webtop_header_message"><img src='<?=$GLOBALS["fw_header_icon"]?>' id='fw_header_icon'><?=$GLOBALS["webtop_header_message"]?></span><?}?></td> </tr> </table>
  6. After the table close tag (
    </table>
    ), insert this line of code.
    <img src="
    image_value_from_advanced_customization_settings
    " />
  7. In the Advanced Customization Editor area, click
    Save Draft
    .
    In the navigation tree,
    header.inc
    now displays in italics.
  8. On the menu bar, click
    Save
    .
    In the navigation tree,
    header.inc
    is no longer italicized. In the screen header, the
    Apply Access Policy
    link displays.
  9. In the screen header, click the
    Apply Access Policy
    link.
    A screen displays the access profile list with the access profile you have been editing selected.
  10. Click the
    Apply Access Policy
    button.
  11. To verify the result, in the General or Advanced Customization view, click Preview and navigate to and click any access policy page.
Logon page with customized page header
customized page header

Adding an image in the logon page code

This example shows one way to change the image that is displayed on a logon page. Have the value of the image available exactly as it is specified in the
Advanced Customization Images
setting for the parent access profile.
Add code to specify an image to display after the logon page.
  1. From the
    View
    list, select
    Advanced Customization
    .
    The advanced customization view displays.
  2. Navigate to the logon page item to be customized.
    1. Expand the
      Access Profiles
      folder and expand the folder for the access profile you want to customize.
    2. Expand these folders
      Access Policy
      Logon Pages
      Logon Page
      .
      Logon Page is the default name for a logon page item. You might see a different name, or names if the access policy includes multiple logon pages; expand one of them.
      Settings for the logon page access policy item display.
  3. Click
    logon.inc
    .
    Code displays in the Advanced Customization Editor area of the screen.
  4. Scroll to the end of the file to this code.
    } --></script> </td> <? if( $GLOBALS["page_layout"] == "form_left" ){ ?><td id="main_table_image_cell"><img src="<? print('%[front_image]'); ?>"></td><? } ?> </tr> </table> <? include_customized_page("general_ui", "footer.inc"); ?> <? include_once("sam/webtop/renderer/vk.inc"); ?> <div id="MessageDIV" class="inspectionHostDIVSmall"></div> </body> </html>
  5. After the table close tag (
    </table>
    ), insert this line of code.
    <img src="
    image_value_from_advanced_customization_settings
    " />
  6. In the Advanced Customization Editor area, click
    Save Draft
    .
    In the navigation tree,
    login.inc
    now displays in italics.
  7. On the menu bar, click
    Save
    .
    In the navigation tree,
    logon.inc
    is no longer italicized. In the screen header, the
    Apply Access Policy
    link displays.
  8. In the screen header, click the
    Apply Access Policy
    link.
    A screen displays the access profile list with the access profile you have been editing selected.
  9. Click the
    Apply Access Policy
    button.
  10. To verify the result, in the General or Advanced customization view, click Preview and navigate to and click any access policy page.
Logon page with custom image after the form
logon page