Incorporando arquivos JavaScript e CSS próprios no CMS bluetronix
Neste tutorial, você incorporará um arquivo JavaScript e uma folha de estilo própria no layout de seu site. Você conhecerá a regra _own e aprenderá como a versionamento de arquivos ajuda em alterações.
Pré-requisitos e objetivo
Para este tutorial, você precisa de um acesso de desenvolvedor ao CMS bluetronix e deve conhecer a estrutura dos layouts e pastas de desenvolvedor. Você aprenderá a incluir arquivos JavaScript e CSS próprios, além dos arquivos do CMS existentes, sem modificar os arquivos de sistema originais.
Utilizaremos os arquivos mostrados nas capturas de tela BxHeadScript_own.js e BxStyle_own.css. Ambos os arquivos são explicitamente incluídos no layout, para que o CMS os considere ao carregar a página da web.
1. Abrir layout
Abra a seção Layout no CMS e selecione Layout - HTML. Em seguida, abra o layout onde você deseja incluir seus arquivos JavaScript e CSS. Neste exemplo, usaremos o layout padrão.
Na definição do layout, você já encontrará inclusões para os arquivos centrais do CMS, como BxHeadScript.js e BxStyle.css. Você pode registrar seus próprios arquivos adicionais logo ao lado.
2. Criar arquivo JavaScript próprio no gerenciador de arquivos
Abra o Gerenciador de Arquivos e navegue até a pasta do sistema bx_script marcada em vermelho. Lá, você encontrará os arquivos centrais JavaScript do CMS bluetronix e, se necessário, variantes dependentes do idioma.
Crie seu próprio arquivo BxHeadScript_own.js ou selecione-o se já existir. Você pode copiar um arquivo existente adequado como modelo.
Selecione Editar para abrir o código JavaScript do seu próprio arquivo no editor de texto.
No exemplo mostrado, o arquivo contém código JavaScript próprio para a seleção entre Modo Escuro e Modo Claro. No editor de texto, você pode gerenciar seu código JavaScript específico do projeto e, em seguida, salvar.
Não altere o arquivo original BxHeadScript.js para suas próprias extensões. Arquivos dentro das pastas de sistema bx_ podem ser sobrescritos durante as atualizações do CMS. Identifique seus próprios arquivos lá com _own.
3. Incorporar arquivo JavaScript próprio no layout
Volte para Layout - HTML. Adicione seu próprio arquivo JavaScript além do arquivo existente do CMS. Se você quiser que seu script seja carregado cedo, insira-o como na captura de tela na seção head, após o script de cabeçalho existente.
<script src="__FV_/bx_script/BxHeadScript_own_min.js__"></script>
<script src="__FV_/bx_script/BxHeadScript_own.js__"></script>
A linha adicional carrega seu próprio código JavaScript. O arquivo original BxHeadScript.js permanece inalterado. O caminho do arquivo e a grafia do seu arquivo devem corresponder ao arquivo no gerenciador de arquivos.
4. Criar arquivo CSS próprio no gerenciador de arquivos
Abra no Gerenciador de Arquivos a pasta do sistema bx_style. Aqui está, entre outros, a folha de estilo central BxStyle.css. Para personalizações próprias, utilizamos um arquivo separado chamado BxStyle_own.css.
Crie o arquivo BxStyle_own.css ou abra o arquivo próprio existente. O arquivo de sistema BxStyle.css permanecerá intacto.
Usando Editar, você pode inserir e salvar suas próprias regras CSS neste arquivo.
5. Incorporar arquivo CSS próprio no layout
Abra novamente Layout - HTML. Na seção head, adicione seu próprio arquivo CSS após a folha de estilo existente. A ordem é importante se suas regras próprias devem sobrescrever a formatação padrão.
<link rel="stylesheet" href="__FV_/bx_style/BxStyle_own_min.css__">
<link rel="stylesheet" href="__FV_/bx_style/BxStyle_own.css__">
O arquivo padrão CSS permanece, enquanto você gerencia formatações adicionais ou diferentes separadamente em BxStyle_own.css.
6. Usar JavaScript no cabeçalho ou no final da página
Arquivos JavaScript podem ser incluídos de acordo com sua função na seção head ou no final da página, antes da tag de fechamento body. O arquivo mostrado BxHeadScript_own.js é carregado no Cabeçalho. Para outros scripts, você também pode usar uma pasta de projeto própria e incluir o arquivo mais tarde no layout.
Exemplo de um arquivo adicional de uma pasta própria no final da página:
<script src="__FV_/bx_script/BxScript_own_min.js__"></script>
<script src="__FV_/script/MyScript.js__"></script>Este exemplo mostra um arquivo adicional. Se você quiser substituir um arquivo de sistema por uma versão própria, precisará ajustar conscientemente as inclusões necessárias no layout escolhido e verificar se nenhuma função do CMS necessária é eliminada.
7. Diferenciar pastas do sistema e pastas de projeto próprias
As pastas bx_ marcadas em vermelho pertencem ao CMS bluetronix. Arquivos próprios dentro dessas pastas devem ser identificados com _own para que não sejam tratados como arquivos de sistema durante as atualizações regulares do CMS.
Você pode armazenar arquivos próprios JavaScript e CSS, alternativamente, em pastas de projeto criadas por você, sem o prefixo bx_, como /script/ ou /meus_scripts/. Nesses casos, a identificação _own não é obrigatória. Você deve usar o caminho real em sua definição de layout.
A identificação _own não substitui a inclusão no layout: Um arquivo criado separadamente só é carregado quando é incluído através da linha script ou link apropriada.
8. Versionamento automático de arquivos
Nas inclusões de layout exibidas, o CMS bluetronix utiliza a marcação __FV_…__. Por meio disso, o CMS pode adicionar um parâmetro de versão com base na data de modificação. Após uma alteração, o navegador, assim, carrega o arquivo JavaScript ou CSS atual em vez de reutilizar uma versão anterior do cache.
Exemplo: Um caminho original como /script/MyScript.js pode ser complementado com um parâmetro de versão após o processamento. Você não precisa atualizar manualmente o número da versão em todos os layouts correspondentes.
9. Salvar e verificar alterações
Primeiro, salve seus próprios arquivos JavaScript e CSS e, em seguida, o layout editado. Atualize sua página da web e verifique se suas funções JavaScript estão sendo executadas e se suas regras CSS estão sendo aplicadas.
Se um arquivo não for carregado, verifique primeiro o nome do arquivo, a capitalização, o caminho da pasta e a inclusão no layout. Se vários layouts estiverem em uso, verifique também se você editou o layout atribuído à página em questão.
Resumo
Para suas próprias extensões, crie, por exemplo, BxHeadScript_own.js na pasta bx_script e BxStyle_own.css na pasta bx_style. Em seguida, inclua ambos os arquivos em Layout - HTML além dos arquivos originais do CMS. Assim, os arquivos padrão permanecem inalterados, enquanto você gerencia o código JavaScript e CSS específico do projeto separadamente.
FAQ
o que os clientes nos perguntam frequentemente
Preciso de acesso de desenvolvedor para incluir meus próprios arquivos JavaScript e CSS?
Sim. Este tutorial é destinado a desenvolvedores que têm acesso à definição de layout e às pastas do desenvolvedor do CMS bluetronix.
Onde encontro as inclusões para JavaScript e CSS?
Abra Layout e selecione Layout - HTML. Lá você pode adicionar as inclusões no layout desejado.
Onde salvo um arquivo JavaScript próprio?
No exemplo mostrado, você cria BxHeadScript_own.js na pasta bx_script e a inclui no layout juntamente com o BxHeadScript.js existente.
Onde salvo um arquivo CSS próprio?
No exemplo mostrado, o seu arquivo BxStyle_own.css está na pasta bx_style. No layout, ele será incluído após o stylesheet existente.
Por que os arquivos próprios devem conter _own no nome quando estão em pastas do sistema?
As pastas do sistema bx_ marcadas em vermelho podem ser sobrescritas durante atualizações. Com _own, você identifica seus próprios arquivos específicos do projeto.
Um arquivo _own é carregado automaticamente assim que é criado?
Não. Você deve incluir seu arquivo JavaScript ou CSS no layout desejado com uma inclusão script ou link correspondente.
Posso usar uma pasta própria em vez de uma pasta de sistema bx_?
Sim. Em uma pasta de projeto criada por conta própria sem o prefixo bx_, _own não é obrigatória. Use o caminho real do arquivo no layout.
Devo carregar meu próprio arquivo CSS antes ou depois do arquivo padrão?
No exemplo mostrado, BxStyle_own.css é incluído após BxStyle.css. Assim, as regras próprias podem sobrescrever as regras padrão carregadas anteriormente, desde que tenham a mesma especificidade.
Qual é a finalidade da marcação __FV_…__ nos caminhos dos arquivos?
O CMS bluetronix pode adicionar um parâmetro de versão ao arquivo, de modo que os navegadores carreguem o arquivo atual após uma alteração.
O que devo verificar se meu próprio arquivo não está funcionando?
Verifique o nome do arquivo, a capitalização, o caminho especificado e a inclusão e seleção do layout correto.