integerating with compose

[Trassive]

i want to use this library but reading guides and getting nowhere ,views in compose documentation ain't helping much either. i do have ideas of views it would be great help if somebody gives a brief overview how i could better understand interop part

[mickael-menu]

There's a relatively new AndroidFragment composable that you can use to host the navigator fragments.

You need to set the supportFragmentManager.fragmentFactory of your Activity as usual, then you can use in your Content composable something like:

AndroidFragment<EpubNavigatorFragment> { fragment ->
    
}

I don't know if this was ever used in production with a Readium powered app. Please let us know how it goes for you.

[Trassive]

i'll inform after trying.
for the future it will be nice to have more sturctured and detailed guide on the readium website itself

[yuroyami]

If anyone needs an explanation on how to implement a Navigator within Jetpack Compose, bump me here I'll explain

[mickael-menu]

I would be interesting for any feedback and tips you have @yuroyami. I could convert it into a user guide. Thanks!

[yuroyami]

@mickael-menu Here's my personal Jetpack Compose approach. Hope it helps those who are stuck implementing Readium in a Jetpack Compose (or a Compose multiplatform app):

1- Make sure you have viewBinding = true in your module's build.gradle.kts. We'll use this to inflate our parent XML (that hosts the EpubNavigatorFragment):

kotlin {
      ...
      buildFeatures {
          viewBinding = true
      }
}

2- In order to make fragments compatible with Jetpack Compose, we need to make use of this library:
implementation("androidx.compose.ui:ui-viewbinding:1.7.2")
It will give us a AndroidViewBinding composable which can interop with XML viewbinding.

3- Create a small XML layout file, name it "epub_fragment_parent.xml" or something like that. It will host the actual EpubNavigatorFragment. So we inflate this XML and then inject EpubNavigatorFragment into it. It's just a FragmentContainerView.

<?xml version="1.0" encoding="utf-8"?>
<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigator"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="#000000">
</androidx.fragment.app.FragmentContainerView>

4- Now let's dive into the actual Jetpack Compose code. This is the parent composable everything will happen here):

lateinit var ebookFragmentParentBinding: EbookFragmentParentBinding <-- important
lateinit var sfm: FragmentManager <-- //VERY important, make sure to initialize this from your activity's onCreate, also, make sure your activity is a subclass of `FragmentActivity` because otherwise it won't have a FragmentManager.
lateinit var epubnav: EpubNavigatorFragment <-- //VERY important, this is the actual fragment provided by Readium
var publication: Publication? = null

@Composable
actual fun EbookViewport(book: Book) {
    val context = LocalContext.current
    var pub by remember { mutableStateOf<Publication?>(null) }

    LaunchedEffect(null) {
        viewmodel.viewModelScope.launch(Dispatchers.IO) {
            pub = getEPUB() <-- //Some kind of logic that gets an EPUB publication from a link for example
        }
    }

    if (pub == null) {
        Surface(modifier = Modifier.fillMaxSize()) {
            Box(contentAlignment = Alignment.Center) {
                CircularProgressIndicator() <-- //Just an example of how we show a loading indicator if a publication is not loaded yet
            }
        }
    }

    pub?.let {
        EbookHost(pub!!) <-- //This will be visible once a publication is ready.
    }
}

Now let's look at the EbookHost composable itself (In this case, I make it handle a case where a publication could be a PDF or a EPUB, since the fragments for each are different:

 AndroidViewBinding(
        modifier = Modifier.fillMaxSize().systemBarsPadding(),
        factory = { inflater, viewgroup, attachToParentBoolean ->
            ebookFragmentParentBinding = EbookFragmentParentBinding.inflate(inflater, viewgroup, attachToParentBoolean)
            return@factory ebookFragmentParentBinding
        }
    ) {
        publication = pub <-- //publication is a global property because it has to be used by EpubFragment as well

        /* This is a "onUpdate" lambda which runs very often (on every recomposition)
         Therefore, we need a boolean to make sure it runs only once just to insert our EpubNavigatorFragment */
        val nav = ebookFragmentParentBinding.navigator

        if (nav.getFragment<EpubFragment>() == null) { <-- //it will show a warning that it's always true, it's a false positive so IGNORE IT
            if (pub.conformsTo(Publication.Profile.PDF)) {
                sfm.beginTransaction()
                    .replace(ebookFragmentParentBinding.navigator.id, PdfFragment::class.java, Bundle(), "Pdf")
                    .commitNow()
            } else if (pub.conformsTo(Publication.Profile.EPUB)) {
                sfm.beginTransaction()
                    .replace(ebookFragmentParentBinding.navigator.id, EpubFragment::class.java, Bundle(), "Epub")
                    .commitNow()
            }
        }
    }

Last but not least, we need the actual fragment code for EpubFragment (and PdfFragment if necessary, they're very similar) because it takes care of initializing the fragment using the factory, changing how the fragment looks, managing EPUB preferences...etc. This is the code:

@OptIn(ExperimentalReadiumApi::class)
class EpubFragment : Fragment(), EpubNavigatorFragment.Listener {

    override fun onCreate(savedInstanceState: Bundle?) {
        /** The only way to create an EpubNavigatorFragment is via this factory */
        childFragmentManager.fragmentFactory = EpubNavigatorFactory(
            publication = publication!!, <-- this assumes publication is always initialized at this point, which should be no issue
            configuration = EpubNavigatorFactory.Configuration(
                defaults = EpubDefaults(scroll = true)
            )
        ).createFragmentFactory(
            initialLocator = null,
            listener = this,
            configuration = EpubNavigatorFragment.Configuration { }
        )

        super.onCreate(savedInstanceState)
    }


    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?,
    ): View {
        val binding = EbookFragmentParentBinding.inflate(inflater, container, false)

        if (savedInstanceState == null) {
            /** Adding the [EpubNavigatorFragment] to the parent host fragment */
            childFragmentManager.beginTransaction()
                .add(R.id.navigator, EpubNavigatorFragment::class.java, Bundle(), "EpubNavigator")
                .commitNow()
        }

        /** We have obtained our EPUB navigator by now */
        epubnav = childFragmentManager.findFragmentByTag("EpubNavigator") as EpubNavigatorFragment

        return binding.root
    }
}

That's it. You should be all set. You can add decorations, input listeners and anything you like, within "EpubFragment" as it's the best way to add your initialization code. But you can also do it via "LaunchedEffect()" in Jetpack Compose, I think there are multiple ways to doing this.

[qnga]

Thank you for sharing this! Do you have no issue with fragment restoration? If you start your app again after it was killed, thinking in Compose pub is null, so the progress indicator is shown, that's ok. But Android usually can't stop itself from restoring fragments that were shown before the kill. Is it not the case with AndroidViewBinding?

[yuroyami]

@qnga Good point. The code I shared provides the basic setup for integrating Readium with Compose. As for state restoration, more effort is definitely needed. I haven't explored that yet. You could try wrapping the publication in rememberSaveableState(pub) as a possible solution. Another approach might be to cache the publication URI in local storage using something like Datastore, then leverage a LaunchedEffect to reload it whenever the screen is composed. This might help with maintaining the publication across state restoration and configuration changes. Let me know if you make any progress on this.

[qnga]

I experimented a bit. Indeed, there is an issue with fragment restoration. I guess there is nothing that Compose can do about it: the framework or at least the core libraries enforce fragment restoration at startup. I could workaround that with dummy fragment factories though. Fun fact: you can return any fragment, disregarding the class parameter, it seems to work just fine, at least in my setup (no cast is ever attempted and the created fragment is quickly dismissed, peharps even never attached).

Besides, I found out that there is a new AndroidFragment composable in latest androidx-fragment-compose versions. It makes it easier to use fragments inside Compose.

[mickael-menu]

Thank you for sharing your approach @yuroyami 🙏 I did have some success using AndroidFragment as well, as mentioned here.