Contributing

This guide have some instructions and tips on how to create a new IReader extension. Please read it carefully if you're a new contributor or don't have any experience on the required languages and knowledges.

This guide is not definitive and it's being updated over time. If you find any issue on it, feel free to report it through a Meta Issue or fixing it directly by submitting a Pull Request.

Prerequisites

Before you start, please note that the ability to use following technologies is required and that existing contributors will not actively teach them to you.

Basic Android development
Kotlin
Web scraping
- HTML
- CSS selectors
- OkHttp
- JSoup

Tools

Android Studio
Emulator or phone with developer options enabled and a recent version of IReader installed
Icon Generator

Cloning the repository

Some alternative steps can be followed to ignore "repo" branch and skip unrelated sources, which will make it faster to pull, navigate and build. This will also reduce disk usage and network traffic.

Steps

Make sure to delete "repo" branch in your fork. You may also want to disable Actions in the repo settings.

Also make sure you are using the latest version of Git as many commands used here are pretty new.

Do a partial clone.

git clone --filter=blob:none --sparse <fork-repo-url>
cd IReader-extensions/

Getting help

Join the Discord server for online help and to ask questions while developing your extension. When doing so, please ask it in the #app-dev channel.
There are some features and tricks that are not explored in this document. Refer to existing extension code for examples.

Writing an extension

The quickest way to get started is to copy an existing extension's folder structure and renaming it as needed. We also recommend reading through a few existing extensions' code before you start.

Setting up a new Gradle module

Each extension should reside in sources/<lang>/<mysourcename>. Use sources/multisrc if your target source supports multiple languages or if it could support multiple sources.

The <lang> used in the folder inside src should be the major language part. For example, if you will be creating a pt-BR source, use <lang> here as pt only. Inside the source class, use the full locale string instead.

Extension file structure

The simplest extension structure looks like this:

$ tree src/<lang>/<mysourcename>/
sources/<lang>/<mysourcename>/
├── build.gradle
├── res (option 1)
│   ├── mipmap-hdpi
│   │   └── ic_launcher.png
│   ├── mipmap-mdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xhdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xxhdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xxxhdpi
│   │   └── ic_launcher.png
│   └── web_hi_res_512.png
└── main
    └── assets (option 2)
	    └── icon.png
    └── src
	    └── ireader
              └── <mysourcename>
                  └── <MySourceName>.kt

build.gradle

Make sure that your new extension's build.gradle file follows the following structure:

listOf("en").map { lang ->  
  Extension(  
      name = "BoxNovelCom", // no space between letters
	  versionCode = 4,  
	  libVersion = "1",  
	  lang = lang,  
	  description = "",  
	  nsfw = false,  
	  icon = DEFAULT_ICON  // if you want to use a remote image repalce `DEFAULT_ICON` with a link
  )  
}.also(::register)

Field	Description
`name`	The name of the extension.
`versionCode`	The extension version code. This must be a positive integer and incremented with any change to the code.
`libVersion`	(Optional, defaults to `1`) The version of the extensions library used.
`lang`	the language of extension
`description`	the description of extension that you want the users see in the app
`isNsfw`	(Optional, defaults to `false`) Flag to indicate that a source contains NSFW content.
`icon`	default to `DEFAULT_ICON` ,if you want to use a remote image repalce `DEFAULT_ICON` with a link
`sourceDir`	default to `main` for a single extension
`assetsDir`	leave it blank if you you are using local res or if you are using a individual extension
`remoteDependencies`	if you want a dependency that is not available IReader-extension projects

The extension's version name is generated automatically by concatenating libVersion and versionCode. With the example used above, the version would be 1.4.

Core dependencies

Extension API

Extensions rely on extensions-lib, which provides some interfaces and stubs from the app for compilation purposes. The actual implementations can be found here. Referencing the actual implementation will help with understanding extensions' call flow.

Additional dependencies

If you find yourself needing additional functionality, you can add more dependencies to your build.gradle file. Many of the dependencies from the main IReader app are exposed to extensions by default.

Note that several dependencies are already exposed to all extensions via Gradle version catalog. To view which are available view libs.versions.toml under the gradle folder

Notice that we're using compileOnly instead of implementation if the app already contains it. You could use implementation instead for a new dependency, or you prefer not to rely on whatever the main app has at the expense of app size.

Note that using compileOnly restricts you to versions that must be compatible with those used in the latest stable version of IReader.

Extension main class

This class should implement one of the Source implementations: HttpSource or ParsedHttpSource.

Class	Description
`HttpSource`	For online source, where requests are made using HTTP.
`SourceFactory`	An Implementation of `HttpSource` that make source creation easier.

Main class key variables

Field	Description
`name`	Name displayed in the "Sources" tab in IReader.
`baseUrl`	Base URL of the source without any trailing slashes.
`lang`	An ISO 639-1 compliant language code (two letters in lower case in most cases, but can also include the country/dialect part by using a simple dash character).
`id`	Identifier of your source, automatically set in `HttpSource`. It should only be manually overriden if you need to copy an existing autogenerated ID.

Extension call flow

getMangaList(sort: Listing?, page: Int)

a.k.a. the default request that app make

Book Search

When the user searches inside the app, getMangaList will be called
if the filters contain a Filter.Title that has a query then the you need to search for a query
- If search functionality is not available, return Observable.just(MangasPage(emptyList(), false))
getFilterList will be called to get all filters and filter types.

val query = filters.findInstance<Filter.Title>()?.value  
  
if (query != null) {  
    getBooks(query = query) // you need to implement this yourself
}

Filters

The search flow have support to filters that can be added to a FilterList inside the getFilterList method. When the user changes the filters' state, they will be passed to the searchRequest, and they can be iterated to create the request (by getting the filter.state value, where the type varies depending on the Filter used). You can check the filter types available here and in the table below.

Filter	State type	Description
`Filter.Note`	`String`	a note for how to use filters
`Filter.Select<V>`	`Int`	A select control, similar to HTML's `<select>`. Only one item can be selected, and the state is the index of the selected one.
`Filter.Text`	`String`	A text control, similar to HTML's `<input type="text">`.
`Filter.Check`	`Boolean`	A checkbox control, similar to HTML's `<input type="checkbox">`. The state is `true` if it's checked.
`Filter.Group<V>`	`List<V>`	A group of filters (preferentially of the same type). The state will be a `List` with all the states.
`Filter.Sort`	`Selection`	A control for sorting, with support for the ordering. The state indicates which item index is selected and if the sorting is `ascending`.

Book Details

When user taps on a book, getMangaDetails and getChapterList will be called and the results will be cached.
remember to check for commands if you enable some commands.
fetchChapterList is called to display the chapter list.
- The list should be sorted descending by the source order.

Chapter

After a chapter list for the book is fetched and the app is going to cache the data, getChapterList will be called.
ChapterInfo.dateUpload is the UNIX Epoch time expressed in milliseconds.
- If you don't pass ChapterInfo.dateUpload and leave it zero, the app will use the default date instead, but it's recommended to always fill it if it's available.
- To get the time in milliseconds from a date string, you can use a SimpleDateFormat like in the example below.
```
private fun parseDate(dateStr: String): Long {
    return runCatching { DATE_FORMATTER.parse(dateStr)?.time }
        .getOrNull() ?: 0L
}

companion object {
    private val DATE_FORMATTER by lazy {
        SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.ENGLISH)
    }
}
```
  Make sure you make the SimpleDateFormat a class constant or variable so it doesn't get recreated for every chapter. If you need to parse or format dates in manga description, create another instance since SimpleDateFormat is not thread-safe.

Chapter Pages

When user opens a chapter, getPageList will be called and it will return a list of Pages.
you need to parse the html to get a list of Pages, for a novel its a list of Text

Writing an Multisrc Extension

Sometimes you have a common extension that is used for many languages and only some part of it need to be changed in order to create another extension for another website, in this case, we can use MultiSrc directory in sources/multisrc

Multisrc Extension file structure

The simplest extension structure looks like this:

$ tree sources/multisrc/<mysourcename>/
sources/multisrc/<mysourcename>/
├── build.gradle
├── res (option 1)
│   ├── mipmap-hdpi
│   │   └── ic_launcher.png
│   ├── mipmap-mdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xhdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xxhdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xxxhdpi
│   │   └── ic_launcher.png
│   └── web_hi_res_512.png
└── main ( common code that is used for othersources)
│	├── res (option 1)
│	│   ├── mipmap-hdpi
│	│   │   └── ic_launcher.png
│	│   ├── mipmap-mdpi
│	│   │   └── ic_launcher.png
│	│   ├── mipmap-xhdpi
│	│   │   └── ic_launcher.png
│	│   ├── mipmap-xxhdpi
│	│   │   └── ic_launcher.png
│	│   ├── mipmap-xxxhdpi
│	│   │   └── ic_launcher.png
│	│   └── web_hi_res_512.png
│	|
│	├── assets (option 2)
│		    └── icon.png
│    └── src
│	    └── ireader
│              └── <mysourcename>
│                  └── <MySourceName>.kt
├── res (option 1)
│   ├── mipmap-hdpi
│   │   └── ic_launcher.png
│   ├── mipmap-mdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xhdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xxhdpi
│   │   └── ic_launcher.png
│   ├── mipmap-xxxhdpi
│   │   └── ic_launcher.png
│   └── web_hi_res_512.png
└── SiteA ( common code that is used for othersources)
│	├── res (option 1)
│	│   ├── mipmap-hdpi
│	│   │   └── ic_launcher.png
│	│   ├── mipmap-mdpi
│	│   │   └── ic_launcher.png
│	│   ├── mipmap-xhdpi
│	│   │   └── ic_launcher.png
│	│   ├── mipmap-xxhdpi
│	│   │   └── ic_launcher.png
│	│   ├── mipmap-xxxhdpi
│	│   │   └── ic_launcher.png
│	│   └── web_hi_res_512.png
│	|
│	├── assets (option 2)
│		    └── icon.png
│    └── src
│	    └── ireader
│              └── <SiteAName>
│                  └── <SiteAName>.kt
└── SiteB ( Site A )
|	├── res (option 1)
|	│   ├── mipmap-hdpi
|	│   │   └── ic_launcher.png
|	│   ├── mipmap-mdpi
|	│   │   └── ic_launcher.png
|	│   ├── mipmap-xhdpi
|	│   │   └── ic_launcher.png
|	│   ├── mipmap-xxhdpi
|	│   │   └── ic_launcher.png
|	│   ├── mipmap-xxxhdpi
|	│   │   └── ic_launcher.png
|	│   └── web_hi_res_512.png
|	|
|	├── assets (option 2)
|		    └── icon.png
   └── src
	    └── ireader
             └── <SiteBName>
                  └── <SiteBName>.kt

build.gradle

Make sure that your new extension's build.gradle file follows the following structure:

	listOf(  
	     Extension(  
		  name = "SiteA",  
		  versionCode = 1,  
		  libVersion = "1",  
		  lang = "en",  
		  description = "",  
		  nsfw = false,  
		  icon = DEFAULT_ICON,  
		  assetsDir = "multisrc/<mysourcename>/SiteA/assets",  
		  sourceDir = "SiteA",  
		  ),  
		  Extension(  
		        name = "SiteB",  
		  versionCode = 1,  
		  libVersion = "1",  
		  lang = "ar",  
		  description = "",  
		  nsfw = false,  
		  icon = DEFAULT_ICON,  
		  assetsDir = "multisrc/<mysourcename>/SiteB/assets",  
		  sourceDir = "SiteB",  
		  ),  
		).also(::register)

Note: if you want to test your extension you must comment other extension in build.gradle.kts

Running

You can run it directly in android studio, after selecting it in Run/Debug Configuration

Building

APKs can be created in Android Studio via Build > Build Bundle(s) / APK(s) > Build APK(s) or Build > Generate Signed Bundle / APK.

Submitting the changes

When you feel confident about your changes, submit a new Pull Request so your code can be reviewed and merged if it's approved. We encourage following a GitHub Standard Fork & Pull Request Workflow and following the good practices of the workflow, such as not commiting directly to master: always create a new branch for your changes.

If you are more comfortable about using Git GUI-based tools, you can refer to this guide about the Git integration inside Android Studio, specifically the "How to Contribute to an to Existing Git Repository in Android Studio" section of the guide.

Please do test your changes by compiling it through Android Studio before submitting it. Also make sure to follow the PR checklist available in the PR body field when creating a new PR. As a reference, you can find it below.

Pull Request checklist

Update VersionCode value in build.gradle for individual extensions
Add the isNsfw = true flag in build.gradle when appropriate
Explicitly kept the id if a source's name or language were changed
Test the modifications by compiling and running the extension through Android Studio

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

Contributing

Table of Contents

Prerequisites

Tools

Cloning the repository

Getting help

Writing an extension

Setting up a new Gradle module

Extension file structure

build.gradle

Core dependencies

Extension API

Additional dependencies

Extension main class

Main class key variables

Extension call flow

getMangaList(sort: Listing?, page: Int)

Book Search

Filters

Book Details

Chapter

Chapter Pages

Writing an Multisrc Extension

Multisrc Extension file structure

build.gradle

Running

Building

Submitting the changes

Pull Request checklist

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing

Table of Contents

Prerequisites

Tools

Cloning the repository

Getting help

Writing an extension

Setting up a new Gradle module

Extension file structure

build.gradle

Core dependencies

Extension API

Additional dependencies

Extension main class

Main class key variables

Extension call flow

getMangaList(sort: Listing?, page: Int)

Book Search

Filters

Book Details

Chapter

Chapter Pages

Writing an Multisrc Extension

Multisrc Extension file structure

build.gradle

Running

Building

Submitting the changes

Pull Request checklist