DOCUMENTAÇÃO DO FRAMEWORK - versão 2.0

DOCUMENTAÇÃO DO FRAMEWORK - versão 2.0 Índice 1 - Objetivo 2 - Descrição do ambiente 2.1. Tecnologias utilizadas 2.2. Estrutura de pastas 2.3. Bibliotecas já incluídas 3 - Características gerais 4 - Criando uma atividade complementar 4.1. - Definição da estrutura geral 4.2. - Inserção de conteúdo 4.3. - Inserção de textos na Biblioteca 4.4. - Inserção de termos no Glossário 5 - Persistência de dados 5.1 - Configuração da tabela do banco de dados 5.2 - Funções disponíveis 1 - Objetivo O objetivo deste documento é explicar o funcionamento do framework (versão 2.0) implementado para criação de novas atividades complementares (incluindo configurações de layout e inserção de novos conteúdos). 2 - Descrição do ambiente 2.1. Tecnologias utilizadas HTML 5 CSS 3 CSS Normalize 2.1.2 Javascript JQUERY 1.8.3 jquery-ui 1.9.2 XML 1.0 PHP5 1

MySQL Server 5.5 Bootstrap 2.2.2 2.2. Estrutura de pastas No nível mais externo, o framework está, inicialmente, dividido em duas pastas: (i) complement e (ii) framework. A pasta complement possui os diretórios e arquivos necessários para criar uma nova atividade complementar. Ela pode ser renomeada para o nome da atividade complementar em questão e copiada para criar múltiplas atividades complementares. Já a pasta framework é única e deve ser mantida inalterada. Dessa forma, é possível haver dentro da mesma estrutura "complement1", "complement2" e apenas uma pasta "framework". Importante: Não aconselhamos alterações na pasta framework. Como você verá no item 4.1 deste documento, algumas customizações podem ser feitas por XML dentro da pasta complement. Quaisquer outras mudanças de layout podem ser feitas sobrescrevendo o CSS também dentro da pasta complement. A pasta complement está distribuída da seguinte maneira: 2

2.3. Bibliotecas já incluídas Algumas bibliotecas já foram incluídas no framework e suas API s estão disponíveis para uso: jquery (versão 1.8.3)» Biblioteca versátil para auxiliar a escrita de javascript. jquery UI (versão 1.9.2)» Biblioteca que dá suporte a interfaces interativas, como menus de navegação e dialogs. Bootstrap (versão 2.2.2)» Biblioteca front-end para o desenvolvimento web mais rápido e fácil. 3

3 - Características gerais O framework foi desenvolvido para facilitar a inserção de conteúdo na criação de novas atividades complementares, mantendo a estrutura de navegação pré-definida. As páginas acessáveis possuem arquivos HTML específicos para armazenar o seu conteúdo. Esses arquivos serão renderizados dinamicamente dentro da estrutura. Dessa forma, a inserção dos conteúdos é transparente para o desenvolvedor, que não precisa se preocupar com o cabeçalho (header) e o rodapé (footer) de cada página sempre que houver uma modificação. Este mecanismo previne erros e agiliza o desenvolvimento. Além disso, o usuário do framework informa, em um arquivo de configurações (config.xml), detalhes sobre o cabeçalho e as tarefas do complemento. O framework possibilita uma inserção variável de páginas para cada uma das tarefas e proporciona uma navegação através do conteúdo, desde a página inicial até a atividade conclusão (botões de avançar e retornar são inseridos automaticamente). Além disso, o percurso de navegação do aluno é armazenado e uma mensagem de alerta é exibida caso o aluno tente ir para alguma INSTRUÇÕES PARA INSTALAÇÃO DO SERVIDOR DO FRAMEWORK - versão 2.0etapa sem ter concluído a anterior. 4 - Criando uma atividade complementar 4.1. - Definição da estrutura geral A primeira alteração que deve ser feita para criar uma atividade complementar é no arquivo de configuração XML localizado na pasta complement : Exemplo: complement/config.xml 4

Dentro da tag <complement> é possível definir algumas especificidades da atividade complementar, como: (a) <header> O header estará presente em todas as páginas da atividade. Ele possui um <title> (título da atividade); um <upper-title> ( atividade complementar ); uma <logo> (o atributo url deve conter o link para o qual o usuário será direcionado ao clicar na logo e o atributo image deve conter o nome do arquivo que contém a imagem da logo da FGV); e um <background> (o atributo image deve conter o nome do arquivo que contém a imagem de fundo do header, o atributo extra deve conter atributos de css específicos para o background e o atributo color deve conter uma cor que será preenchida no header caso a imagem não se ajuste totalmente ao tamanho dele). 5

(b) <footer> O footer também estará presente em todas as páginas da atividade. Ele possui o atributo color que define a sua cor de fundo. (c) <tasks> Uma atividade complementar possui, por definição quatro tarefas. Cada tarefa pode ter uma ou mais páginas. No exemplo ilustrado na figura, as tags <task> representam as tarefas de 1 a 4, na ordem em que foram inseridas no XML. Cada <task> possui um número flexível de páginas, sendo que cada página é definida pela tag <page>. Essa tag possui um atributo name, contendo o nome que será visível ao aluno no menu da atividade; e um atributo file, contendo o nome do arquivo HTML que possui o conteúdo da respectiva página. A tag <database> é utilizada para referencia a tabela do banco de dados que será utilizada para persistência de dados da atividade complementar em questão. Seu uso está explicado no item 5.1 deste documento. Na tag <libs> devem ser declaradas bibliotecas javascript e arquivos css (<js> e <cs> respectivamente) que pertençam à lógica específica da atividade complementar implementada. Note que é possível sobrescrever o layout de qualquer componente do framework em um css próprio. Importante: o framework espera que os arquivos javascript, css e arquivos de imagens estejam dentro da pasta media, como mostrado na imagem do item 2.2 deste documento. 4.2. - Inserção de conteúdo Para inserir conteúdo às páginas basta alterar o arquivo content.html no diretório respectivo da página que deseja alterar. Exemplo: complement/info/content.html 6

Exemplo: complement/instructions/content.html 4.3. - Inserção de textos na Biblioteca O framework dá suporte à inclusão de Textos de Apoio na página Biblioteca. Essa página é renderizada automaticamente pelo framework de acordo com a definição dos textos no arquivo text.xml. Exemplo: complement/library/text.xml 7

Para cada <text>, é necessário definir <title>, <source> (definindo o nome do arquivo HTML que possui o conteúdo do texto) e, opcionalmente, <ref> (contendo a referência bibliográfica do texto). Os HTML, que possuem os conteúdos dos textos, devem ficar dentro da pasta library. O atributo id do <text> possui uma funcionalidade específica: é possível que se deseje inserir um link para um ou mais textos avulsos em alguma página de conteúdo, como dentro de uma tarefa, por exemplo. Para isso, o framework disponibiliza uma função opentext(id_do_texto) que pode ser chamada a qualquer momento em um javascript. Seguindo o exemplo da figura acima, se for feita uma chamada opentext(0), o texto Nome do texto de apoio 01 será aberto em um pop-up na página corrente. timecamp 4.4. - Inserção de termos no Glossário O framework dá suporte à inclusão de termos (e suas definições) na página Glossário. Essa página é renderizada automaticamente pelo framework de acordo com a definição dos termos no arquivo glossary.xml. Exemplo: complement/glossary/glossary.xml 8

Para incluir um termo basta definir uma tag <word> com o atributo name (obrigatório). Esse atributo será utilizado pelo framework para ordenar as palavras no glossário em ordem alfabética (portanto a palavra com name= frame ficará na letra F na página de glossário). Dentro da tag <word> deve-se incluir a tag <definition> com a definição do termo. Note que dentro da definição é possível inserir trechos de código em HTML para auxiliar na formatação do texto (rich-text). Opcionalmente, através da tag <representation>, é possível definir o modo como a palavra será exibida na página, também inserindo trechos em HTML para formatar o texto (rich-text). Essa tag é opcional e caso ela não conste dentro de <word> o framework exibirá como nome do termo o atributo name, seguindo a formatação default. Os termos não precisam ser definidos em ordem alfabética e, independente da ordem, o framework se responsibilizará por separar os termos de acordo com suas letras iniciais ao renderizar a tela de Glossário. As letras que não possuírem conteúdo serão desabilitadas. Dessa forma, o usuário identifica rapidamente quais letras deve acessar. 5 - Persistência de dados 5.1. - Configuração da tabela do banco de dados Para viabilizar a persistência de dados para múltiplas atividades complementares, cada atividade possui uma tabela própria na base de dados. Instruções de como criar uma tabela estão no documento "INSTRUÇÕES PARA INSTALAÇÃO DO SERVIDOR DO FRAMEWORK - versão 2.0". Uma vez que já exista a tabela para armazenar os dados referentes a uma atividade complementar, basta inserir o nome da tabela na tag <complement_table>, localizada dentro da tag <database> no arquivo 'config.xml', como no exemplo: Exemplo: complement/config.xml 5.2. - Funções disponíveis O framework possui funcionalidades que facilitam a persistência de dados dos 9

usuários. Estão disponíveis duas funções que encapsulam as chamadas com o servidor remoto: persistdata(field_name, fiel_value) e getdata(field_name, callback). Repare que a persistência de dados é feita a partir de uma tupla <chave, valor>. Portanto, para salvar um dado, basta chamar a persistdata com o nome do campo (field_name) e o valor (field_value), sendo que ambos devem ser obrigatoriamente strings. De forma análoga, para resgatar o dado basta chamar a getdata passando como parâmetro o nome do campo (field_name) e uma função de callback, que será a função responsável por tratar o dado recebido do banco de dados. Importante: Para que a persistência de dados funcione corretamente, é necessário definir uma váriavel global user_id (já declarada pelo framework) com o id que identifica o usuário. Essa definição deve ocorrer antes de qualquer uma das funções de persistência ser chamada. Recomendamos fortemente que essa definição seja feita no arquivo 'complement/media/js/complement_lib.js'. Basta inserir nesse arquivo uma atribuição como 'user_id= (valor do id)' para que o usuário seja identificado na base de dados. FIM DO DOCUMENTO 10