Noções sobre o Ficheiro components.json e Formato

Formato Geral

O formato geral do ficheiro components.json é o seguinte:

• As propriedades dos componentes são especificadas em cada componente. As propriedades "components" ou "apps" de nível superior são obsoletas.

• Cada componente tem uma propriedade "type". Os componentes só podem ter determinados valores (todos os valores possíveis são listados na tabela para os componentes por omissão).

• Cada componente tem uma propriedade "id", que deve ser exclusiva. Esta propriedade é utilizada para fazer a distinção entre componentes com o mesmo "type". Anteriormente, as aplicações tinham a propriedade "appName". Embora "appName" ainda funcione se a propriedade "id" não estiver disponível, a propriedade "appName" é obsoleta.

• Cada componente tem uma propriedade "name" que é o nome para apresentação na interface do utilizador. Se não forem especificados valores de reserva, para os componentes o valor é o nome do componente por omissão correspondente e para os componentes remotos o valor é a ID.

Segue-se um exemplo de um ficheiro components.json:

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                ...
            },
            {
                ...
            },...
        ]
    },
    {
        "name": "My own category name",
        "list": [ ... ]
    }
]

A estrutura geral é uma matriz JSON de objetos de categoria. Cada objeto de categoria tem uma propriedade "name" e uma propriedade "list". A propriedade "name" pode ser uma chave que efetua correspondência com uma Cadeia de Caracteres localizada. Se estas categorias por omissão não forem suficientes, pode fornecer o seu próprio nome de categoria, que não será localizado. A tabela seguinte lista as categorias por omissão disponíveis e as chaves correspondentes.

A propriedade "list" em cada objeto de categoria contém uma matriz de objetos de componente. Cada componente ou objeto deve ter as propriedades "type" e "id". As outras propriedades são opcionais.

• A propriedade "type" deve ser igual a um dos tipos encontrados nos componentes por omissão. Se o "type" ainda não existir, o componente não será apresentado.

• A propriedade "id" deve ser exclusiva entre os componentes. Se a propriedade "id" já existir, o componente não será apresentado.

• A propriedade "name" é o nome para apresentação do componente na interface do utilizador. Substitui a propriedade "appName" anterior para as aplicações (agora componentes remotos).

• Todas as outras propriedades são tratadas de forma idêntica à das releases anteriores.

Acrescentar Novos Componentes ao components.json

Não tem permissão para modificar os componentes por omissão. Contudo, pode criar um novo componente baseado num componente por omissão existente. Por exemplo, pode criar um novo componente baseado no componente "scs-title", que define um determinado texto por omissão. Para acrescentar um novo componente, é obrigatório especificar, no mínimo, as propriedades "type" e "id".

• O "type" deve ser igual a um dos tipos encontrados nos componentes por omissão. Se o "type" ainda não existir, o componente não será apresentado.

• A propriedade "id" deve ser exclusiva entre os componentes. Se a propriedade "id" já existir, o componente não será apresentado.

Segue-se um exemplo de código para acrescentar um novo componente Title. Este componente será apresentado juntamente com o componente de título por omissão.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline"
            }
        ]
    }
]

Segue-se um exemplo de código para acrescentar um novo componente Title com um nome para apresentação e texto por omissão.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                "initialData": {
                    "userText": "This is a second title component"
                }
            }
        ]
    }
]

Note que o componente de título assume todas as propriedades do componente Title por omissão como base e aplica modificações ao nível do tema sobre o mesmo para criar o novo componente.

Compatibilidade com Versões Anteriores

Os ficheiros components.json no formato anterior ainda podem ser lidos.

• Ficheiros com as propriedades "components" ou "apps" de nível superior.

• Se o ficheiro contiver uma propriedade "apps", os componentes remotos definidos pelo utilizador nesta propriedade continuam a ser carregados.

• Se o ficheiro contiver uma propriedade "apps" de nível superior, assume-se que quaisquer componentes remotos listados abaixo têm o tipo "scs-app".

• Se a propriedade "appName" estiver presente, define "id" como o valor "appName". O nome para apresentação será igual a "name", se especificado, ou recorre ao valor "id".