Uma vez que o Cordova tenha sido instalado no computador via NPM, o primeiro passo para criar um novo projeto é executar no terminal/prompt de comandos o comando cordova create, cujos detalhes da sintaxe e funcionamento você verá neste documento.
cordova create
O comando cordova create tem por objetivo criar um novo projeto Cordova. Quando executado ele gera a estrutura de pastas e arquivos necessária para iniciar uma nova aplicação.
A sintaxe desse comando é a seguinte:
cordova create <diretório> [id] [nome] [configurações] [opções]Como podemos ver, esse comando espera os seguintes parâmetros:
- diretório: Parâmetro obrigatório que indica o diretório em que o projeto será criado. Caso o diretório ainda
não exista, ele será criado. Caso o diretório exista e esteja vazio, ele será usado normalmente e dentro dele
serão adicionadas outras pastas e arquivos. Já se o diretório existir e não estiver vazio o Cordova retornará
o seguinte erro e o projeto não será criado:
Error: Path already exists and is not empty: <diretório>
- id: Identificador da aplicação no formato reverse-domain. Esse identificador será salvo no arquivo config.xml,
no elemento <widget>, e caso não seja informado assumirá o valor padrão io.cordova.hellocordova.
Apesar de ser possível alterar esse valor posteriormente é aconselhado informá-lo já ao executar o comando create,
pois ele será usado para gerar os pacotes da linguagem Java para Android, por exemplo.
Nota: Formato reverse-domain
A notação reverse-domain, também chamada de reverse-DNS, consiste em nomear os componentes do sistema na forma de domínios web invertidos, normalmente contendo o nome da empresa/desenvolvedor e do projeto. Por exemplo, a empresa DevMedia, que possui o domínio devmedia.com.br, poderia usar o seguinte nome ao criar um projeto chamado MeuAplicativo: br.com.devmedia.MeuAplicativo. Essa notação é muito utilizada em projetos Java, mas também é adotada em outras linguagens. - nome: Esse é o título da aplicação e também fica salvo no arquivo config.xml. Caso esse parâmetro não seja informado, ele assumirá o valor padrão HelloCordova. No entanto, é aconselhado informar o nome do projeto no momento da sua criação.
- opções: Nesta última parte do comando podemos passar ainda o argumento nomeado --template,
cujos detalhes são apresentados abaixo:
--template Usado para criar o projeto baseado em um template customizado e que esteja localizado em uma pasta do computador, no NPM ou no GitHub.
Exemplos:
- --template=projetos/templates/meu-template (diretório local)
- --template=template-no-npm (pacote do NPM)
- --template=https://github.com/usuario/template-cordova (URL do GitHub)
Nota: para utilizar templates do NPM ou GitHub é necessário que o computador esteja conectado à internet.Nota: o valor desses parâmetros pode ser atribuído com o sinal de igualdade, como foi demonstrado acima, ou apenas separando-o por espaço do nome do parâmetro, da seguinte forma: --template meu-template.
Estrutura do projeto
Quando executamos o comando cordova create sem informar um template específico é criada uma estrutura padrão de pastas e arquivos, como mostra a Figura 1.
Temos então as seguintes pastas e arquivos:
- hooks: Hooks são scripts que podem ser usados para customizar os comandos do Cordova. Por exemplo, podemos efetuar alguma ação após executar o comando run, como criar ou modificar um arquivo. Os hooks são escritos em JavaScript e devem ser adicionados nessa pasta;
- platforms: Para desenvolver a aplicação nós devemos trabalhar nos arquivos da pasta www. Porém, quando a aplicação é compilada os arquivos são copiados para a pasta de cada plataforma (iOS, Android, Browser, etc), que fica dentro da pasta platforms. Além disso são gerados também os arquivos específicos de cada plataforma (projeto do XCode para iOS e estrutura de arquivos para o Android Studio, por exemplo);
- plugins: Algumas funcionalidades comuns na criação de aplicações, como a exibição de mensagens para o usuário, estão disponíveis na forma de plugins. Nessa pasta são adicionados os plugins do Cordova instalados no projeto;
- res: Nessa pasta ficam recursos de imagem, vídeo, ícones, etc. Esses arquivos são divididos de acordo com a plataforma, o que nos permite customizar a aparência da aplicação nas diferentes plataformas;
- www: Essa é a pasta em que ficam contidos os arquivos HTML, CSS e JavaScript nos quais trabalharemos. Os arquivos dessa pasta são também copiados para a pasta de cada plataforma quando compilamos a aplicação;
- .npmignore: Esse é um arquivo do NPM (Node Package Manager) e nele são listados quais arquivos deve ser ignorados quando gerarmos um pacote do NPM a partir da nossa aplicação. Esse pacote é gerado quando temos a intenção de distribuir essa aplicação no repositório do NPM (por exemplo, quando criamos um template para o Cordova e desejamos distribuí-lo);
- config.xml: Arquivo de configuração principal do projeto Cordova. Nele estão registradas informações sobre o projeto, plugins e plataformas instaladas,etc;
- package.json: Esse também é um arquivo próprio do NPM e também possui informações sobre o projeto. Essas porém são usadas na instalação de novos pacotes via NPM, bem como se desejarmos publicar a aplicação como um pacote no repositório do NPM.
Exemplos práticos
A seguir temos alguns exemplos práticos de uso do comando cordova create:
cordova create MeuApp Cria um projeto no diretório MeuApp com o nome HelloCordova e o id io.cordova.hellocordova.
cordova create MeuApp br.com.devmedia.MeuApp “Meu Aplicativo”Cria um projeto no diretório MeuApp com o nome “Meu Aplicativo” e o id br.com.devmedia.MeuApp.
cordova create MeuApp br.com.devmedia.MeuApp “Meu App” --template=cordova-phaser-ts-jedCria um projeto com as mesmas informações do comando anterior, porém dessa vez se baseando no template cordova-phaser-ts-jed que encontra-se hospedado no repositório do NPM.
