Contributing

1. 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.

2. 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 = "2",  
	  lang = lang,  
	  description = "",  
	  nsfw = false,  
	  icon = DEFAULT_ICON  // if you want to use a remote image repalce `DEFAULT_ICON` with a link
  )  
}.also(::register)

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.

Main class key variables

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.

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 = "2",  
		  lang = "en",  
		  description = "",  
		  nsfw = false,  
		  icon = DEFAULT_ICON,  
		  assetsDir = "multisrc/<mysourcename>/SiteA/assets",  
		  sourceDir = "SiteA",  
		  ),  
		  Extension(  
		        name = "SiteB",  
		  versionCode = 1,  
		  libVersion = "2",  
		  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