Autoria de Swift PlaygroundBooks — parte 4

Adicionando capítulos e páginas

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.

ocê 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.

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:

  1. O nome da pasta precisa terminar com a extensão .playgroundchapter
  2. Somente o último capítulo pode conter template para páginas
  3. Deve haver um arquivo Manifest.plist
  4. 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:

  1. Pasta Template.playgroundpage dentro da pasta Pages do capítulo
  2. 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.

Manifest.plist aberto no XCode
Manifest.plist aberto no TextEdit

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:

  1. Duplicar e renomear a pasta de página
  2. Alterar o seu nome no Manifest.plist dentro desta página
  3. 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:

Finalizando

Tranquilo né? Capítulos adicionados, páginas criadas, agora só falta começar a trabalhar na customização do conteúdo!

Tchau

Índice da série

Coordinator at Apple Developer Academy | Mackenzie