# Luakit Documentation / Modules / formfiller

# Module `formfiller`

Provides functionality to auto-fill forms based on a Lua DSL

The formfiller provides support for filling out forms based on the contents of a forms file, which uses a domain-specific language to specify the content to fill forms with.

The following is an example for a formfiller definition:

    on "example.com" {
        form "profile1" {
            method = "post",
            action = "/login",
            className = "someFormClass",
            id = "form_id",
            input {
                name = "username",
                type = "text",
                className = "someClass",
                id = "username_field",
                value = "myUsername",
            },
            input {
                name = "password",
                value = "myPassword",
            },
            input {
                name = "autologin",
                type = "checkbox",
                checked = true,
            },
            submit = true,
            autofill = false,
        },
    }

- The `form` function's string argument is optional. It allows you to define multiple profiles for use with the `zL` binding.

- All entries are matched top to bottom, until one fully matches or calls `submit()`.

- The `submit` attribute of a form can also be a number, which gives index of the submit button to click (starting with `1`). If there is no such button or the argument is `true`, `form.submit()` will be called instead.

- Instead of `submit`, you can also use `focus = true` inside an `input` to focus that element or `select = true` to select the text inside it. `focus` will trigger input mode.

- The string argument to the `on` function (`example.com` in the example above) takes a Lua pattern! BEWARE its escaping!

- All of the attributes of the `form` and `input` tables are matched as plain text.

- Setting `autofill = true` on a form definition will automatically fill and possibly submit any matching forms when a web page with a matching URI finishes loading. This is useful if you wish to have login pages for various web services filled out automatically. It is critically important, however, to verify that the URI pattern of the rule is correct!

As a basic precaution, autofill only works if the web page domain is present within the URI pattern.

There is a conversion script in the luakit repository that converts from the old formfiller format to the new one. For more information, see the converter script under `extras/convert_formfiller.rb`.

## Files and Directories

- The formfiller configuration is loaded from the `forms.lua` file stored in the luakit data directory.

## Functions

### formfiller.extend (extensions)

Extend the formfiller DSL with additional functions. This takes a table of functions. For example, to use the `pass` storage manager:

    formfiller.extend({
        pass = function(s) return io.popen("pass " .. s):read() end
    })

which will then be usable in the fields of `form.lua`:

    input {
        name = "username",
        value = pass("emailpassword"),
    }

Functions used to extend the DSL will be called only when needed: when matching for attributes used in matching, or once a form is applied, for attributes used in form application.

#### Parameters

- extensions
  Type: table
  The table of functions extending the formfiller DSL.

## Attribution

#### Copyright

- 2011 Fabian Streitel
- 2011 Mason Larobina