Extender Screens
=====================================================================

Extender Custom UIs require integration with the Screen Permissions
Customization, but it is straightforward.

All Extender Custom UIs look the same from the inside, so it is
impossible to tell which screen is running to apply the permissions 
correctly.

To work around this, we need to provide some hints to the permissions
manager.

Creating Permissions for Extender Screens
---------------------------------------------------------------------

If you're working with a Custom UI that is already integrated with 
the Screen Permissions customization, you can skip to the end 
and starting creating permissions for your screen.

You'll know if your Custom UI is integrated by checking the code for
a constant called ``PERMISSIONS_SCREEN_NAME``.  This defines
the name you will use in the :guilabel:`Screen` field of the permission
definition.

To open a UI script to see if the constant is defined:

1. Open :guilabel:`Extender --> Setup --> Scripts`.
2. Right click on the script that defines the UI and select :guilabel:`Open`.
3. The file will be opened in the default editor.  Search it using 
   :guilabel:`Ctrl+f` for ``PERMISSIONS_SCREEN_NAME``.
4. If the constant is present, note the value.

.. note:: 

    The Permission Screen Name must begin with VI! If it does not, the
    permission will not be usable.

A UI script that uses the Screen name ``VINAME`` will likely start
like this:

.. code-block:: python

    from accpac import *
    try:
        from poplar_screenperms.screen_permission_ui import ScreenPermissionUI
        parent = ScreenPermissionUI
    except ImportError as e:
        parent = UI

    TABLE = "VINAME.VITABLE"
    PERMISSION_SCREEN_NAME = "VINAME"

    def main(args):
        CustomTableUI()

    class CustomTableUI(parent):

        def __init__(self, permission=PERMISSION_SCREEN_NAME):
            super().__init__()
            self.createScreen()

            if hasattr(self, 'set_program'):
                self.set_program(permission)

With the name in hand, define a permission as you would any other.  To
create a Screen Permission for this Custom UI, just use ``VINAME``
as the screen name.

.. figure:: https://s3.amazonaws.com/dev.expi/content/poplar_screenperms/extender_screen_perm.png

    Configuring a Screen Permission for the VINAME screen, Users without Read
    permissions cannot open the screen.

To create a field level permission, you'll need the control name.  If 
you'use using a `Poplar Custom Table UI`_, the control name will always be
``x1{FIELD}``, where {FIELD} is replaced with the database table field name.

For the datasource, use your table name.  To continue our example and create a 
permission to manage the ``FIELD`` field in the ``VINAME.VITABLE`` table:

.. figure:: https://s3.amazonaws.com/dev.expi/content/poplar_screenperms/extender_control_perm.png

    Configuring a Control Permission for the VINAME screen FIELD field, Users 
    without Read permissions cannot see the field.


.. _`Poplar Custom Table UI`: https://poplars.dev/customzations/poplar_customtableui

Making a Screen Permission Compatible Custom UI
-------------------------------------------------------------------------------

If you'd like to add screen permissions to an existing UI, make the 
following changes to your Custom UI script:

1. Inherit from ``ScreenPermissionUI`` instead of ``UI``.  All Custom UIs are 
   subclasses of UI.  Using the ScreenPermissionUI instead, all the permission
   enforcement is automatically added to your UI, in addition to all the 
   standard functionality.

2. Call ``super().__init__()`` instead of ``UI.__init__()``.

3. After the screen has been created, call ``self.set_program(PERMNAME)``.

It is easy to create a Custom UI that will use permissions if they are 
available, but otherwise fall back to a standard UI. See the code block above,
which falls back on UI if the poplar_screenperms package is not installed.