Paginar

Web Component para transformar conteúdos HTML em uma visualização paginada, melhorando a leitura no browser, navegação, customização etc.

Exemplo real em uso (com alguma complexidade)

link

Como usar

Via CDN, basta incluir ao final do html, antes do fechamento da tag body, o script:

<script type="module" src="https://cdn.jsdelivr.net/gh/sabia-publisher/paginar/dist/index.es.js"></script>

Esse link acima sempre puxa a última versão disponível para o software, e também as melhorias que eventualmente fazemos.

Para apontar para uma versão estável, e assim evitar possíveis bugs ou desconfigurações vindas das melhorias, pode ser da seguinte maneira:

<script type="module" src="https://unpkg.com/paginar@0.3.0/dist/index.es.js"></script>

No corpo do html, no local onde deseja que seja renderizado o leitor, utilizar o Web Component conforme abaixo, e inclua o conteúdo que deseja paginar dentro de um div com propriedade slot="content":

<paginate-content id="pagination-el">
    <div slot="content">
        <p>Conteúdo HTML para paginar</p>
    </div>
</paginate-content>

Customização

Parametros de customização disponíveis

O web component disponibiliza algumas interfaces de customização por via de um objeto a ser linkado ao web component, conforme o exemplo:

<paginate-content id="pagination-el">
    <div slot="content">
        <p>Conteúdo de uma pagina.</p>
    </div>
</paginate-content>

<script>
    const settings = {
        fontSize: 19, // number
    }

    const paginationEl = document.getElementById('pagination-el')
    if (paginationEl) {
        paginationEl.setAttribute("reader-settings", JSON.stringify(settings))
    }
</script>

Nesse exemplo, configuramos o tamanho padrão de font-size da interface e texto como 19px. As demais configurações disponíveis até o momento são:

const settings = {
    // fontSize
    // tamanho da fonte
    // tipagem: número
    fontSize: 19, 

    // textFont
    // designa a fonte base a ser usada no corpo do texto
    textFont: 'Times New Roman',

    // baseFont
    // designa a fonte padrão para a interface do paginador como um todo
    baseFont: '"Inter", sans-serif',

    // homeUrl
    // URL a ser direcionado pelo botao de home ao lado do sumário.
    // se nao for adicionada a opcao aqui, o botao de home nao aparecerá
    homeUrl: 'https://sabia.pub',

    // bookTitle
    // titulo do livro, a ser mostrado no cabeçalho do paginador
    bookTitle: 'A Tale of Two Cities',

    // chapterTitle
    // titulo do capítulo, a ser mostrado no cabeçalho do paginador
    chapterTitle: 'Chapter One - The Period',

    // fontsOptions
    // customização da lista de fontes disponíveis para o usuário customizar
    // a tela de leitura. Deve ser uma lista de até 4 opções, com o nome
    // da fonte, o label a ser apresentado para o leitur, se é default ou nao
    // e um link de onde essa fonte deve ser importada, caso não seja uma 
    // fonte de sistema
    fontsOptions: [
        {
            label: 'Times New Roman',
            name: 'TimesNewRoman, Times New Roman, Times, Baskerville, Georgia,serif',
            defaultTextFont: true // fonte padrão do corpo do texto
        },
        {
            label: 'Inter',
            name: '"Inter", sans-serif',
            link: 'https://fonts.googleapis.com/css2?family=Inter:wght@300;400;700&display=swap',
            defaultBaseFont: true // fonte padrão da interface de paginação
        },
        {
            label: 'Open Dyslexic',
            name: '"Open-Dyslexic", sans-serif',
            link: 'https://fonts.cdnfonts.com/css/open-dyslexic'
        },
        {
            label: 'Atkinson Hyperlegible',
            name: 'Atkinson Hyperlegible',
            link: 'https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400;1,700&display=swap'
        }
    ],

    // cssString
    // possibilita que CSS seja enxertado no escopo do web component 
    //  para a customização da interface em si (conceito explicado abaixo, 
    // no item de "Aplicando estilos na interface do paginador")
    // no exemplo abaixo, mudamos a cor do cabeçalho para transparente
    // e o padding do cabeçalho. Existem diversas classes e ids auxiliares na
    // interface, que podem ser explorados pelo inspetor de elementos do
    // navegador.
    // no segundo estilo, escondemos o menu de "Notas de rodapé" do menu
    // de opções
    cssString: `
        header#component-header {
            background-color: transparent;
            padding: 5px;
        }

        #footnotes-button {
            display: none;
        }
    `

}

Aplicando estilo no corpo do texto

O conteúdo que vai dentro do <div slot="content"></div> pode ser customizado por CSS, seja por importação de um link p/ arquivo CSS, ou seja por uma tag <style> fora do componente de <page-content>.

No exemplo abaixo, na classe .page-break criamos uma classe-auxiliar que força uma quebra de coluna/página. E também aplicamos uma classe geral em todos os parágrafos, para controlar a indentação:

<style>
    .page-break {
        break-before: column;
    }
        
    p {
        text-indent: 4rem;
    }
</style>

<paginate-content id="pagination-el" book-title="Título do livro">
    <div slot="content">
        <p>Conteúdo de uma pagina.</p>
        <div class="page-break"></div>
        <p>Conteúdo da próxima página.</div>
    </div>
</paginate-content>

Aplicando estilos na interface do paginador

No entanto, a maneira acima demonstrada não possibilita alterar o estilo da interface em sí do paginador. Isso porque o escopo do CSS do paginador está dentro de um web component, que possui escopo isolado do restante da página, aninhados no shadow dom daquele componente.

Para alterar o estilo da interface do web component, precisamos inserir o CSS almejado no escopo do web component. Para isso, disponibilizamos uma interface via parametros da configuração do componente, conforme exemplo a seguir:

<paginate-content id="pagination-el" book-title="Título do livro">
    <div slot="content">
        <p>Conteúdo de uma pagina.</p>
    </div>
</paginate-content>

<script>
    const settings = {
        // outras opções
        cssString: `
            main#rootComponent  {
                transition: background-color 200ms linear;
            }
        `
    }
        
    const paginationEl = document.getElementById('pagination-el')
    if (paginationEl) {
        paginationEl.setAttribute("reader-settings", JSON.stringify(settings))
    }
</script>