Metadata-Version: 2.1
Name: urpaform
Version: 0.2.0
Summary: Form Filling Module with UltimateRPA
Home-page: https://github.com/ultimaterpa/urpaform
Author: anerold
Author-email: support@ultimaterpa.cz
License: MIT
Description: # urpaform
        
        Extension for filling in forms with [UltimateRPA](https://www.ultimaterpa.com).  
        You need to have the [UltimateRPA Tools installed](https://www.ultimaterpa.com/documentation/_install.html).  
        Urpaform allows you to   
        - distinguish between several forms in your robotization, 
        - assign form fields of various types to a specific form,
        - maintain the form fields.
        
        
        ## Examples 
        
        ### Basic Usage - Form with a Simple Edit Box
        
        The name given to the form appears in logs. A form field type is specified 
        as EditElement, added to a form, assigned with the desired value to be filled in 
        and finally, the form is completed.
        
        ```python
        
        from urpaform import Form, EditElement
        
        app = urpa.exec_app("Some_application.exe")
        edit_element = app.find_first(cf.name("Username").edit())
        edit_field = EditElement(edit_element)
        test_form = Form("my forms's name")
        test_form.add(edit_field, "UltimateRPA")
        test_form.complete()
        ```
        Alternatively, you can take advantage of a context manager to complete the form.
        
        ```python
        
        from urpaform import Form, EditElement
        
        app = urpa.exec_app("Some_application.exe")
        edit_element = app.find_first(cf.name("Username").edit())
        edit_field = EditElement(edit_element)
        with Form("my forms's name") as test_form:
              test_form.add(edit_field, "UltimateRPA")
        ```
        
        Note, that there are several ways to add one or many fields to your form using the `add()` method.  
        You can add fields separately one by one by passing two parameters, where an element is followed by a value.  
        Alternatively, you can add multiple fields at once by passing any number of tuples with elements and values for each field.
        
        ```python
        # adding 1 field
        test_form.add(some_edit_field, "some value")
        
        # adding 2 fields as tuples
        test_form.add((some_edit_field, "some value"), (another_field, "some value"))
        ```
        
        If needed, Form can be initialized with custom values for arguments:
        * `attempts`: how many times can be completion of the form attempted (default value is 3)
        * `delay`: how many second should pass between filling of two fields (default value is 0)
        
        ### Options for Logging and Checks
        
        For several form field types, you can determine whether the filled values 
        appear in logs. You can also control whether the check of desired value and truly filled 
        value will be performed. 
        
        ```python
        from urpaform import Form, ComboElement
        
        app = urpa.exec_app("Some_application.exe")
        combo_element = app.find_first(cf.name("Usual").combo_box())
        combo_field = ComboElement(combo_element, show_in_log=True, allow_check=False)
        test_form = Form("my forms's name")
        test_form.add(combo_field, "Saturday")
        test_form.complete()
        ```
        
        ### Maintaining a Password Box
        
        Maintenance of a password box is similar to an edit box. You can even choose
        between keyboard input and pasting just like in edit box. However, the filled 
        value in a password box cannot be checked. The password itself can be stored in 
        Windows Credential Vault and retrieved with `urpa.get_password()`. More details 
        in [Vault Tutorial and documentation](https://www.ultimaterpa.com/documentation/_vault.html).
        
        ```python
        from urpaform import PasswordElement
        
        app = urpa.exec_app("Some_application.exe")
        password = urpa.get_password(system, user)
        password_element = app.find_first(cf.name("Password").edit())
        password_field = PasswordElement(password_element)
        test_form = Form("my forms's name")
        test_form.add(password_field, password)
        test_form.complete()
        ```
        
        ### Setting Specific Behavior of Elements - Edit Elements
        
        When [inspecting](https://www.ultimaterpa.com/documentation/_search_elements.html) an edit element, you may discover, that it has some specific behavior.
        - For most, the filled value is placed in value property, but for others in the name property or even the text_value property.
        You can control the respective set up with `value_is_in` parameter.
        - Some can contain a default value that cannot be removed from the edit box. For example, 
        predefined dots for a date. You can use the `default_value` parameter.
        - You have an option to define your own combination of keys with `clear_keys` to clear 
        the field, in case the default setting fails for your application.
        - There is na alternative way to fill an edit box (default method is `writing` using keyboard input). You can switch to pasting the value into the field from clipboard by setting `send_method` at `pasting` and `paste_keys` at demanded paste shortcut (default CTRL+V).
        
        ```python
        
        from urpaform import Form, EditElement
        
        app = urpa.exec_app("Some_application.exe")
        edit_element = app.find_first(cf.name("Username").edit())
        edit_field = EditElement(edit_element, value_is_in="name", default_value="  .  .    ")
        test_form = Form("my forms's name")
        test_form.add(edit_field, "UltimateRPA")
        test_form.complete()
        ```
        
        
        ### Setting Specific Behavior of Elements - Combo Boxes
        
        Based on specific behavior of the combo box in your form, you can choose the method 
        to fill in your desired value. Many would accept the desired value as a text. For others,
        you may need to activate the `walk_type` to walk through all available values in the 
        combo box to find the desired one.
        
        It is recommended to use the default method and to use the other method only if the 
        default method fails to set the value in your combo box.
        
        ```python
        from urpaform import Form, ComboElement
        
        app = urpa.exec_app("Some_application.exe")
        first_combo_element = app.find_first(cf.name("Usual").combo_box())
        first_combo_field = ComboElement(first_combo_element, walk_type=False)
        test_form = Form("my forms's name")
        test_form.add(first_combo_field, "Tuesday")
        second_combo_element = app.find_first(cf.name("Unusual").combo_box())
        second_combo_field = ComboElement(second_combo_element, walk_type=True)
        test_form.add(second_combo_field, "Saturday")
        test_form.complete()
        ```
        
        
        ###  Maintaining Check Boxes and Radio Buttons
        
        You can check and uncheck check boxes in your forms, as well as activate radio buttons.
        
        ```python
        from urpaform import Form, CheckElement, RadioElement
        
        app = urpa.exec_app("Some_application.exe")
        test_form = Form("my forms's name")
        first_check_element = app.find_first(cf.name("a)").check_box())
        first_check_field = CheckElement(first_check_element)
        test_form.add(first_check_field, True)
        second_check_element = app.find_first(cf.name("b)").check_box())
        second_check_field = CheckElement(second_check_element)
        test_form.add(second_check_field, False)
        radio_element = app.find_first(cf.name("2").radio_button())
        radio_field = RadioElement(radio_element)
        test_form.add(radio_field, True)
        test_form.complete()
        ```
        
        ## Changelog
        
        [Changelog is here](https://github.com/ultimaterpa/urpaform/blob/master/CHANGELOG.md)
        
Keywords: Robotic Process Automation,RPA,UltimateRPA,form filling
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.7
Classifier: Operating System :: Microsoft :: Windows
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
