Best Practices for sharing field plug-ins

If you want to develop and share a field plug-in, we suggest that you follow our guidelines regarding the structure and content of your repositories. This will ensure that users can easily find and navigate your plug-in repository. For an example of how a non-baseline field plug-in repository should look, see the call-phone-number field plug-in. Below are the guidelines you should follow when sharing your field plug-in

By the stage, if you are thinking about sharing, you should have already developed and tested a field plug-in, and be satisfied that it is working. To learn more, check out our guide to creating field plug-ins.

1. Repository

You should set up your repository in a specific way.

Descriptive Characteristics

  1. Add the topic scto-field-plug-in to your repository.

This will allow your field plug-in to show up when users search for that topic.

  1. Add a repository description

The description of a repository tells the public what the repository is for. This is what will appear under each repository title on an organization's GitHub page. Anyone who takes a quick look at the GitHub page should be able to determine what a field plug-in does just by looking at the description, so it should be clear, concise, and descriptive. It should be about 1 or 2 sentences.

Structure and organization

  1. Keep the license, README, and field plug-in .zip file in the root of the repository.
  2. Keep all source files in a source folder (/source/).
  3. Keep all other files in an extras folder (/extras/).

This includes image previews, sample forms, and other associated files that you may want to store in your repository. In addition, the sample form files (including the form definition and other attachments) should be in its own folder within the extras folder.

Upkeep

  1. Keep your .zip file up-to-date.

Keep the most recent version of your x.fieldpliugin.zip file in the root of your repository. Most users will only be looking for that file, and they will not bother looking around in subdirectories, or zipping their own version. Every time you push changes to your source code, you should re-compress and push that .zip file as well.

2. README

Your README should be specific to your field plug-in, user focused, and contain the following sections:

2.1. Title (required)

The title must be short and intuitive, clearly explaining the field plug-in. Other than spaces, hyphens, and underscores, it should have the same name as the field plug-in.

2.2. Image preview (optional).

This should be a clear screenshot, or set of screenshots that illustrate the functionality or usage of the field plug-in. These live in the /extras/ folder.

2.3. Description (required)

  • Introduction (required, doesn't need a heading)
    This should be a brief description of the aims of the field plug-in, detailing what new functionality it adds, and the motivation for its development. Consider answering questions like what is it, what purpose does it serve and why would you use it in this section.
    This should not be long (no more than 10 lines in most cases). If you need to add extra information, consider using a wiki.
    This is different from the repo description (see above).
  • [Download button] (beta download button to begin with)
    This button should provide a direct link to downloading the field plug-in. Use the standard button images - beta and release.
  • Features (optional)
    If the field plug-in is more complex and the features can't be easily summarized in the introduction, highlight the key features of the field plug-in in this section for easy reference. 
  • Data format (required)
    This should clearly indicate which field type(s) are supported by the field plug-in and if needed, also show how the response is stored. 

2.4. How to use (required)

  • Getting started (required)
    This should provide basic step-by-step instructions on how the user can deploy and use the field plug-in. If more detailed instructions would be helpful, consider using a wiki.
  • Parameters (optional)
    If the field plugin has parameters, provide a list of them, clearly specifying which are required and which are optional. It should also include examples demonstrating different combinations of parameters where applicable.
  • Default SurveyCTO feature support (optional)
    If a field using the field plug-in is recognizably and functionally the source field type (i.e. it still behaves like a text field, for example), include this section. Specify the default field features that are supported by the field plug-in (e.g. that your text field plug-in supports the "numbers" appearance option). The best way to display the feature support is with a table; you can copy the feature support table used in the baseline field plug-ins, and modify as needed.

2.5. More resources

This should include information about where the user can access related resources, such as a sample form and the developer documentation.

3. Sample form/s

This should be a simple form that demonstrates the functionality of your field plug-in. This goes in the /extras/sample-form/ folder.

4. Wiki (optional)

Some complex field plug-ins will require a detailed explanation of its rationale and functionality. Use the wiki to outline as much information as necessary.

0 Comments

Please sign in to leave a comment.