How to add a custom frame to the panel interface

This article uses the example of Ubuntu OS 20 and the Roundcube service to describe the process of adding any of your content hosted on external resources to the panel as frames - as a web page within the panel web page.

Add a new menu item

1. In the /usr/local/mgr5/etc/xml folder, create the file ispmgr_mod_testframe.xml with the following contents:

   <?xml version="1.0" encoding="UTF-8"?>
   <mgrdata>
       <mainmenu level="admin+">
           <modernmenu>
               <node name="my_group">
                   <node name="testframe" />
               </node>
           </modernmenu>
       </mainmenu>
   
       <handler name="testframe.sh" type="xml">
           <func name="testframe" />
       </handler>
   
       <lang name="ru">
           <messages name="desktop">
               <msg name="modernmenu_my_group">Test</msg>
               <msg name="modernmenu_testframe">Test Form Frame</msg>
           </messages>
       </lang>
   </mgrdata>

   Note:

   Thus, a group with the name Test is created in the left menu of the panel, the menu item Test form frame is in it, and a handler is also set in this file.

2. Create a testframe.sh handler file and add the following lines to it:

   #!/bin/bash
   cat /usr/local/mgr5/addon/testframe.xml

     This is the simplest handler, returning the static contents of the testframe.xml file.

    

3. Place the testframe.sh file in the /usr/local/mgr5/addon/ folder and set the default permissions for plugin handlers:

   chmod 755 testframe.sh
   

4.  testframe.xml - XML description of the form, put it in /usr/local/mgr5/addon/ next to the previous file.

   <?xml version="1.0" encoding="UTF-8"?>
   <doc lang="ru" func="testframe" binary="/ispmgr">
       <metadata name="testframe" type="form" mgr="ispmgr">
           <form>
               <field name="frame" fullwidth="yes">
                   <frame name="roundcubeframe" forcetheme="yes" fullpage="yes" keepalive="yes" />
               </field>
           </form>
       </metadata>
       <messages name="testframe" checked="6b49a92f5cc5153c76b78446d0d74eb4">
           <msg name="title">Test Form Frame</msg>
           <msg name="frame">Frame</msg>
       </messages>
       <roundcubeframe>https://x.x.x.x:1501/roundcube/?_task=mail&amp;_mbox=INBOX</roundcubeframe>
   </doc>
   
   where x.x.x.x - is the ip address of your panel

5. Reload the panel with the command in the console:

   kilall core

   After that, a new group should appear at the bottom of the left menu with the Test Form Frame menu item in it.

    

Additional settings

1. Open the testframe.xml file for editing and fix the ip address in the URL specified inside the <roundcubeframe> tag replacing it with the ip address of your panel. Everything except the ip address (protocol, port, path to Roundcube) can be left as it is.  
2. After editing and saving the XML form description file, you do not need to restart the panel.
3. For the form to work correctly, you need to allow Roundcube to be displayed in a different frame - by default it allows itself to be displayed only in frames with matching host and port (in this case the port is different - in the panel by default port 1500, in Roundcube installed with ispmanager panel port 1501).

   There are 2 ways to do this:

   • Disable the  X-Frame-Options header in the configuration file

     Roundcube  

     1. Go to the /etc/roundcube and open the config.inc.php file for editing.
     2. At the end of the file, add

        the following string:

        $config['x_frame_options'] = '';

         

     3. With this option Roundcube will stop adding default value SAMEORIGIN for X-Frame-Options header. The change will take effect immediately after saving the config.inc.php file, you don't need to reload anything.
        

      

   •   change the Content-Security-Policy header configuration      

     The X-Frame-Options header allows you to specify only two options, which either prevent content from being displayed in a frame at all, or allow content to be displayed only in a frame from the same host and port. To make our content visible only in a frame from a different host or port, we need to use the Content-Security-Policy header.

     1.   Disable the X-Frame-Options header which adds Roundcube by default (see instructions in the previous section).
     2.   Go to the  /etc/nginx/vhosts-includes and open the following file for editing:

        roundcube-nginx.conf

          In the section starting with the line location ~ ^/roundcube/(.+\.php)$ {, and in the section starting with the line  location ~* ^/roundcube/(.+\.(jpg|jpeg|gif|css|png|js|ico|html|xml|txt))$ { add the following string:

        add_header "Content-Security-Policy" "frame-ancestors x.x.x.x:1500";
        
        *** Replace x.x.x.x.x:1500 with the ip address and port of your panel

     3.   In order to activate the changes, restart nginx with the followng command: /etc/init.d/nginx restart
        

     Configuring Content-Security-Policy header in Apache  

     In many cases, you may need to configure the **Content-Security-Policy **  header in the Apache web server to display content in a frame.  The following code must be added to the appropriate level of the Apache configuration file (this can be .htaccess for a specific folder, or configuration files in  /etc/apache2 or /etc/httpd  -  at your discretion) replacing the host and port with the one used by the panel:

     <IfModule mod_headers.c>
         Header set Content-Security-Policy "frame-ancestors 172.31.97.115:1500"
     </IfModule>

    

   
   

Frame options

The following attributes can be used with the <frame> tag:

• keepalive - this attribute allows you to keep the frame state when you switch to other tabs in the panel and then return to the frame tab;
• fullheight - makes the frame stretch to the bottom of the browser window;
• fullpage - makes the frame stretch from the left menu and the bar in the panel header to the bottom and right borders of the browser window, filling all the space occupied by the form;
• forcetheme - his attribute, when the frame is displayed in a panel with a dark theme enabled, applies a filter to the frame content, trying to match its colors to the dark theme of the panel. Depending on the page or application displayed in the frame, the use of this attribute may be useful or undesirable.

An example of using <frame> attributes:

<frame name="frame" forcetheme="yes" fullpage="yes" keepalive="yes" />

This frame covers the entire window except for the left menu and the panel header, persists when you navigate to other tabs in the panel, and, in a dark theme, tries to match the panel colors.

https://ip address:1501/roundcube/?_task=mail&amp;_mbox=INBOX</roundcubeframe>