Mailing-List: contact callback-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: callback-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of fil@adobe.com designates
 64.18.1.191 as permitted sender)
From: Filip Maj <fil@adobe.com>
To: "callback-dev@incubator.apache.org" <callback-dev@incubator.apache.org>
Date: Mon, 25 Jun 2012 11:28:39 -0700
Subject: Re: Plugin Format and Spec
Thread-Topic: Plugin Format and Spec
Thread-Index: Ac1TACQVo02EP1qmRWyjPKtaTH4RLw==
Message-ID: <CC0DFB39.8EE7%fil@adobe.com>
In-Reply-To: 
 <CADVgkyOwhdrZa1eGRHqoxGOCQYFKM9uMCi+LGuPeb-Tux0BmnA@mail.gmail.com>
Accept-Language: en-US
Content-Language: en-US
user-agent: Microsoft-MacOutlook/14.2.2.120421
acceptlanguage: en-US
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0

Looks great. I'll add some detail to the list you have here. I'd recommend
tweaking the order a little bit; introducing the JS before the native APIs.

# Plugin Author Guide

- plugin package format -> points to Andrew's plugin spec
- js api
--- basically documenting exec(). Service, action, callbacks, arguments.
What about how arguments are translated from JS types (string, number,
objects, etc) to native types for each platform?

- native api
--- ios
--- android
--- blackberry
--- windowsphone
--- bada


On 6/25/12 11:16 AM, "Brian LeRoux" <b@brian.io> wrote:

>Biggest question is how to document. My thinking is that we want to
>specify the PluginPackage so that PluginInstall works. So the docs
>would read like this:
>
># Plugin Author Guide
>
>- plugin package format
>- native api
>--- ios
>--- android
>--- blackberry
>--- windowsphone
>--- bada
>- js api
>
>Thoughts? (If this looks good I will update the issue.)
>
>
>
>On Mon, Jun 25, 2012 at 10:50 AM, Filip Maj <fil@adobe.com> wrote:
>> Hah Michael and I were just talking about that..
>>
>> I will send a pull request to Andrew's draft spec
>>
>> On 6/25/12 10:46 AM, "Brian LeRoux" <b@brian.io> wrote:
>>
>>>npm does this w/ an 'engines' attribute on package.json
>>>
>>>On Mon, Jun 25, 2012 at 10:26 AM, Filip Maj <fil@adobe.com> wrote:
>>>> One more thing that came to mind is how to support different versions
>>>>of Cordova? Any ideas?
>>>>
>>>> From: Andrew Lunny <alunny@gmail.com<mailto:alunny@gmail.com>>
>>>> Reply-To: "alunny@gmail.com<mailto:alunny@gmail.com>"
>>>><alunny@gmail.com<mailto:alunny@gmail.com>>
>>>> To: Default User Nam <fil@adobe.com<mailto:fil@adobe.com>>
>>>> Cc:
>>>>"callback-dev@incubator.apache.org<mailto:callback-dev@incubator.apache
>>>>.o
>>>>rg>"
>>>><callback-dev@incubator.apache.org<mailto:callback-dev@incubator.apache
>>>>.o
>>>>rg>>
>>>> Subject: Re: Plugin Format and Spec
>>>>
>>>>
>>>>
>>>> On 11 June 2012 13:50, Filip Maj <fil@adobe.com<mailto:fil@adobe.com>>
>>>>wrote:
>>>> Nice work Andrew! I suggest taking this and moving to a cordova wiki
>>>>page
>>>> (assuming all committers are on board to adopting this as the basis
>>>>for
>>>>a
>>>> plugin spec)
>>>>
>>>> A link on the Cordova wiki is probably the best place to start - we
>>>>can
>>>>get some more feedback from plugin authors and app developers (i.e.
>>>>keep
>>>>this as "a way to write plugins" rather than "the official way to write
>>>>plugins").
>>>>
>>>>
>>>> Is target-dir necessary for the <source-file> element? For Java files,
>>>>the
>>>> tooling could take a peak inside the .java file and extract out the
>>>> package name from the file, no? Phonegap build already does this
>>>>doesn't
>>>> it?
>>>>
>>>> PhoneGap Build did do this, but no longer supports uploading arbitrary
>>>>Java files. Only plugins with a manifest are supported.
>>>>
>>>> I'm torn - one of the goals of this format is to make it as easy as
>>>>possible to write tools that use it as possible. Right now, a tool
>>>>reads
>>>>one file (plugin.xml) and moves source files (ignoring config files for
>>>>the moment). I'd prefer it wasn't "read one file, then read each .java
>>>>file to discover where to move it".
>>>>
>>>> One option is to use the id attribute on the top-level plugin element
>>>>to resolve the path, but that doesn't handle the case where different
>>>>Java files will have different paths. I wonder if there are more
>>>>complex
>>>>plugins around we can try to convert to see where the pain points are.
>>>>
>>>>
>>>> Adding the ability to modify existing parts of a native platform's
>>>>config
>>>> document to the <config-file> portion might be needed.. Although Ive
>>>>yet
>>>> to dig up a use case. Will dig around more.
>>>>
>>>> Agreed - also things like target OS/SDK versions may be required by
>>>>certain plugins (i.e. this plugin uses an iOS 6 API, so we need to
>>>>update your project to iOS 6). Probably the best approach there is to
>>>>warn/prompt the user before proceeding.
>>>>
>>>> +1 agree that <resource-file> and <header-file> is redundant. Tooling
>>>> should be able to distinguish this so merging with <source-file>
>>>>makes a
>>>> lot of sense.
>>>>
>>>> Looking good!
>>>>
>>>> On 6/8/12 6:40 PM, "Andrew Lunny"
>>>><alunny@gmail.com<mailto:alunny@gmail.com>> wrote:
>>>>
>>>>>Hi all,
>>>>>
>>>>>I've posted to this list before about pluginstall[1], the tool I've
>>>>>developed as part of working on PhoneGap Build and requiring
>>>>>programmatic
>>>>>installation of Cordova plugins.
>>>>>
>>>>>I've now written up a spec for the format that pluginstall uses - I
>>>>>think
>>>>>it's generally useful for Cordova plugin installation and
>>>>>manipulation.
>>>>>The
>>>>>spec is available on GitHub:
>>>>>https://github.com/alunny/cordova-plugin-spec
>>>>>
>>>>>Issues and/or pull requests and/or forks welcome.
>>>>>
>>>>>Cheers,
>>>>>Andrew
>>>>>
>>>>>[1] https://github.com/alunny/pluginstall
>>>>
>>>>
>>