Autoria de Swift PlaygroundBooks — parte 4

Adicionando capítulos e páginas

Published in

phcacique

6 min readOct 11, 2020

Olá, mundo!

Este artigo é o quarto de uma série sobre autoria de PlaygroundBooks. Veja ao final desta página o índice para os demais artigos.

Você deve ter percebido que a maioria dos PlaygroundBooks oficiais da Apple possui uma boa divisão do conteúdo em capítulos e páginas. Veja na imagem abaixo o livro Aprenda a Programar 1.

Os capítulos foram organizados por tópicos específicos de lógica de programação. As páginas, por sua vez, foram organizadas de forma a apresentar o conteúdo do capítulo de maneira fluida e dinâmica, assim o aluno pode acompanhar o seu progresso ao longo do estudo.

A apresentação de sumário do Playgrounds é bem simples, veja:

Capítulos são representados pelo texto mais à esquerda (com a opção de abrir ou fechar por meio da setinha ao lado do seu nome). Páginas estão agrupadas mais à direita. A página selecionada apresenta um marcador vertical à frente do nome.

Mas como criar novos capítulos e páginas?

Criando Capítulos

Você deve ter notado que não existe uma opção para isso no app Playgrounds, pois a ideia é justamente manter o template criado pelo autor, ainda que seja um template vazio. Sendo assim, precisamos voltar à estrutura de pastas do arquivo.

Lembre-se de como podemos acessar a estrutura
1. Clique com o botão direito sobre o playground e em seguida em Show in Finder
2. Clique com o botão direito sobre o arquivo e em seguida Show Package Content

Para criar um novo capítulo, basta duplicar a pasta do primeiro capítulo e renomeá-la. Em seguida, alterar o manifesto.

Veja que na estrutura de um capítulo (pasta Chapter1.playgroundchapter), temos algumas coisas bem definidas:

O nome da pasta precisa terminar com a extensão .playgroundchapter
Somente o último capítulo pode conter template para páginas
Deve haver um arquivo Manifest.plist
Deve conter uma pasta Pages com todas as pastas relacionadas ao capítulo.

Vamos falar sobre cada detalhe desses:

Nome da pasta

O nome da pasta que tem os dados do capítulo não é o nome que aparece no PlaygroundBook. Você pode colocar nomes mais intuitivos para a programação, como Capitulo1, Capitulo2… desde que sempre termine com a extensão de capítulo.

O nome real do capítulo, que aparece no sumário, vai ser configurado mais adiante no Manifest.plist

Templates para Páginas

Alguns livros permitem que o aluno acrescente uma nova página a ele, o que pode ser observado pelo botão de + que aparece ao passar o mouse sobre o sumário:

Entretanto, só é permitido (pela documentação oficial) acrescentar páginas ao último capítulo criado. Este template é apresentado em duas partes:

Pasta Template.playgroundpage dentro da pasta Pages do capítulo
Propriedade TemplatePageFilename no arquivo Manifest.plist

Caso você duplique a pasta do primeiro capítulo, do template básico, estas configurações serão duplicadas. Esteja atento para isso. Remova as pastas e propriedades para que não haja problema ao executar o seu livro.

Somente deixe esta configuração padrão no último capítulo e apenas se a sua intenção é realmente permitir que o aluno crie uma nova página.

Lembre-se que quando o aluno cria uma nova página ela é criada na pasta Edits, ou seja, pode ser perdida ao resetar o PlaygroundBook

Manifest

Agora vamos tratar do arquivo de propriedades dentro da pasta do capítulo.

Lembre-se que ele pode ser editado em qualquer editor de texto, como mostram as imagens abaixo (mesmo arquivo aberto no XCode e no TextEdit). Não se lembra? Volte ao primeiro artigo da série por um instante.

Veja que nós temos apenas duas propriedades neste arquivo: Name e InitialUserPages.

Como é de se esperar, a propriedade Name define o nome real do capítulo. No caso padrão ele vem com My Playground. Altere para o nome desejado.

A segunda propriedade é um a lista de páginas do capítulo. Veja que temos uma tag <array> e dentro dela uma tag <string> com o nome da pasta da página padrão. Ao criar novas páginas, lembre-se de acrescentar novas tags <string> aqui com as pastas criadas.

Pages

Por fim, cada capítulo deve ter então a pasta Pages com as páginas que pertencem a ele. Falaremos desta pasta mais adiante ao acrescentarmos novas páginas.

Editando o Manifest principal

Ok, adicionamos novas pastas e configuramos os capítulos, mas eles ainda não aparecem no nosso livro. Para que possam aparecer, precisamos configurar as propriedades do manifest principal.

Navegue até a pasta Contents na raiz do diretório do PlaygroundBook. Abra o Manifest.plist. É o mesmo que usamos para adicionar uma capa no artigo anterior.

Na imagem a seguir, dei um destaque para a lista de capítulos, que vamos editar e separei cara par (chave-valor) com uma linha em branco, para te ajudar a visualizar a informação.

Nesta região selecionada, devemos adicionar as pastas para os novos capítulos. Basta duplicar a tag <string>, dentro do <array> e trocar o nome para que seja equivalente ao da pasta que você criou.

veja só:

Resumindo: dupliquei a pasta, troquei a propriedade name no manifesto dentro de cada pasta e adicionei o capítulo no manifest principal.

Adicionando novas Páginas

O processo aqui é semelhante ao que fizemos com os capítulos:

Duplicar e renomear a pasta de página
Alterar o seu nome no Manifest.plist dentro desta página
Acrescentar a nova página no Manifest.plist do capítulo.

Adicionando uma nova página no capítulo 2, temos algo assim:

Veja que renomeei as pastas de cada página, para melhor organizar o diretório.

O manifest da página 2 fica assim:

A única alteração foi a propriedade Name, que tem o nome real da página (que aparece no sumário do livro).

Já destaco duas novas propriedades no manifesto da página:

LiveViewEdgeToEdge — diz se a área de interação do playground preenche a tela toda ou não. O padrão dela é NO, indicando que ele ocupa a metade direita da tela. Caso seja YES, esta área ocupa toda a tela.
LiveViewMode — diz se a área de interação (a Live View) deve aparecer aberta logo na abertura da página ou não. Por padrão ela aparece escondida (HiddenByDefault), mas pode ser apresentada por padrão com o valor (VisibleByDefault). Falaremos especificamente deste tópico em um artigo mais adiante, no final da série.

Este é o sumário do que foi gerado: