FairTemplate plug-in use and template co-construction implementation process

⚙️Introduction

Issues with Fair

• Fair currently lacks support for certain syntax, such as "if" and "map", which require the use of specific syntax sugars.
• Some business logic in Fair requires plugins to be implemented, such as network requests and phone calls.
• It can be challenging for developers who are not familiar with Fair syntax to address the above issues.
• While Fair provides examples for developers to reference and use, there are no smaller templates available for direct use by developers.
• Fair developers hope to be able to collaborate on code construction.

FairTemplate's Solutions to Pain Points

1. The Fair development team at 58.com has extracted the code templates for Widgets, Components, and Pages that implement basic capabilities such as network requests, data loading, and display, and collected them into a template repository on Github as a source for online FairTemplate plugins. Developers can load the code templates through an IDEA plugin, choose the templates they need for rapid development, and also contribute their own templates.
2. The FairTemplate plugin provides a fast template creation feature and one-click compilation and packaging capabilities. Users only need to modify the file or class name to quickly compile and preview the template. By replacing the data source, developers can easily meet their development needs. This not only greatly reduces the likelihood of errors that occur during compilation or runtime due to code writing by developers, but also effectively reduces the difficulty of learning Fair for developers.
3. The FairTemplate plugin simplifies the Fair development process and provides developers with a user-friendly online Fair template environment.

📖 Prerequisite Knowledge

1. The Fair online templates are stored in the wuba/FairTemplate repository, which is associated with the wuba/fair repository through git-submodule. Learn more

2. After the association is established, a hyperlink of submodule_name@commit_id will be generated in the main warehouse, click to jump directly to the sub-warehouse and switch to the corresponding commit_id branch. As shown below:

3. The advantage of using git-submodule is that it can establish a direct association with Fair without coupling the code of the Fair repository. In short, the submodule is an independent repository. Normally, cloning the code of the main repository will not clone the code of the submodule repository. If you need to clone it, please refer to git-submodule

💡FairTemplate IDEA plugin

The FairTemplate plugin currently provides the following capabilities:

• Fair Build: One-click compilation and packaging to generate fair products
• Faircli install/server: Extend the faircli script tool, you can create template projects through the command line
• Bundle Upload: connect to the FairPushy hot update platform, and support uploading fair compiled products to the hot update platform
• Fair template creation: users can quickly select and create templates, and support template co-construction

User operation process:

1. FairTemplate plugin installation

If you are doing fair development on Android Studio

1. You can search for FairTemplate in preferences-plugins-Marketplace and install it

2. You can go to jetbrains marketplace to search for FairTemplate and install it

2. Use of FairTemplate plugin

• Quickly create templates

Right-click under the target directory and select FairTemplate to bring up the template gallery page. The operation is shown in the figure below:

• One-click compilation and packaging

Select Fair Plugin on the top bar, click Fair Build to compile and generate the product. It should be noted here that the Fair project needs to be a top-level directory, otherwise this function may fail.

• Docking hot update platform

Fill in the corresponding parameters to upload the fair product to the hot update platform. The prerequisite is to execute the Fair Build to generate the fair product. If you don't understand, you can visit FairPushy to learn more

3. Frequently asked questions about the FairTemplate plugin

• Created a template but there is no corresponding file in the directory?

Refresh the project -> Reload from disk

• The plug-in is always loading?

If it takes a long time to load, it is recommended to visit github.com first to see if it can be opened. If not, please go online scientifically. If you can access GitHub normally, please check the event log for any error message. If there is an error message, you can file an issue on FairTemplate and attach relevant exception information

• How long is the template update interval?

The automatic update time of the template is 12 hours. In the future, we will consider adding an entry to manually trigger the update of the online template

• If you encounter problems related to the FairTemplate plugin, how to give feedback?

At present, the plug-in code is not open source, and related issues can be reported to FairTemplate

🔧Template co-construction

What is template co-construction?

The template co-construction is based on the FairTemplate IDEA plug-in template gallery to realize the function of loading and selecting the fair template code contributed by oneself or others. Every fair developer can contribute their own templates, aiming to create a good fair ecology.

Template co-construction process

• The developer pulls down the wuba/FairTemplate warehouse, if the branch is not main, please switch to main, and the subsequent code also needs to be submitted to the main branch
• Use fair to write the template code with the granularity of Widget/Component/Page and store it in the specified directory
• Submit the written template according to the specified format and create a pr
• The administrator will review and test the submitted code. After passing the review and test, the wuba/FairTemplate warehouse will be tagged and released
• The FairTemplate plug-in updates the template within a certain time interval (12 hours). After the update is completed, the developer can reopen the FairTemplate plug-in to see the submitted template

Template co-construction submission format requirements

Developers need to store and name the files according to the specified format, otherwise the template code will not be loaded and the code review will not be passed.

Submitting a template needs to contain two parts, one part is the template code itself, and the other part is the template cover image.

• template code The template code is divided into three types according to the granularity, namely widget, component and page, all managed in the templates directory

  The submitted formats for widget and page are template directory name/template file name, example: circle_avatar/circle_avatar.dart

  The component is relatively special, and its directory structure corresponds to template directory/standard/template file name and template directory/extra/extra file name, if it only contains dart files, you only need to submit standard, if it contains Non-dart files need to be placed in extra and submitted together. For example: circle_avatar/standard/circle_avatar.dart (if it contains non-dart files:circle_avatar/extra/circle_avatar.js)

• Template cover image

1. The cover image is uniformly placed in the images directory. The cover image currently supports png, webp, and gif formats. Currently, the best compatibility is png. It is recommended to use the png format when submitting

2. How the cover image is associated with the template -> Use the image name to fuzzy match the template directory name. In order to avoid high overlap, it is recommended to be careful and detailed when naming the template. Such as xxx_circle_avatar.png -> circle_avatar

3. The association between the cover image and the template may be modified in the future, and the method of using a mapping table may be considered

Template co-construction core implementation

• git-submodule wuba/fairTemplate is an independent warehouse, and the binding relationship with the main sub-warehouse of wuba/fair warehouse is established through git-submodule, which does not affect the pull and submission of wuba/fair warehouse code
• github restful api With the help of the tags api in the restful api, pull the latest tag url and version number of the online template, perform version comparison, download, decompress and load the online template

🏷 Summary

Thank you for your love and support for fair. You are welcome to use the FairTemplate plug-in in the development process of fair. I also hope that you can provide your own template code to create a good online template ecology~