English | 简体中文
sample-gradle-plugin
We often write demo applications that contain a lot of template code, such as lists of different demo cases, jump logic, application permissions and fake data, and more.
SamplePlugin provides various components through annotations and automatically generates this template code so that people viewing the demo application can understand the application more easily.
Download the sample apk to see more: Sample APK.
Minimal supported versions
Due to limited effort, SamplePlugin is currently supported up to version 7.x:
- Minimal supported Gradle version:
7.0.2. - Minimal supported Android Gradle Plugin version:
7.0.0.
Setup
- Add the following code to the root project
build.gradle.ktsfile:
plugins {
id("com.airsaid.sample") version "" apply false
}
- Add the following code to the android application project (app by default)
build.gradle.ktsfile:
plugins {
id("com.airsaid.sample")
}
dependencies {
implementation("com.airsaid:sample-extension:" )
}
Old setup method
- Add the following code to the root project
build.gradle.ktsfile:
buildscript {
dependencies {
classpath("com.airsaid:sample-gradle:" )
}
}
- Add the following code to the android application project (app by default)
build.gradle.ktsfile:
plugins {
id("com.airsaid.sample")
}
dependencies {
implementation("com.airsaid:sample-extension:" )
}
How to use
Register as an example by adding the @Register annotation to the activity or fragment class ( or other supported component) for which the example code is written. For example:
@Register
class DemoFragment : Fragment() {
...
}
Then we run the application and we can see that the example we just registered has appeared in the automatically generated list.
By default, the title of each example item in the list is the class name of the example. If you want to change the title or add a description, you can add the title and desc attributes to the annotation. For example:
@Register(title = "Demo", desc = "Demonstrate how to use.")
class DemoFragment : Fragment() {
...
}
For the case of multiple examples, we organize the relationship between the examples by package name.
For example, suppose this is the structure of your project:
com.airsaid.demo.fragment
FragmentDemo1.kt
FragmentDemo2.kt
com.airsaid.demo.ui
ViewDemo1.kt
ViewDemo2.kt
The result of the automatic generation of the demo list is:
|-- fragment
|-- FragmentDemo1
|-- FragmentDemo2
|-- ui
|-- ViewDemo1
|-- ViewDemo2
That's all, You don't need to do anything. Or you can specify it manually using the path attribute of the @Register annotation. For example:
@Register(path = "android/view")
class DemoFragment : Fragment() {
...
}
Working with testcase
Imagine you have a vast demonstration app, and finding one demo is hard. So you may want to open it directly whenever you launch your app.
The solution is to use the @TestCase annotation, which specifies a test case that will be automatically opened when you start the application. In the case of specifying multiple test cases, a dialog will alert for you to select:
@TestCase
@Register
class DemoFragment : Fragment() {
...
}
Working with extension
We provide a number of extension annotations to easily add additional demos to the sample.
For example, When you use @SampleSourceCode, it will help you generate a ViewPager and put your source code as a list:
@SampleSourceCode
@Register
class DemoFragment : Fragment() {
...
}
Currently, the sample framework itself provides the following extension annotations. Or you can extend it yourself, as seen in the sample application.
@SampleDocument
Display the related document. For example:
// You can specify the documents in the assets directory:
@SampleDocument("assets://sample_document.md")
// Or you can set up an online documentation address:
// @SampleDocument("https://raw.githubusercontent.com/Airsaid/sample-gradle-plugin/master/README.md")
// Or you can specify documents in any directory, e.g. under the same level as the current class:
// @SampleDocument("sample_document.md")
@Register(
title = "SampleDocument",
desc = "Use @SampleDocument to associate documents to sample."
)
class SampleDocumentFragment : Fragment() {
...
}
@SampleSourceCode
Display the source file. For example:
// By default, all source classes of the package where the current class is located are displayed.
@SampleSourceCode
// Or you can use regular expressions that filter only the required classes:
// @SampleSourceCode("SampleSourceCodeFragment.kt")
@Register(
title = "SampleSourceCode",
desc = "Use @SampleSourceCode to associate source code to sample."
)
class SampleSourceCodeFragment : Fragment() {
...
}
@SampleMessage
Display the test message. For example:
@SampleMessage
@Register(
title = "SampleMessage",
desc = "Use @SampleMessage to take the messages output by System.out " +
"and display them on the page."
)
class SampleMessageFragment : Fragment() {
...
}
@SampleMemory
Display the runtime memory. For example:
@SampleMemory
@Register(
title = "SampleMemory",
desc = "Use @SampleMemory to quickly see the current memory usage on the page."
)
class SampleMemoryFragment : Fragment() {
...
}
@SamplePermission
Automatically request specified permissions. For example:
@SamplePermission(
Manifest.permission.CAMERA,
Manifest.permission.READ_EXTERNAL_STORAGE
)
@Register(
title = "SamplePermission",
desc = "Use @SamplePermission and specify the permissions to be requested to " +
"automatically request permissions when the page is first opened."
)
class SamplePermissionFragment : Fragment() {
override fun onActivityCreated(savedInstanceState: Bundle?) {
super.onActivityCreated(savedInstanceState)
addPermissionObserver { result ->
if (result.granted) {
Toast.makeText(context, "${result.name} Permission request successful!", Toast.LENGTH_SHORT)
.show()
} else {
Toast.makeText(context, "${result.name} Permission request failed!", Toast.LENGTH_SHORT)
.show()
}
}
}
...
}
Project structure
- app: the demo app.
- sample-api: common api for both library and plugin.
- sample-core: the core library. Support for core APIs such as the base action processor.
- sample-extension: the extension library. Based on the core library, it provides all kinds of extended functions.
- sample-plugin: GradlePlugin for collecting annotation information at compile time and modifying bytecode files.
License
Copyright 2022 Airsaid. https://github.com/airsaid
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
3.9k Dec 30, 2022
8 Sep 8, 2022
1.4k Dec 29, 2022
3k Dec 29, 2022
24 Jul 26, 2021
29 Nov 9, 2022
8 Jan 2, 2023
1 Nov 12, 2021
853 Dec 21, 2022
345 Dec 10, 2022
4 Dec 15, 2022
21 Oct 3, 2022
0 Dec 23, 2021
960 Dec 18, 2022
2.4k Dec 30, 2022
913 Dec 28, 2022
506 Jan 8, 2023
560 Jan 8, 2023