Skip to content

Commit ddd4dce

Browse files
danciaclaradanciaclara
authored
Merge pull request #477 from makeplane/editor-block-tabs
Tabs, new widgets, Jira updates and more
2 parents f74b222 + 72ab80c commit ddd4dce

5 files changed

Lines changed: 310 additions & 116 deletions

File tree

‎docs/automations/custom-automations.md‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -156,14 +156,19 @@ Conditions let you filter which work items an automation acts on. You can combin
156156

157157
Updates a field on the work item.
158158

159-
| Property | What you can do |
160-
| ---------- | ---------------------------------------------------------------------- |
161-
| Priority | Set, add, or remove a priority level (Urgent, High, Medium, Low, None) |
162-
| State | Move the work item to a specific state |
163-
| Assignees | Add or remove assignees |
164-
| Labels | Add, remove, or replace all labels |
165-
| Start date | Set, update, or remove the start date |
166-
| Due date | Set, update, or remove the due date |
159+
| Property | What you can do |
160+
| ---------- | -------------------------------------------------------------------------------------------------- |
161+
| Priority | Set, add, or remove a priority level (Urgent, High, Medium, Low, None) |
162+
| State | Move the work item to a specific state |
163+
| Assignees | Add or remove assignees |
164+
| Labels | Add, remove, or replace all labels |
165+
| Start date | Set, update, or remove the start date |
166+
| Due date | Set, update, or remove the due date |
167+
| Cycle | Assign the work item to a cycle, move it to a different cycle, or remove it from its current cycle |
168+
169+
:::tip
170+
When assigning a cycle, the cycle must belong to the work item's own project, and you cannot assign a work item to a cycle that has already ended. A work item can be in only one cycle at a time, so assigning a cycle moves the work item off any cycle it is currently in.
171+
:::
167172

168173
#### Add comment
169174

@@ -299,3 +304,5 @@ Some common things people use automations for.
299304
- **Contextual reminders.** Surface the right information at the right moment - for example, post an internal comment with a checklist when a work item enters "Ready for QA," or flag missing information when a work item is created without an assignee.
300305

301306
- **Scheduled operations.** Run scripts on a timer to handle things that don't map to a single event - for example, sweep stale items weekly, sync data to an external tool nightly, or generate a status comment on open items every Monday morning.
307+
308+
- **Sprint assignment.** Put work items into the right cycle automatically - for example, add a work item to the current cycle when its state changes to "In Progress," or remove it from its cycle when it moves to "Backlog."

‎docs/core-concepts/issues/plane-query-language.md‎

Lines changed: 100 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Filter work items using text-based queries with Plane Query Languag
55

66
# Plane Query Language (PQL) <Badge type="info" text="Pro" />
77

8-
Plane Query Language (PQL) lets you filter work items using text-based queries. Write structured expressions to quickly find exactly what you need.
8+
Plane Query Language (PQL) lets you filter work items using text-based queries. Write structured expressions to quickly find exactly what you need, combine conditions with logic, call built-in functions, and sort and limit the results.
99

1010
![PQL editor](https://media.docs.plane.so/issues/pql-editor.webp#hero)
1111

@@ -17,7 +17,7 @@ To switch to PQL mode, click **PQL** in the filter bar.
1717

1818
When you start typing in the PQL field:
1919

20-
1. A dropdown shows available **fields**
20+
1. A dropdown shows available **fields** and **functions**
2121
2. After selecting a field, you see **operators**
2222
3. Then you choose or type **values**
2323
4. Continue building your query using **AND** or **OR**
@@ -40,7 +40,7 @@ priority = High
4040

4141
This returns all work items where priority is High.
4242

43-
You can also combine multiple conditions using logical operators like `AND` and `OR`.
43+
You can also combine multiple conditions using the logical operators `AND`, `OR`, and `NOT`.
4444

4545
**Using AND**
4646

@@ -58,12 +58,33 @@ state = Todo OR state = In Progress
5858

5959
This returns work items that match either condition.
6060

61+
**Using NOT**
62+
63+
```
64+
NOT hasNoAssignee()
65+
```
66+
67+
This returns work items that do have an assignee.
68+
6169
**Combined:**
6270

6371
```
6472
(priority = High AND state in (Backlog, In Progress, Todo)) OR (type in (Bug, Task, Improvements) AND assignee in (Ethan, Parker, Amanda))
6573
```
6674

75+
## Sort and limit results
76+
77+
You can sort results and cap how many are returned by adding `ORDER BY` and `LIMIT` clauses to the end of a query.
78+
79+
```
80+
priority = High ORDER BY dueDate ASC LIMIT 20
81+
```
82+
83+
- **ORDER BY** sorts the results by a field. Add `ASC` (ascending, the default) or `DESC` (descending).
84+
- **LIMIT** caps the number of results returned. The maximum is 1000.
85+
86+
Fields you can sort by: `priority`, `state`, `title`, `assignee`, `label`, `module`, `startDate`, `dueDate`, `createdAt`, `updatedAt`, `sortOrder`, `rank`.
87+
6788
## Save as view
6889

6990
Once you've built your query, click **Save view** to preserve it for quick access later. See [Views](/core-concepts/views) for details.
@@ -79,6 +100,40 @@ PQL is available wherever work items are listed:
79100
- Teamspace work items
80101
- Workspace views
81102

103+
The exact fields available in the editor depend on what is enabled for the project or workspace you are filtering. For example, `cycle` and `module` appear where those features are on, and custom properties appear when your work item types define them.
104+
105+
## Fields reference
106+
107+
### Text search
108+
109+
| Field | What it searches |
110+
| ------- | ----------------------------------------------------------------------- |
111+
| `title` | The work item title (name) only |
112+
| `text` | The work item title **and** description together, in a single condition |
113+
114+
Use `text` when you want to match a term whether it appears in the title or the body of a work item. For example, `text ~ "login"` returns work items with "login" in the title or the description.
115+
116+
### Common fields
117+
118+
| Field | Filters on |
119+
| ------------ | --------------------------------------------------------------- |
120+
| `type` | Work item type |
121+
| `state` | Workflow state |
122+
| `stateGroup` | State group (Backlog, Unstarted, Started, Completed, Cancelled) |
123+
| `priority` | Priority (Urgent, High, Medium, Low, None) |
124+
| `assignee` | Assigned members |
125+
| `label` | Labels applied |
126+
| `cycle` | Cycle membership |
127+
| `module` | Module membership |
128+
| `milestone` | Milestone |
129+
| `mention` | Members mentioned in the work item |
130+
| `createdBy` | Who created the work item |
131+
| `project` | Project the work item belongs to |
132+
| `startDate` | Start date |
133+
| `dueDate` | Due date |
134+
| `createdAt` | Creation date |
135+
| `updatedAt` | Last updated date |
136+
82137
## Operators reference
83138

84139
Each field supports different operators. The available operators depend on the field type.
@@ -99,6 +154,14 @@ Each field supports different operators. The available operators depend on the f
99154
| `!=` | Title does not match |
100155
| `~` | Title contains text |
101156

157+
### text
158+
159+
| Operator | Description |
160+
| -------- | -------------------------------------------- |
161+
| `=` | Title or description matches the text |
162+
| `!=` | Title or description does not match the text |
163+
| `~` | Title or description contains the text |
164+
102165
### type
103166

104167
| Operator | Description |
@@ -331,14 +394,37 @@ The available operators depend on the property type.
331394

332395
## Built-in functions
333396

334-
PQL includes functions to filter work items based on common scenarios. These functions return a boolean value (`true` or `false`).
335-
336-
| Function | Description |
337-
| --------------------- | ----------------------------------- |
338-
| `isOverdue` | Due date is past and state is open |
339-
| `hasNoAssignee` | Work item has no assignee |
340-
| `hasNoLabel` | Work item has no labels |
341-
| `isTopLevel` | Not a sub-work item (has no parent) |
342-
| `isSubWorkItem` | Is a sub-work item (has a parent) |
343-
| `hasChildren` | Has at least one sub-work item |
344-
| `hasStartAndDueDates` | Has both start and due dates |
397+
PQL includes functions that cover common scenarios. Type `(` after a field, or start typing a function name, and the editor suggests the ones that fit.
398+
399+
### Predicate functions
400+
401+
These are standalone conditions that return true or false. Use them on their own (and combine with `NOT` to invert).
402+
403+
| Function | Matches work items that |
404+
| ----------------------- | -------------------------------------- |
405+
| `isOverdue()` | Are past their due date and still open |
406+
| `hasNoAssignee()` | Have no assignee |
407+
| `hasNoLabel()` | Have no labels |
408+
| `isTopLevel()` | Are not a sub-work item (no parent) |
409+
| `isSubWorkItem()` | Are a sub-work item (have a parent) |
410+
| `hasChildren()` | Have at least one sub-work item |
411+
| `hasStartAndDueDates()` | Have both a start date and a due date |
412+
413+
### Relation functions
414+
415+
These match work items by their relationship to other work items. Each takes one or more work item identifiers (for example `PROJ-123`).
416+
417+
| Function | Matches work items that |
418+
| -------------------------- | --------------------------------------- |
419+
| `blockedBy("PROJ-1", …)` | Are blocked by the given items |
420+
| `blocks("PROJ-1", …)` | Block the given items |
421+
| `linkedTo("PROJ-1", …)` | Are related to the given items |
422+
| `duplicateOf("PROJ-1", …)` | Are marked duplicate of the given items |
423+
| `childOf("PROJ-1", …)` | Are a child of the given items |
424+
| `parentOf("PROJ-1", …)` | Are a parent of the given items |
425+
426+
Example:
427+
428+
```
429+
blockedBy("PROJ-42")
430+
```

‎docs/core-concepts/pages/editor-blocks.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,32 @@ Use the slash command to insert the layout you need:
9696

9797
Each column appears with an "Add content" placeholder where you can add any block type - text, lists, code, images, and more.
9898

99+
## Tabs <Badge type="tip" text="Business" />
100+
101+
Tabs let you organize content into a tabbed block within a page, so related sections can share one space and readers switch between them instead of scrolling. You can lay tabs out horizontally (along the top) or vertically (down the side).
102+
103+
### Insert tabs
104+
105+
Type `/tabs` in the editor and choose one of:
106+
107+
- **Horizontal tabs** - the tab labels run along the top of the block.
108+
- **Vertical tabs** - the tab labels run down the side of the block.
109+
110+
A new block is inserted with two tabs, named "Tab 1" and "Tab 2". Each tab holds its own content, and you can put any editor content inside a tab, including text, lists, images, and other blocks.
111+
112+
### Rename a tab
113+
114+
Double-click a tab label, type the new name, and press Enter (or click away) to save.
115+
116+
### Change the layout
117+
118+
While editing, use the layout controls on the block to switch between horizontal and vertical orientation at any time. Your tabs and their content are preserved.
119+
120+
### Notes
121+
122+
- Tabs cannot be nested. You cannot insert a tabs block inside another tabs block.
123+
- In read-only or published pages, readers can switch between tabs but cannot add, rename, delete, or edit them.
124+
99125
## Video <Badge type="info" text="Pro" />
100126

101127
Embeds video content directly into your pages for rich multimedia documentation.

0 commit comments

Comments
 (0)