| # Providing Outlines |
| |
| Outline information is used by clients to allow users to see the structure of |
| their code. |
| |
| ## Implementation details |
| |
| Outline information is available through a subscription. If the server has |
| subscribed for outline information in some set of files, then the plugin should |
| send the information in an `analysis.outline` notification whenever the |
| information needs to be updated. |
| |
| When a notification needs to be sent, the method `sendOutlineNotification` will |
| be invoked. This method is responsible for sending the notification. |
| |
| The easiest way to add support for this notification is by adding the classes |
| `OutlineMixin` and `DartOutlineMixin` (from |
| `package:analyzer_plugin/plugin/outline_mixin.dart`) to the list of mixins |
| for your subclass of `ServerPlugin`. This will leave you with one abstract |
| method that you need to implement: `getOutlineContributors`. That method is |
| responsible for returning a list of `OutlineContributor`s. It is the outline |
| contributors that produce the actual outline information. (Most plugins will |
| only need a single outline contributor.) |
| |
| To write an outline contributor, create a class that implements |
| `OutlineContributor`. The interface defines a single method named |
| `computeOutline`. The method has two arguments: an `OutlineRequest` that |
| describes the file for which outline information is being requested and an |
| `OutlineCollector` through which outline information is to be added. |
| |
| If you mix in the class `DartOutlineMixin`, then the request will be an instance |
| of `DartOutlineRequest`, which also has analysis results. |
| |
| ## Example |
| |
| Start by creating a class that implements `OutlineContributor`, then |
| implement the method `computeOutline`. This method is typically implemented |
| by creating a visitor (such as an AstVisitor) that can visit the results of the |
| analysis (such as a CompilationUnit) and extract the outline information from |
| the analysis result. |
| |
| For example, your contributor might look something like the following: |
| |
| ```dart |
| class MyOutlineContributor implements OutlineContributor { |
| @override |
| void computeOutline( |
| OutlineRequest request, OutlineCollector collector) { |
| if (request is DartOutlineRequest) { |
| OutlineVisitor visitor = new OutlineVisitor(collector); |
| request.result.unit.accept(visitor); |
| } |
| } |
| } |
| |
| class OutlineVisitor extends RecursiveAstVisitor { |
| final OutlineCollector collector; |
| |
| OutlineVisitor(this.collector); |
| |
| @override |
| void visitClassDeclaration(ClassDeclaration node) { |
| // ... |
| } |
| } |
| ``` |
| |
| Given a contributor like the one above, you can implement your plugin similar to |
| the following: |
| |
| ```dart |
| class MyPlugin extends ServerPlugin with OutlineMixin, DartOutlineMixin { |
| // ... |
| |
| @override |
| List<OutlineContributor> getOutlineContributors(String path) { |
| return <OutlineContributor>[new MyOutlineContributor()]; |
| } |
| } |
| ``` |