ClippingMagic.js

ClippingMagic.js permite a você integrar facilmente o editor Clipping Magic ao seu site. Você pode editar imagens individuais na página frontal, ou uma sequencia de imagens no recorte em lote.

Experimente

Após fazer upload de algumas imagens, você pode executar os exemplos abaixo diretamente no seu navegador. Basta clicar no botão "Experimente!"

Há algumas pequenas diferenças entre o editor Clipping Magic normal e o editor da API:

  • A personalização de configurações padrão não está disponível.
  • A página splash de ajuda não é exibida.

Preparação

Para usar o ClippinMagic.js, comece por inseri-lo e inicializá-lo nas páginas em que você quer permitir a edição:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js" type="text/javascript"></script>
<script src="https://clippingmagic.com/api/v1/ClippingMagic.js" type="text/javascript"></script>
<script type="text/javascript">
  var errorsArray = ClippingMagic.initialize({apiId: 123});
  if (errorsArray.length > 0) alert("Seu navegador não tem alguns dos recursos necessários: \n\n " + errorsArray.join("\n "));
</script>

ClippingMagic.js depende de jQuery. Portanto, carregue jQuery antes de carregar ClippingMagic.js.


Editar uma imagem individual

Você pode exibir o editor para uma imagem individual desta forma:

ClippingMagic.edit({
    "image" : {
      "id" : 2345,
      "secret" : "image_secret"
    },
    "locale" : "pt-BR"
  }, callback);

A função callback será chamada com result-generated ou editor-exit, mas não com os dois. Ambos indicam que o editor foi fechado.

Essa chamada somente deve ser feita após o evento document ready, pois ela faz referência ao DOM.


Editar várias imagens em sequência

Você pode exibir o editor para a edição de várias imagens desta forma:

ClippingMagic.edit({
    "images" : [ {
      "id" : 2345,
      "secret" : "image_secret"
    }, {
      "id" : 2346,
      "secret" : "image_secret2"
    } ],
    "locale" : "pt-BR"
  }, callback);

A função callback será chamada com result-generated uma vez para cada resultado produzido pelo usuário, ou seja, uma vez para cada clique em 'Concluído'. No final, haverá uma chamada editor-exit indicando que o editor foi fechado, o que pode ocorrer porque o usuário clicou em X ou porque não há mais imagens a editar. Não há callback para o caso de o usuário pular uma imagem.

Essa chamada somente deve ser feita após o evento document ready, pois ela faz referência ao DOM.


Callback function(opts)

A função edit recebe uma função callback como parâmetro. Esse callback permite responder a ações do usuário e notificar o servidor de back-end sobre o progresso da edição de imagem.

A assinatura do callback é function(opts) e exceções ou valores retornados são ignorados. O parâmetro opts é um PlainObject contendo:

event

Cadeia de caracteres que indica o que acaba de ocorrer. Veja a tabela abaixo.

image Opcional. Um objeto JSON de imagem (somente o id e a chave secreta são incluídos).
error Opcional. Um objeto JSON de erro.
EventoTem imagem?Tem erro?Significado
result-generatedSimNão O usuário clicou em 'Concluído', um resultado foi gerado e está disponível para download imediato usando a API de back-end. No modo de imagem individual, o editor foi fechado.
editor-exitNãoNão O usuário fechou o editor clicando no X vermelho no canto superior direito ou o usuário já não tem imagens para editar no modo de várias imagens. O editor foi fechado.
errorNãoSim Houve um erro. Verifique o valor do error para obter mais informações. O editor foi fechado.

Assim que o editor for fechado, você pode chamar edit() novamente. Chamadas anteriores a isso resultam em exceção.

Exemplo de invocação de callback

callback({
  "event" : "result-generated",
  "image" : {
    "id" : 2345,
    "secret" : "image_secret"
  }
}); 

Definições de função

ClippingMagic.initialize(opts) -> array_of_missing_features

A função initialize recebe um PlainObject contendo pares de chave/valor que configuram a inicialização:

apiId
Obrigatório. Seu id de API.

A função retorna um array de JavaScript com cadeias de caracteres descrevendo os recursos que o navegador atual não tem, mas que são necessários para execução do editor. Se esse array estiver vazio, você pode prosseguir e chamar a função edit.

ClippingMagic.edit(opts, callback)

A função edit recebe os seguintes parâmetros:

opts

Obrigatório. Um PlainObject contendo pares de chave/valor para configurar a inicialização:

image Opcional. Um objeto JSON de imagem (somente o id e a chave secreta são obrigatórios).
images Opcional. Um array de objetos JSON de imagem (somente o id e a chave secreta são obrigatórios).
locale Opcional. O idioma usado na exibição do editor. Se omitido, o padrão é inglês. Os valores válidos são:
CódigoIdioma de exibição
en-US English (inglês)
de-DE Deutsch (alemão)
es-ES Español (espanhol)
fr-FR Français (francês)
it-IT Italiano (italiano)
ja-JP 日本語 (japonês)
ko-KR 한국어 (coreano)
pt-BR Português (português)
zh-Hans-CN 简体中文 (chinês)
callback

Obrigatório. Veja mais detalhes na seção Callback.

Esse método não retorna um valor. Uma exceção será acionada se initialize não for chamado antes de chamar este método, se initialize retornar um array não vazio ou se a janela do editor já estiver aberta.