|
1 | | -# CommonsDemo |
| 1 | +# CommonsDemo |
| 2 | + |
| 3 | +This library provides UI classes used in [Flowing Code Add-ons](https://addonsv24.flowingcode.com/) demos. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +## Tabbed Demo |
| 8 | + |
| 9 | +The central component is the `TabbedDemo` layout, where a `SplitLayout` showcases add-on examples and, optionally, their corresponding source code. The layout accommodates the inclusion of multiple demonstrations in tab form, which allows users to easily switch between different examples for a comprehensive exploration of the add-on features. `TabbedDemo` also has options for choosing between light and dark themes (enabling evaluation of styles in both scenarios), hiding the source code, and switching the orientation of the split layout (by default, it automatically adjusts to vertical or horizontal based on the screen ratio). |
| 10 | + |
| 11 | +``` |
| 12 | +@Route |
| 13 | +@GithubLink("https://github.com/FlowingCode/CommonsDemo") |
| 14 | +public class Demo extends TabbedDemo { |
| 15 | + public Demo() { |
| 16 | + //... |
| 17 | + addDemo(SampleDemo.class, "Demo"); |
| 18 | + addDemo(SampleDemoDefault.class); |
| 19 | + //... |
| 20 | + } |
| 21 | +} |
| 22 | +``` |
| 23 | + |
| 24 | +The `@GithubLink` and `@GithubBranch` annotations allow defaulting the demo sources to a given branch in a _public_ GitHub repository. The `@GithubLink` annotation must be configured with the HTTPS URL to the repository. Private repositories require an access token and are not supported by CommonsDemo. |
| 25 | + |
| 26 | +Different examples can be presented in routed demo views sharing a `TabbedDemo` layout. Since each example has its own route, users can easily reference and access them by using a URL in their web browser. This allows users to directly view the specific example they are interested in exploring. |
| 27 | +``` |
| 28 | +@Route(value = "demo/demo-with-source", layout = Demo.class) |
| 29 | +@PageTitle("Demo with source") |
| 30 | +@DemoSource |
| 31 | +public class SampleDemoDefault extends Div { |
| 32 | + public SampleDemoDefault() { |
| 33 | + add(new Span("Demo component with defaulted @DemoSource annotation")); |
| 34 | + } |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +The demo view can be annotated with `@DemoSource`, in order to configure the URL for retrieving the source code. An optional `value` allows providing a link to the source code, in cases where it differs from the annotated class. When this annotation is used without a value, and the tabbed demo is annotated with `@GithubLink`, the source URL is automatically set to the location of the annotated class under `src/test/java` in the specified GitHub repository. The branch information is derived from the value specified in `@GithubBranch` within the tabbed demo or its containing package. If the source URL is defaulted and no `@GithubBranch` annotation is present either in the tabbed demo or its containing package, then the branch defaults to `master`. |
| 39 | + |
| 40 | +The `@DemoHelper` annotation can be used to link demo views with associated help content provided by `DemoHelperRenderer`. |
| 41 | +The handling of how this help content is presented is managed by `DemoHelperViewer`, which is configured on the `TabbedDemo`. |
| 42 | +By default, help content will be rendered in a `Dialog`. |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +## Code Viewer |
| 47 | + |
| 48 | +The code viewer component (`SourceCodeViewer`) is responsible of rendering a Java source file along the demo. |
| 49 | + |
| 50 | +The rendering process consists of the following steps: |
| 51 | +1. Source code retrieval |
| 52 | +2. License abbreviation |
| 53 | +3. Cleanup (conditional code, boilerplate removal and addition of synthetic sources) |
| 54 | +4. Formatting (provided by [prism.js](https://prismjs.com/)) |
| 55 | +5. Post-processing (fragment highlighting) |
| 56 | + |
| 57 | +### Source code retrieval |
| 58 | +The specified URL (refer to the explanation of `@DemoSource` above) will be used to fetch sources. URLs pointing to `github.com` will be rewritten into `raw.githubusercontent.com` URLs. In development mode, sources will be retrieved from the local `src` directory (if available). |
| 59 | + |
| 60 | +### License abbreviation |
| 61 | + |
| 62 | +A license comment block at the beginning of the file will be replaced with a short two-lines comment (author, year and link to the license terms), provided that: |
| 63 | + |
| 64 | +- The license comment is be placed _before_ the package declaration. |
| 65 | +- The license comment is formatted by [license-maven-plugin](https://www.mojohaus.org/license-maven-plugin) with default delimiters. |
| 66 | +- The license is a well-known license supported by CommonsDemo. |
| 67 | + |
| 68 | +The following well-known licenses are currently supported by CommonsDemo: |
| 69 | +- [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| 70 | + |
| 71 | +This feature cannot be disabled. |
| 72 | + |
| 73 | +**Example** |
| 74 | + |
| 75 | +If the source starts with: |
| 76 | +``` |
| 77 | +/*- |
| 78 | + * #%L |
| 79 | + * Example |
| 80 | + * %% |
| 81 | + * Copyright (C) 2019 - 2023 Flowing Code |
| 82 | + * %% |
| 83 | + * Licensed under the Apache License, Version 2.0 (the "License"); |
| 84 | + * you may not use this file except in compliance with the License. |
| 85 | + * You may obtain a copy of the License at |
| 86 | + * |
| 87 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 88 | + * |
| 89 | + * Unless required by applicable law or agreed to in writing, software |
| 90 | + * distributed under the License is distributed on an "AS IS" BASIS, |
| 91 | + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 92 | + * See the License for the specific language governing permissions and |
| 93 | + * limitations under the License. |
| 94 | + * #L% |
| 95 | + */ |
| 96 | +``` |
| 97 | + |
| 98 | +It will be rendered as: |
| 99 | +``` |
| 100 | +//Copyright (C) 2019 - 2023 Flowing Code |
| 101 | +//Licensed under the Apache License, Version 2.0 |
| 102 | +``` |
| 103 | + |
| 104 | +### Boilerplate removal |
| 105 | + |
| 106 | +Commonly used boilerplate code from source snippets is automatically hidden: |
| 107 | + |
| 108 | +- The package declaration |
| 109 | +- All lines with a `// hide-source` comment |
| 110 | +- The following annotations and their imports: |
| 111 | + - `@com.vaadin.flow.router.Route` |
| 112 | + - `@com.vaadin.flow.router.PageTitle` |
| 113 | + - `@com.flowingcode.vaadin.addons.demo.DemoSource` |
| 114 | + - `@java.lang.SupressWarning` |
| 115 | + - `@org.junit.Ignore` |
| 116 | +- Calls to `SourceCodeViewer.highlightOnHover` and `SourceCodeViewer.highlight` |
| 117 | + |
| 118 | +This feature cannot be disabled. |
| 119 | + |
| 120 | +<!-- FROM https://github.com/FlowingCode/CommonsDemo/pull/37 --> |
| 121 | + |
| 122 | + |
| 123 | +### Synthetic source |
| 124 | + |
| 125 | +This feature allows comments to be formatted as if they were code. When used together with the `// hide-source` feature, it can improve the clarity of the example, particularly in scenarios where techniques like reflection are employed in order to circumvent binary compatibility issues. |
| 126 | + |
| 127 | +For instance, if the demo source is: |
| 128 | + |
| 129 | +``` |
| 130 | +// show-source foo.bar(); |
| 131 | +Method m = Foo.class.getMethod("bar"); // hide-source |
| 132 | +m.invoke(foo); // hide-source |
| 133 | +``` |
| 134 | + |
| 135 | +It will be rendered as: |
| 136 | +``` |
| 137 | +foo.bar(); |
| 138 | +``` |
| 139 | + |
| 140 | +### Conditional code |
| 141 | + |
| 142 | +This feature allows controlling the code block rendering, depending on the version of the framework being used. |
| 143 | + |
| 144 | +For instance, the following source would be rendered as `foo();` in Vaadin 23+, `bar()` in Vaadin 22 and `baz()` in other versions of the framework: |
| 145 | +``` |
| 146 | +// #if vaadin ge 23 |
| 147 | +// show-source foo(); |
| 148 | +// #elif vaadin eq 22 |
| 149 | +// show-source bar(); |
| 150 | +// #else |
| 151 | +// show-source baz(); |
| 152 | +// #endif |
| 153 | +``` |
| 154 | + |
| 155 | +**Directives:** `#if`, `#elif` (else-if), `#else`, `#endif`. Nested conditionals are supported. |
| 156 | + |
| 157 | +**Syntax:** `#if variable operator value` |
| 158 | +- Supported variables are "vaadin" and "flow". (Note that Vaadin 14 uses Flow 1.x.x) |
| 159 | +- Supported operators are `lt`, `le`, `ne`, `eq`, `gt`, `ge`. |
| 160 | +- Value is a one-digit (`x`), two-digit (`x.y`) or three-digit (`x.y.z`) version number |
| 161 | + |
| 162 | +Strictly, the constructor of `SourceCodeViewer` receives a map with arbitrary variables defined by the caller, and `TabbedDemo` defines "vaadin" and "flow" variables. Implementation details in PR https://github.com/FlowingCode/CommonsDemo/pull/44. |
| 163 | + |
| 164 | +### Fragment highlighting |
| 165 | + |
| 166 | +This feature supports highlighting a source code fragment in order to emphasize a section of the code snippet. |
| 167 | +The highlighted fragment is automatically scrolled into view. |
| 168 | + |
| 169 | +A fragment is highlighted either by calling `SourceCodeViewer.highlight(name)` or when hovering a component that has been configured with `SourceCodeViewer.highlightOnHover(component,name)`, where `name` is the name of the fragment. `SourceCodeViewer.highlight(null)` turn off the highlighting. |
| 170 | + |
| 171 | +In the source code, a fragment is delimited by `// begin-block name` and `// end-block` comments. Nested fragments are not supported. |
| 172 | +The `// begin-block` and `// end-block` comments are removed after post-processing. |
| 173 | + |
| 174 | +``` |
| 175 | + // begin-block first |
| 176 | + Div first = new Div(new Text("First")); |
| 177 | + SourceCodeViewer.highlightOnHover(first, "first"); |
| 178 | + add(first); |
| 179 | + // end-block |
| 180 | +``` |
| 181 | + |
| 182 | +<!-- FROM https://github.com/FlowingCode/CommonsDemo/pull/62 --> |
| 183 | + |
| 184 | + |
0 commit comments