|
| 1 | +# Font families in the EPUB navigator |
| 2 | + |
| 3 | +Readium allows users to customize the font family used to render a reflowable EPUB, by changing the [EPUB navigator preferences](Navigator%20Preferences.md). |
| 4 | + |
| 5 | +:warning: You cannot change the default font family of a fixed-layout EPUB (with zoomable pages), as it is similar to a PDF or a comic book. |
| 6 | + |
| 7 | +## Available font families |
| 8 | + |
| 9 | +iOS ships with a large collection of font families that you can use directly in the EPUB preferences. [Take a look at the Apple catalog of System Fonts](https://developer.apple.com/fonts/system-fonts/). |
| 10 | + |
| 11 | +To improve readability, Readium embeds three additional font families designed for accessibility: |
| 12 | + |
| 13 | +* [OpenDyslexic](https://opendyslexic.org/) |
| 14 | +* [AccessibleDfA](https://github.com/Orange-OpenSource/font-accessible-dfa), by Orange |
| 15 | +* [iA Writer Duospace](https://github.com/iaolo/iA-Fonts/tree/master/iA%20Writer%20Duospace), by iA |
| 16 | + |
| 17 | +You can use all the iOS System Fonts out of the box with the EPUB navigator: |
| 18 | + |
| 19 | +```swift |
| 20 | +epubNavigator.submitPreferences(EPUBPreferences( |
| 21 | + fontFamily: "Palatino" |
| 22 | +)) |
| 23 | +``` |
| 24 | + |
| 25 | +Alternatively, extend `FontFamily` to benefit from the compiler type safety: |
| 26 | + |
| 27 | +```swift |
| 28 | +extension FontFamily { |
| 29 | + public static let palatino: FontFamily = "Palatino" |
| 30 | +} |
| 31 | + |
| 32 | +epubNavigator.submitPreferences(EPUBPreferences( |
| 33 | + fontFamily: .palatino |
| 34 | +)) |
| 35 | +``` |
| 36 | + |
| 37 | +For your convenience, a number of [recommended fonts](https://readium.org/readium-css/docs/CSS09-default_fonts) are pre-declared in the `FontFamily` type: Iowan Old Style, Palatino, Athelas, Georgia, Helvetica Neue, Seravek and Arial. |
| 38 | + |
| 39 | +## Setting the available font families in the user interface |
| 40 | + |
| 41 | +If you build your settings user interface with the EPUB Preferences Editor, you can customize the list of available font families using `with(supportedValues:)`. |
| 42 | + |
| 43 | +```swift |
| 44 | +epubPreferencesEditor.fontFamily.with(supportedValues: [ |
| 45 | + nil, // A `nil` value means that the original author font will be used. |
| 46 | + .palatino, |
| 47 | + .helveticaNeue, |
| 48 | + .iaWriterDuospace, |
| 49 | + .accessibleDfA, |
| 50 | + .openDyslexic |
| 51 | +]) |
| 52 | +``` |
| 53 | + |
| 54 | +## How to add custom font families? |
| 55 | + |
| 56 | +To offer more choices to your users, you must embed and declare custom font families. Use the following steps: |
| 57 | + |
| 58 | +1. Get the font files in the desired format, such as .ttf and .otf. [Google Fonts](https://fonts.google.com/) is a good source of free fonts. |
| 59 | +2. Add the files to your app target from Xcode. |
| 60 | +3. Declare new extensions for your custom font families to make them first-class citizens. This is optional but convenient. |
| 61 | + ```swift |
| 62 | + extension FontFamily { |
| 63 | + public static let literata: FontFamily = "Literata" |
| 64 | + public static let atkinsonHyperlegible: FontFamily = "Atkinson Hyperlegible" |
| 65 | + } |
| 66 | + ``` |
| 67 | +4. Configure the EPUB navigator with a declaration of the font faces for all the additional font families. |
| 68 | + ```swift |
| 69 | + let resources = Bundle.main.resourceURL! |
| 70 | + let navigator = try EPUBNavigatorViewController( |
| 71 | + publication: publication, |
| 72 | + initialLocation: locator, |
| 73 | + config: .init( |
| 74 | + fontFamilyDeclarations: [ |
| 75 | + CSSFontFamilyDeclaration( |
| 76 | + fontFamily: .literata, |
| 77 | + fontFaces: [ |
| 78 | + // Literata is a variable font family, so we can provide a font weight range. |
| 79 | + // https://fonts.google.com/knowledge/glossary/variable_fonts |
| 80 | + CSSFontFace( |
| 81 | + file: resources.appendingPathComponent("Literata-VariableFont_opsz,wght.ttf"), |
| 82 | + style: .normal, weight: .variable(200...900) |
| 83 | + ), |
| 84 | + CSSFontFace( |
| 85 | + file: resources.appendingPathComponent("Literata-Italic-VariableFont_opsz,wght.ttf"), |
| 86 | + style: .italic, weight: .variable(200...900) |
| 87 | + ) |
| 88 | + ] |
| 89 | + ).eraseToAnyHTMLFontFamilyDeclaration(), |
| 90 | + |
| 91 | + CSSFontFamilyDeclaration( |
| 92 | + fontFamily: .atkinsonHyperlegible, |
| 93 | + fontFaces: [ |
| 94 | + CSSFontFace( |
| 95 | + file: resources.appendingPathComponent("Atkinson-Hyperlegible-Regular.ttf"), |
| 96 | + style: .normal, weight: .standard(.normal) |
| 97 | + ), |
| 98 | + CSSFontFace( |
| 99 | + file: resources.appendingPathComponent("Atkinson-Hyperlegible-Italic.ttf"), |
| 100 | + style: .italic, weight: .standard(.normal) |
| 101 | + ), |
| 102 | + CSSFontFace( |
| 103 | + file: resources.appendingPathComponent("Atkinson-Hyperlegible-Bold.ttf"), |
| 104 | + style: .normal, weight: .standard(.bold) |
| 105 | + ), |
| 106 | + CSSFontFace( |
| 107 | + file: resources.appendingPathComponent("Atkinson-Hyperlegible-BoldItalic.ttf"), |
| 108 | + style: .italic, weight: .standard(.bold) |
| 109 | + ), |
| 110 | + ] |
| 111 | + ).eraseToAnyHTMLFontFamilyDeclaration() |
| 112 | + ] |
| 113 | + ), |
| 114 | + httpServer: GCDHTTPServer.shared |
| 115 | + ) |
| 116 | + ``` |
| 117 | + |
| 118 | +You are now ready to use your custom font families. |
| 119 | + |
0 commit comments