Editor de texto enriquecido (WYSIWYG) no OpenProject

O OpenProject tem um editor quase WYSIWYG, desenvolvido pela CKSource CKEditor5. O formato subjacente é o CommonMark do GitHub (GFM) com HTML adicional para, por exemplo, menções e dimensionamento de imagens.

Nota

Em alguns recursos, como pacotes de trabalho ou comentários, o editor não apresenta todas as funcionalidades, como macros ou carregamentos de imagens. Na vista de ecrã dividido do pacote de trabalho (vista de detalhes), poderá ter de utilizar os três pontos verticais para aceder a funcionalidades adicionais do editor.

Tópico	Conteúdo
Formatação básica	Elementos de formatação básica no editor WYSIWYG
Tratamento de imagens	Como adicionar imagens no editor WYSIWYG.
Atalhos de teclado	Trabalhar com atalhos de teclado no editor WYSIWYG.
Macros	Macros disponíveis no editor WYSIWYG
Ligações para os recursos do OpenProject	Como estabelecer ligações a recursos como wikis, projetos e reuniões.
Incorporação de atributos do pacote de trabalho e atributos do projeto	Como incorporar atributos e textos de ajuda de atributos.

Formatação básica

O CKEditor5 integrado no OpenProject suporta estilos de texto básicos, tais como formatação a negrito e itálico, cabeçalhos, rasurado, código em linha, e aspas, bem como manipulação de imagens em linha. A colagem de conteúdos como imagens ou texto enriquecido também é suportada, enquanto o estilo não suportado será retirado pelo editor.

Quebras de linha

Em vez de criar um novo parágrafo com Enter, pode também premir “SHIFT+Enter” para criar uma quebra de linha sem criar um novo parágrafo.

Ligações

Crie hiperligações premindo a barra de ferramentas (opcionalmente com algum texto selecionado), ou premindo “CTRL+k” para abrir um popup para introduzir a ligação.

Widgets e novas linhas

O CKEditor utiliza widgets para apresentar elementos em bloco, como imagens, tabelas e outros elementos que não estão em linha. Pode selecionar a maioria dos widgets premindo-os. A única exceção é o widget de tabela, que tem um pequeno botão de seleção no canto superior esquerdo para selecionar toda a tabela.

Quando tem um widget selecionado, pode removê-lo ou cortá-lo. Pode criar uma nova linha por baixo selecionando o widget e premindo “ENTER” ou “↓ (SETA PARA BAIXO)”, ou uma nova linha por cima premindo “SHIFT+enter” ou “↑ (SETA PARA CIMA)”. Isto é especialmente necessário quando o widget é o primeiro ou o último elemento na página para inserir uma linha abaixo ou acima deste.

Blocos de código

Como o CKEditor5 atualmente não oferece suporte para blocos de código, o OpenProject pode exibir mas não editar blocos de código dentro da instância do CKEditor. Um bloco de código pode ser editado através de uma janela modal dentro de uma instância do editor “CodeMirror”. Isto tem a vantagem de fornecer destaque de sintaxe e deteção de código (para os idiomas suportados).

Tabelas

A extensão GFM das especificações CommonMark adiciona uma definição para a sintaxe de tabela, que o CKEditor do OpenProject suporta. Esta definição exige que todas as tabelas tenham uma linha de cabeçalho. Para tabelas criadas com o CKEditor sem linhas de cabeçalho, é apresentada uma tabela HTML. Isto corresponde ao comportamento de, por exemplo, GitHub.

Formatação automática

O CKEditor5 permite algumas combinações de toques de teclado de formatação automática do tipo CommonMark:

• Crie estilos em negrito ou itálico introduzindo “será negrito”, “será itálico”,
• Crie títulos com diferentes indentações com “#”, “##”, “###”, …
• Crie uma lista com marcadores iniciando a linha com “*” ou “-” e um espaço
• Crie uma lista numerada iniciando a linha com “1.” ou “1)” e um espaço

Tratamento de imagens

Nos recursos suportados do OpenProject onde os anexos são permitidos, pode adicionar imagens à página através de

• utilizar o botão da barra de ferramentas,
• colar uma imagem da sua área de transferência,
• ou arrastar e largar uma imagem no editor.

A imagem será automaticamente carregada e guardada como anexo. Pode ajustar o tamanho da imagem no editor utilizando o rato.

Atalhos de teclado

O CKEditor tem uma grande variedade de atalhos de teclado que pode utilizar. Pode encontrar uma lista de atalhos documentados aqui: https://ckeditor.com/docs/ckeditor5/latest/features/keyboard-support.html.

Para além disso, o OpenProject adiciona o seguinte atalho:

Atalho (Windows / Linux)	Atalho (Mac)	Ação
CTRL + ENTER	CMD + ENTER	Guardar alterações Para campos editáveis em linha, guarde o campo e feche-o. Para páginas com um WYSIWYG completo (reuniões, páginas wiki), submeta o formulário.

Macros

O OpenProject tem macros suportados em páginas formatadas em Textile e continua a fazê-lo com o editor WYSIWYG. Note que as macros não são expandidas durante a edição da página, em vez disso, é apresentado um marcador de posição.

Pode encontrar as macros aqui no editor de texto:

Índice

Quando aplicável, a macro de índice (TOC) produzirá uma lista de todos os títulos na página atual.

Botão do pacote de trabalho

Configure um botão ou uma ligação para direcionar o ecrã de criação de pacotes de trabalho no projeto atual. Pode pré-selecionar um tipo de pacote de trabalho que deve ser selecionado, facilitando a orientação dos utilizadores para o formulário de criação de pacotes de trabalho.

Incluir página wiki

Inclua o conteúdo de uma determinada página wiki no projeto atual ou noutro projeto visível.

Incorporar tabela de pacotes de trabalho e gráfico de Gantt

Esta é a macro mais flexível que oferece uma funcionalidade alargada relativamente à inclusão de tabelas de pacotes de trabalho dinâmicas com todo o potencial da tabela de pacotes de trabalho normal.

Ao adicionar uma tabela de pacote de trabalho incorporada através da barra de ferramentas, pode configurar a vista de tabela (como colunas, agrupamento, filtros e outras propriedades) numa janela pop-up.

A página renderizada irá então procurar os resultados da tabela de pacotes de trabalho de forma dinâmica, respeitando a visibilidade de cada utilizador.

Utilize-a para incorporar vistas noutras páginas, criar relatórios de vários resultados ou incorporar uma vista de gráfico de Gantt.

Ligações para recursos do OpenProject

Tal como acontece com a sintaxe de formatação Textile, pode ligar a outros recursos dentro do OpenProject utilizando os mesmos atalhos que anteriormente. Crie ligações para:

Destino da ligação	Exemplo de utilização
Página Wiki	“[[Página Wiki]]”
Página Wiki com nome da ligação distinto	“[[Página Wiki|O texto da ligação]]”
Página Wiki no projeto Sandbox	“[[Sandbox:Página Wiki]]”
Pacote de trabalho com ID12	#12
Pacote de trabalho com ID 12 com assunto e tipo	##12
Pacote de trabalho com ID 12 com assunto, tipo, estado e datas	###12
Versão por ID ou nome	versão#3, versão: "Versão 1.0.0"
Projeto por ID/nome	projeto#12 , projeto: "Nome do meu projeto"
Anexo por nome do ficheiro	anexo:nome do ficheiro.zip
Reunião por ID/nome	reunião#12 , reunião: "Nome da minha reunião"
Documento por ID/nome	documento#12 , documento: "Nome do meu documento"
Utilizador por ID ou início de sessão	utilizador#4 , utilizador: "johndoe"
Mensagem do fórum por ID	mensagem#1218
Revisão do repositório 43	r43
Confirmar por hash	confirmar:f30e13e4
Ficheiro de origem no repositório	fonte: "algum/ficheiro"

Para evitar o processamento destes itens, preceda-os com um caratere ! como !#12 que impedirá a ligação a um pacote de trabalho com ID 12.

Nota

Todas estas macros têm de ser escritas como uma nova palavra (ou seja, com pelo menos um espaço antes ou no início de um parágrafo/frase). As macros contidas numa palavra como qualquercoisareunião4# não serão analisadas.

Dica

Para obter mais informações sobre a utilização de macros, consulte este artigo do blogue.

Preenchimento automático para pacotes de trabalho e utilizadores

Para pacotes de trabalho e utilizadores, introduzir # ou @ abrirá um menu suspenso de preenchimento automático para pacotes de trabalho e utilizadores visíveis, respetivamente.

Incorporação de atributos de pacote de trabalho e atributos de projeto

Nota

Estas macros só serão expandidas no frontend. Para cada utilizador individual, as permissões corretas serão verificadas e a macro resultará num erro se o utilizador não estiver autorizado a visualizar o respetivo recurso.

Incorporação de um valor de pacote de trabalho por ID de pacote de trabalho

Utilize as macros workPackageValue:ID:attribute para incorporar atributos de um pacote de trabalho pela sua ID do pacote de trabalho. Consulte a tabela abaixo para conhecer os atributos disponíveis.

Exemplo:

Ligação para o assunto do pacote de trabalho com ID #1234: workPackageValue:1234:subject

Incorporação de um valor de pacote de trabalho por assunto de pacote de trabalho

Utilize as macros workPackageValue: "Project name":attribute para incorporar atributos de um pacote de trabalho pelo seu assunto. Consulte a tabela abaixo para conhecer os atributos disponíveis.

Exemplo:

Ligação ao responsável pelo pacote de trabalho com o tema “Início do projeto “: workPackageValue: "Início do projeto":responsável

Nota

A referência a um pacote de trabalho por assunto resulta na procura apenas de pacotes de trabalho com esse assunto no projeto atual (caso exista). Se precisar de fazer referência cruzada a pacotes de trabalho, utilize a sua ID para identificar o pacote de trabalho a que pretende fazer referência. Não recomendamos a utilização de assuntos como referências, uma vez que estes não são atualizados quando o assunto referenciado é alterado.

Incorporação relativa de um valor de pacote de trabalho

Utilize as macros workPackageValue:attribute para incorporar atributos do pacote de trabalho atual.

Se estiver a editar uma descrição de pacote de trabalho ou um campo personalizado de texto enriquecido pertencente a um pacote de trabalho, pode omitir a ID se quiser referenciá-lo. Tem de incluir a ID do pacote de trabalho se estiver a editar, por exemplo, uma página wiki ou a descrição de uma reunião. Consulte a tabela abaixo para conhecer os atributos disponíveis.

Exemplo:

Ligação à pessoa responsável pelo pacote de trabalho atual: workPackageValue:assignee

Incorporação de um valor de projeto por ID de projeto

Utilize as macros projectValue:ID:attribute para incorporar atributos de um projeto pela sua ID de projeto. Consulte a tabela abaixo para conhecer os atributos disponíveis.

Exemplo:

Ligação ao estado do projeto com a ID 1234: projectValue:1234:status

Incorporação relativa de um valor de projeto

Utilize as macros projectValue:attribute para incorporar atributos do projeto atual. Consulte a tabela abaixo para conhecer os atributos disponíveis.

Exemplo:

Ligação ao estado do projeto atual: projectValue:status

Incorporar textos de ajuda de atributos

Pode também incorporar valores de atributos e os seus textos de ajuda utilizando workPackageLabel ou projectLabel. Por exemplo,workPackageLabel:1234:status produziria a etiqueta traduzida para “Status” e (se existir), o texto de ajuda correspondente.

Atributos

As listas seguintes mostram os atributos suportados para pacotes de trabalho e projetos.

Nota

Se estiver a utilizar um idioma diferente do inglês, uma tradução dos comandos só pode ser utilizada no editor de texto se o idioma de todos os utilizadores de uma instância estiver definido para o mesmo idioma (por exemplo, alemão). Neste caso, apenas o atributo ao qual o comando se refere é traduzido, por exemplo (workPackageValue:1234: "atributo traduzido"). Não recomendamos a utilização de atributos traduzidos, uma vez que podem não funcionar em versões futuras devido a correções ou alterações nos textos.

Atributos disponíveis para pacotes de trabalho

A lista seguinte contém todos os nomes de atributos suportados para as macros workPackageValue e workPackageLabel, onde 1234 representa a ID do pacote de trabalho.

Atributo	Exemplo de utilização
%Concuído	workPackageValue:8415:percentageDone
Responsável	workPackageValue:1234:responsible
Encarregado	workPackageValue:1234:assignee
Autor	workPackageValue:1234:author
Categoria	workPackageValue:1234:category
Data de criação	workPackageValue:1234:createdAt
Campos personalizados	workPackageValue:1234: "Nome do campo personalizado do pacote de trabalho"
Data da última atualização	workPackageValue:1234:updatedAt
Descrição	workPackageValue:1234:description
Tempo estimado	workPackageValue:1234:estimatedTime
Data de conclusão	workPackageValue:1234:dueDate
Pacote de trabalho principal	workPackageValue:1234:parent
Prioridade	workPackageValue:1234:priority
Projeto	workPackageValue:1234:project
Horas restantes	workPackageValue:1234:remainingTime
Trabalho restante	workPackageValue:8415:remainingTime
Tempo gasto	workPackageValue:1234:spentTime
Data de início	workPackageValue:1234:startDate
Estado	workPackageValue:1234:status
Assunto / Título	workPackageValue:1234:subject
Versão	workPackageValue:1234:version
Trabalho	workPackageValue:8415:estimatedTime
Tipo de pacote de trabalho	workPackageValue:1234:type

Nota

A incorporação recursiva de texto enriquecido não é suportada. Por exemplo, não pode incorporar uma descrição de um pacote de trabalho em si mesma com workPackageValue:description.

Atributos disponíveis para projetos

A lista a seguir contém todos os nomes de atributos suportados para as macros projectValue e projectLabel. Todos os exemplos mostram referências ao projeto actual em que o documento é processado. Podem também fazer referência a outro projeto com o atributo projectValue: "Identificador do projeto":atributo.

Atributo	Exemplo de utilização
Campos personalizados	projectValue: "Nome do campo personalizado do projeto"
Projeto ativo? (booleano)	projectValue:active
Descrição	projectValue:description
Identificador do projeto	projectValue:identifier
Nome do projeto	projectValue:name
Estado	projectValue:status
Descrição do estado	projectValue:statusExplanation
Projeto principal	projectValue:parent
Projeto público? (booleano)	projectValue:public