Creating a New Feature

This tutorial will walk you through creating a simple feature for the WikiTree Browser Extension (WBE).

Prerequisites

This tutorial assumes you have the following:

An account on GitHub.
A code editor and terminal access (this tutorial will be using Visual Studio Code).
The Google Chrome or Mozilla Firefox browser.

Optional: If you prefer using a graphical interface for Git operations, install GitHub Desktop.

Forking the Repository

Sign into your GitHub account.

Go to the WikiTree Browser Extension Code Repository.

Click the "Fork" button at the top right. This will take you to a page titled "Create a new fork". You can leave everything as default. Press the "Create fork" button.

You should now have a copy of the repository saved to your GitHub account.

Downloading the Code

Once you have forked the repository, you need to download the code to your local machine. You can do this using either GitHub Desktop, the Terminal, or Visual Studio Code. Choose the method you're most comfortable with.

Using GitHub Desktop

Open GitHub Desktop and sign in if prompted.
Go to your forked repository on GitHub, click the green "Code" button, and select "Open with GitHub Desktop".
Choose a location to clone the repository on your computer, and click "Clone".
After cloning, GitHub Desktop will ask how you plan to use this fork. Choose "To contribute to the parent project".
Click "Open in Visual Studio Code" to start working on the code.

Using the Terminal

Go to your code repository on GitHub, click the green "Code" button, and copy the HTTPS link that is shown.
Open your terminal and run the following command to clone the repository:
```
git clone https://github.com/your-username/wikitree-browser-extension.git
```
Replace your-username with your actual GitHub username.
Navigate to the directory where the repository was cloned:
```
cd wikitree-browser-extension
```

Using Visual Studio Code

Upon opening Visual Studio Code, you should be brought to a "Welcome" page. If you don't see this page, you can access it by going to Help > Welcome in the menu.

Under "Start", there is an option to "Clone Git Repository". When you click that, it will ask for a URL.

Go to your code repository on GitHub, click the green "Code" button, and copy the HTTPS link that is shown. Enter that into VS Code and select "Clone from URL".

Select where you would like to save the code on your computer.

After it has been cloned, select "Open" in VS Code.

You should now see the code files in the left-hand sidebar.

Installing Dependencies

You will need to install the project’s dependencies using NPM.

WBE uses a package manager called NPM (Node Package Manager). If you have never used it before, you will need to install it. The instructions for installing it can be found at the npm website.

Once npm is installed on your computer, open a terminal in VS Code by selecting Terminal > New Terminal from the menu.

Then, type the following command to install the necessary dependencies for WBE:

npm install

Testing WBE locally

You should now have a copy of the extension code on your computer.

You will have to build the browser extension before you can test it.

In the terminal, type:

npm run build-dev

Testing in Google Chrome

In Chrome, type chrome://extensions in the address bar.

At the top right of that page, there should be a "Developer Mode" toggle. Make sure it is switched on.

Make sure all other versions of the WikiTree Browser Extension are disabled.

At the top left of the page, click the "Load Unpacked" button. Navigate to the folder where you've downloaded the code, and select the wikitree-browser-extension/dist folder. This should load the extension into your browser so you can test it.

Testing in Mozilla Firefox

To test in Firefox, follow these steps:

Build the extension for Firefox by typing:
```
npm run build-firefox-dev
```
Open Firefox and navigate to about:debugging#/runtime/this-firefox.
Click on "Load Temporary Add-on...".
Navigate to the wikitree-browser-extension/dist folder and select the manifest.json file.
The extension should now be listed under "Temporary Extensions".

Note: Temporary extensions will be removed when Firefox is closed. For persistent testing, consider using Firefox Developer Edition.

Setting up a new feature

The first thing you want to do before writing a new feature is to switch to a new branch in Git. In the terminal, type:

git checkout -b helloWorld

Using GitHub Desktop

If you are using GitHub Desktop, follow these steps:

Open GitHub Desktop and ensure your forked repository is selected.
Create a new branch by clicking on the "Current Branch" dropdown and selecting "New Branch".
Enter helloWorld as the branch name and click "Create Branch".

Now that you are on the new branch, use the create-feature script to set up your files.

Setting Up a New Feature Using the Automation Script

We now have a script that can automate much of the setup process for a new feature. Instead of manually creating files and adding entries to existing files, you can use this script to quickly scaffold everything.

Before Using the Script

There are a few things you need to understand before using the feature creation script:

Page Types: These are used to specify where the feature should be applied. Some common page types include:
- isProfilePage
- isProfileEdit
- isSpacePage
- isSpaceEdit
- isMainDomain
- ... and more.
To see the full list of available page types, you can look at the file src/core/page_type.js.
Categories: The categories are used to classify the feature within the extension. The available categories are:
- Global
- Global/Style
- Profile
- Editing
- Editing/Add_Person
- Editing/Edit_Profile
- Navigation
- Navigation/Find_Menu
- Community

Running the Script

To create a new feature, navigate to the root directory of the project in your terminal and run:

node scripts/create-feature.js -f hello_world -a "Author Name" -i AuthorID -c Profile -p isProfilePage

Arguments:

-f or --featureName: The name of the new feature in snake_case (e.g., new_feature_name).
-a or --authorName: The name of the author creating the feature (e.g., Jane Doe).
-i or --authorId: The ID of the author (e.g., Doe-123).
-c or --category: The category for the feature (from the list above).
-p or --pageTypes: A comma-separated list of page types this feature applies to (e.g., isProfilePage, isSpacePage).

What the Script Does

Generates Feature Files: The script will create a new folder in src/features with the name of the new feature. In that folder, it will create:
- hello_world.js: The main script for your feature.
- hello_world_options.js: The options file where the feature is registered.
- hello_world.css: A CSS file for any styles that the feature may need.
Updates Configuration Files:
- Adds an import statement to content.js for the new feature.
- Adds an import statement to register_feature_options.js in alphabetical order, ensuring the new feature's options are correctly registered.

Writing your feature code

Once you've run the script, you can continue developing your feature. Open the generated hello_world.js file (in src/features/hello_world/) to add the specific functionality you want your feature to have. Here’s an example of what it might look like after the script has created it:

import { shouldInitializeFeature } from "../../core/options/options_storage";

shouldInitializeFeature("helloWorld").then((result) => {
  if (result) {
    init();
  }
});

This ensures that your feature will only initialize if it has been enabled by the user in the options menu.

Now it's time to write the feature code!

This simple feature will just change the header of a profile from Name to Hello, Name.

The HTML for the header looks like this:

<h1>
  <span itemprop="name">Daniel George Nelson</span>
  ...
</h1>

To grab the name and make changes we want to:

Use jQuery to make changing the DOM a bit easier: import $ from "jquery".
Grab the element that has the name of the profile and save it: const nameElement = $('h1 > [itemprop="name"]');.
Get the name inside of that element and save it: const nameText = nameElement.text();.
Change the text inside of the element to our desired text: $(nameElement).text(\Hello, ${nameText}`);`.

Combining those, the final code in hello_world.js should look like this:

import { shouldInitializeFeature, getFeatureOptions } from "../../core/options/options_storage";
import $ from "jquery";

shouldInitializeFeature("helloWorld").then((result) => {
  if (result) {
    const nameElement = $('h1 > [itemprop="name"]');
    const nameText = nameElement.text();
    $(nameElement).text(`Hello, ${nameText}`);
  }
});

Once you've saved and rebuilt the extension, go to a profile page and you should see "Hello, Name" at the top of the profile.

If you don't see any changes to the profile, you may need to go to chrome://extensions or about:debugging#/runtime/this-firefox and click the reload button next to the extension, then reload the profile page.

Requesting to add your code to the shared repo

Now that your feature is finished, you want that feature to be added to the shared code repository on GitHub.

In the terminal, type:

git status

This will show you which files have been changed.

Since we want to include all the files that have been changed, type:

git add .

Now you want to commit the changes with a short message about what was changed. Type:

git commit -m "Add Hello World feature."

Now you want to add those changes to your GitHub repository. Type:

git push --set-upstream origin helloWorld

This will upload the code to your repository under the branch "helloWorld".

If you go to your GitHub repository, you can now access the "helloWorld" branch in the dropdown on the left.

Once you are viewing that branch, you should see a section that says "This branch is X commits ahead of wikitree/wikitree-browser-extension:development" and a button that says "Contribute".

Click the "Contribute" button, and you will be taken to a form where you can fill out more information about your feature. If this were an actual feature that should be added to the code, you would press the "Create pull request" button to request that the WBE maintainers view your code and add it to the browser extension. But it isn't necessary for this tutorial.

Using GitHub Desktop

If you prefer to use GitHub Desktop to submit your changes, follow these steps:

Open GitHub Desktop and ensure your repository is selected.
You should see a list of changed files under the "Changes" tab.
Click the checkbox next to each file you want to include in the commit (or check all boxes to include all changes).
In the "Summary" field at the bottom left, enter a commit message, such as Add Hello World feature.
Click Commit to helloWorld.
Once the commit is created, click Push origin at the top to upload your changes to your GitHub repository.
GitHub Desktop will provide an option to Create Pull Request. Click this button, and it will open GitHub in your browser with the form pre-filled. Review the details, and press Create pull request to submit your changes for review.

Additional Info

If you ran into any trouble during this tutorial, feel free to ask for help in the WikiTree Discord, the WikiTree Apps Project Google Group, or in G2G with the wt_apps tag.

You can also practice your GitHub skills by improving this tutorial!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tutorial.md

tutorial.md

Creating a New Feature

Prerequisites

Forking the Repository

Downloading the Code

Using GitHub Desktop

Using the Terminal

Using Visual Studio Code

Installing Dependencies

Testing WBE locally

Testing in Google Chrome

Testing in Mozilla Firefox

Setting up a new feature

Using GitHub Desktop

Setting Up a New Feature Using the Automation Script

Before Using the Script

Running the Script

What the Script Does

Writing your feature code

Requesting to add your code to the shared repo

Using GitHub Desktop

Additional Info

Files

tutorial.md

Latest commit

History

tutorial.md

File metadata and controls

Creating a New Feature

Prerequisites

Forking the Repository

Downloading the Code

Using GitHub Desktop

Using the Terminal

Using Visual Studio Code

Installing Dependencies

Testing WBE locally

Testing in Google Chrome

Testing in Mozilla Firefox

Setting up a new feature

Using GitHub Desktop

Setting Up a New Feature Using the Automation Script

Before Using the Script

Running the Script

What the Script Does

Writing your feature code

Requesting to add your code to the shared repo

Using GitHub Desktop

Additional Info