README.md 4.37 KB
Newer Older
Rich's avatar
Rich committed
1
2
3
4
5
# Action Links

Provides an API and an admin's UI to manage a set of links that trigger
Form Processor submissions and redirect to a success/denied URL.

Rich's avatar
Rich committed
6
7
![Screenshot](images/screenshot.png)

Rich's avatar
Rich committed
8
9
10
11
12
The extension is licensed under [AGPL-3.0](LICENSE.txt).

## Requirements

* PHP v7.0+
Rich's avatar
Rich committed
13
* CiviCRM 5.20+
Rich's avatar
Rich committed
14
15
16
17
18
19
20
21
22
23
24
25

## Installation (Web UI)

This extension has not yet been published for installation via the web UI.

## Installation (CLI, Zip)

Sysadmins and developers may download the `.zip` file for this extension and
install it with the command-line tool [cv](https://github.com/civicrm/cv).

```bash
cd <extension-dir>
Rich's avatar
Rich committed
26
cv dl actionlinks@https://lab.civicrm.org/artfulrobot/actionlinks/-/archive/master/actionlinks-master.zip
Rich's avatar
Rich committed
27
28
29
30
31
32
33
34
```

## Installation (CLI, Git)

Sysadmins and developers may clone the [Git](https://en.wikipedia.org/wiki/Git) repo for this extension and
install it with the command-line tool [cv](https://github.com/civicrm/cv).

```bash
Rich's avatar
Rich committed
35
git clone git@lab.civicrm.org:artfulrobot/actionlinks.git
Rich's avatar
Rich committed
36
37
38
39
40
cv en actionlinks
```

## Usage

Rich's avatar
Rich committed
41
42
43
44
45
46
1. Get it installed,

2. then give your admin users the new "Administer Action
   Links Extension" permission.

3. Then head over to **Administer » System Settings » Action Links**
Rich's avatar
Rich committed
47
48
49
50
51
52

### Create your first action link.

Here you can add your first action link. The edit screen is shown in the
screnshot above.

Rich's avatar
Rich committed
53
- *Name*: used for the administrative interface only.
Rich's avatar
Rich committed
54

Rich's avatar
Rich committed
55
- *Description*: same
Rich's avatar
Rich committed
56

Rich's avatar
Rich committed
57
- *Active*: if un-checked users of the link will get the denied/fallback URL
Rich's avatar
Rich committed
58

Rich's avatar
Rich committed
59
- *Link URL*: the web address to the page/resource you want to redirect
Rich's avatar
Rich committed
60
  people to.
Rich's avatar
Rich committed
61

Rich's avatar
Rich committed
62
- *Fallback URL (if denied)*: the web address to redirect people to if
Rich's avatar
Rich committed
63
  they're not alowed the link for any reason.
Rich's avatar
Rich committed
64

Rich's avatar
Rich committed
65
- *Form Processor*: if you have the Form Processor extension, you can pick
Rich's avatar
Rich committed
66
  a form processor to call. This gives you all the logic that extension
Rich's avatar
Rich committed
67
68
69
70
71
72
73
74
75
76
  provides, e.g. creating activities, adding to groups. If you choose one
  then the following configuration is also available:
   - Whether to run the Form Processor every time the link is allowed, or
     only once per contact. e.g. you might want to record that a contact
     has downloaded a resource, but you don't need to know every time they
     downloaded it.
   - Values for the Form Processor's inputs. Note that you can
     (programmatically) add Form Processor input params to the links
     generated. You can't overwrite a configured input, and you can't
     provide a parameter that is not an allowed/expected input.
Rich's avatar
Rich committed
77

Rich's avatar
Rich committed
78
- *Max uses*: the max times the link can be used by anyone. (probably not
Rich's avatar
Rich committed
79
  that useful)
Rich's avatar
Rich committed
80

Rich's avatar
Rich committed
81
- *Max number of unique contacts who can use this.* e.g. "First 10 people to
Rich's avatar
Rich committed
82
  click this get a voucher for a free pie.".
Rich's avatar
Rich committed
83

Rich's avatar
Rich committed
84
- *Number of times each contact is allowed to use this link*.
Rich's avatar
Rich committed
85

Rich's avatar
Rich committed
86
87
- *When to stop allowing access*.

Rich's avatar
Rich committed
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

### Create links for contacts

Currently the only way to get a usable link is via the API. You can use
the command line (shown below) or the APIv4 explorer (**Support
» Developer » Api Explorer v4**) or any other method (php, angular, js...)
for this.

You'll need the ID of the link, and the ID(s) of the contacts you want to
make th links for, e.g.

e.g.

```
cv api4 ActionLink.getLink '{"actionLinkID":1, "contactIDs":[1, 2, 3]}'

{
    "0": {
        "contactID": 1,
        "link": "https://example.com/civicrm/actionlink?alid=1&cid=1&cs=f1cf81a779fce9d6d3217b9f3338c8ef_1582107927_inf"
    },
    "1": {
        "contactID": 2,
        "link": "https://example.com/civicrm/actionlink?alid=1&cid=2&cs=1284819e3a049f21a769cf89fdaf297e_1582107927_inf"
    },
    "2": {
        "contactID": 3,
        "link": "https://example.com/civicrm/actionlink?alid=1&cid=3&cs=4d1a15f4b048798204df98f0e74b6733_1582107927_inf"
    }
}
```
Rich's avatar
Rich committed
119

Rich's avatar
Rich committed
120
### Feedback / testers / ideas / bugs welcome
Rich's avatar
Rich committed
121

Rich's avatar
Rich committed
122
123
124
Please use the [issue
queue](https://lab.civicrm.org/artfulrobot/actionlinks/issues) or contact
me (@artfulrobot) on [chat.civicrm.org](https://chat.civicrm.org).
Rich's avatar
Rich committed
125
126
127
128
129
130
131
132
133
134

## Tokens

There's 2 types of token available and I'm not exactly sure when to use
each. (If you can clarify, please do a PR!)

There's the old skool way, which you can use in Message Templates for
example. You should enter tokens like:

```
135
Hey, click this: {actionlink.id1}
Rich's avatar
Rich committed
136
137
138
139
140
141
142
143
144
145
146
147
148
149
```

where `1` is the Action Link ID.

And there's the new way using TokenProcessor, for which you need to write
tokens like this:

```
Hey, click this: {contact.actionLink1}
```

(note the camelCase in this instance. This is just to keep you on your
toes.)