dpogue commented on code in PR #1498: URL: https://github.com/apache/cordova-ios/pull/1498#discussion_r1799979744
########## CordovaLib/CordovaLib.docc/upgrading-8.md: ########## @@ -0,0 +1,189 @@ +# Upgrading Plugins to Cordova iOS 8.x +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +--> + +A guide for plugin authors to understand the API changes in Cordova iOS 8.x. + +## Major Breaking Changes +### Changes to the generated app project naming + +The generated app template is now consistently named `App`, including `App.xcodeproj` and `App.xcworkspace`. The Xcode build target for the app is also named `App`. If you are expecting the name of the Xcode project or target to match the name specified in config.xml, it will now fail to find the project. + +Use the cordova-ios nodeJS API to retrieve the Xcode project path and other project details: + +```js +// Old code +const projectRoot = context.opts.projectRoot; +const platformPath = path.join(projectRoot, 'platforms', 'ios'); + +const config = getConfigParser(context, path.join(projectRoot, 'config.xml')); +const projectName = config.name(); + +const pbxprojPath = path.join(platformPath, projectName + '.xcodeproj', 'project.pbxproj'); +const xcodeProject = xcode.project(pbxprojPath); +``` + +```js +// New code +const projectRoot = context.opts.projectRoot; +const platformPath = path.join(projectRoot, 'platforms', 'ios'); + +const cordova_ios = require('cordova-ios'); +const iosProject = new cordova_ios('ios', platformPath); + +const xcodeProject = xcode.project(iosProject.locations.pbxproj); +``` + +This updated pattern is backwards compatible with existing versions of Cordova iOS 5.0.0 and newer. + +### CDVAppDelegate window deprecation + +The generated app template now uses the `UIScene` API to support multiple windows, which means that it's no longer a safe assumption that an app has only a single window. + +The ``CDVAppDelegate/window`` property of ``CDVAppDelegate`` is deprecated due to moving to the `UIScene` API. This property will always have a `nil` value. + +```objc +// Old code +// Include example here of how to get the root window +``` + + +```objc +// New code +// Include example here of how to get the root window +``` + +### CDVAppDelegate viewController deprecation + +The ``CDVAppDelegate/viewController`` property of ``CDVAppDelegate`` is deprecated, and may return `nil` if a `CDVViewController` has not yet been initialized. + +Plugins should prefer accessing the view controller using their ``CDVPlugin/viewController`` property (which is now typed as ``CDVViewController``). + +### UIView scrollView property deprecation + +The `scrollView` property added as a global category extension to `UIView` is now deprecated in Objective C code and **removed entirely in Swift code**. This is to prevent conflicts with other Swift classes that extend `UIView` and have their own `scrollView` properties. + +You can still access the `scrollView` property of the web view by dynamically invoking the method: + +```objc +// Old code +UIScrollView *scroller = self.webView.scrollView; +``` + +```objc +// New code +#import <objc/message.h> + +UIScrollView *scroller; +SEL scrollViewSelector = NSSelectorFromString(@"scrollView"); + +if ([self.webView respondsToSelector:scrollViewSelector]) { + scroller = ((id (*)(id, SEL))objc_msgSend)(self.webView, scrollViewSelector); +} +``` Review Comment: TODO: Maybe add a Swift example here too? ########## CordovaLib/CordovaLib.docc/upgrading-8.md: ########## @@ -0,0 +1,189 @@ +# Upgrading Plugins to Cordova iOS 8.x +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +--> + +A guide for plugin authors to understand the API changes in Cordova iOS 8.x. + +## Major Breaking Changes +### Changes to the generated app project naming + +The generated app template is now consistently named `App`, including `App.xcodeproj` and `App.xcworkspace`. The Xcode build target for the app is also named `App`. If you are expecting the name of the Xcode project or target to match the name specified in config.xml, it will now fail to find the project. + +Use the cordova-ios nodeJS API to retrieve the Xcode project path and other project details: + +```js +// Old code +const projectRoot = context.opts.projectRoot; +const platformPath = path.join(projectRoot, 'platforms', 'ios'); + +const config = getConfigParser(context, path.join(projectRoot, 'config.xml')); +const projectName = config.name(); + +const pbxprojPath = path.join(platformPath, projectName + '.xcodeproj', 'project.pbxproj'); +const xcodeProject = xcode.project(pbxprojPath); +``` + +```js +// New code +const projectRoot = context.opts.projectRoot; +const platformPath = path.join(projectRoot, 'platforms', 'ios'); + +const cordova_ios = require('cordova-ios'); +const iosProject = new cordova_ios('ios', platformPath); + +const xcodeProject = xcode.project(iosProject.locations.pbxproj); +``` + +This updated pattern is backwards compatible with existing versions of Cordova iOS 5.0.0 and newer. + +### CDVAppDelegate window deprecation + +The generated app template now uses the `UIScene` API to support multiple windows, which means that it's no longer a safe assumption that an app has only a single window. + +The ``CDVAppDelegate/window`` property of ``CDVAppDelegate`` is deprecated due to moving to the `UIScene` API. This property will always have a `nil` value. + +```objc +// Old code +// Include example here of how to get the root window +``` + + +```objc +// New code +// Include example here of how to get the root window +``` Review Comment: TODO: Need sample code here ########## CordovaLib/CordovaLib.docc/upgrading-8.md: ########## @@ -0,0 +1,189 @@ +# Upgrading Plugins to Cordova iOS 8.x +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +--> + +A guide for plugin authors to understand the API changes in Cordova iOS 8.x. + +## Major Breaking Changes +### Changes to the generated app project naming + +The generated app template is now consistently named `App`, including `App.xcodeproj` and `App.xcworkspace`. The Xcode build target for the app is also named `App`. If you are expecting the name of the Xcode project or target to match the name specified in config.xml, it will now fail to find the project. + +Use the cordova-ios nodeJS API to retrieve the Xcode project path and other project details: + +```js +// Old code +const projectRoot = context.opts.projectRoot; +const platformPath = path.join(projectRoot, 'platforms', 'ios'); + +const config = getConfigParser(context, path.join(projectRoot, 'config.xml')); +const projectName = config.name(); + +const pbxprojPath = path.join(platformPath, projectName + '.xcodeproj', 'project.pbxproj'); +const xcodeProject = xcode.project(pbxprojPath); +``` + +```js +// New code +const projectRoot = context.opts.projectRoot; +const platformPath = path.join(projectRoot, 'platforms', 'ios'); + +const cordova_ios = require('cordova-ios'); +const iosProject = new cordova_ios('ios', platformPath); + +const xcodeProject = xcode.project(iosProject.locations.pbxproj); +``` + +This updated pattern is backwards compatible with existing versions of Cordova iOS 5.0.0 and newer. + +### CDVAppDelegate window deprecation + +The generated app template now uses the `UIScene` API to support multiple windows, which means that it's no longer a safe assumption that an app has only a single window. + +The ``CDVAppDelegate/window`` property of ``CDVAppDelegate`` is deprecated due to moving to the `UIScene` API. This property will always have a `nil` value. + +```objc +// Old code +// Include example here of how to get the root window +``` + + +```objc +// New code +// Include example here of how to get the root window +``` + +### CDVAppDelegate viewController deprecation + +The ``CDVAppDelegate/viewController`` property of ``CDVAppDelegate`` is deprecated, and may return `nil` if a `CDVViewController` has not yet been initialized. + +Plugins should prefer accessing the view controller using their ``CDVPlugin/viewController`` property (which is now typed as ``CDVViewController``). + +### UIView scrollView property deprecation + +The `scrollView` property added as a global category extension to `UIView` is now deprecated in Objective C code and **removed entirely in Swift code**. This is to prevent conflicts with other Swift classes that extend `UIView` and have their own `scrollView` properties. + +You can still access the `scrollView` property of the web view by dynamically invoking the method: + +```objc +// Old code +UIScrollView *scroller = self.webView.scrollView; +``` + +```objc +// New code +#import <objc/message.h> + +UIScrollView *scroller; +SEL scrollViewSelector = NSSelectorFromString(@"scrollView"); + +if ([self.webView respondsToSelector:scrollViewSelector]) { + scroller = ((id (*)(id, SEL))objc_msgSend)(self.webView, scrollViewSelector); +} +``` + +This updated code is compatible with existing versions of Cordova iOS. + +## Other Major Changes +### Deprecating AppDelegate category extensions + +Please extend the ``CDVAppDelegate`` base class instead: + +```objc +// Old code +#import "AppDelegate.h" + +@interface AppDelegate (myplugin) + // Added extension methods here +@end +``` + +```objc +// New code +#import <Cordova/CDVAppDelegate.h> + +@interface CDVAppDelegate (myplugin) + // Added extension methods here +@end +``` + +It was never a completely safe assumption that an app using Cordova would include a class named `AppDelegate` that was a subclass of `CDVAppDelegate` due to the ability to embed CordovaLib in an existing iOS app project as a library. If your plugin needs to add behaviour to the app delegate, it should do so to the `CDVAppDelegate` base class. + +The updated code is backwards compatible with several existing Cordova iOS versions. + +### Deprecating MainViewController category extensions + +Please extend the ``CDVViewController`` base class instead: + +```objc +// Old code +#import "MainViewController.h" + +@interface MainViewController (myplugin) + // Added extension methods here +@end +``` + +```objc +// New code +#import <Cordova/CDVViewController.h> + +@interface CDVViewController (myplugin) + // Added extension methods here +@end +``` + +It was never a completely safe assumption that an app using Cordova would include a class named `MainViewController` that was a subclass of `CDVViewController` due to the ability to embed CordovaLib in an existing iOS app project as a library. If your plugin needs to add behaviour to the Cordova view controller, it should do so to the `CDVViewController` base class. + +This updated code is backwards compatible with several existing Cordova iOS versions. + +### Deprecating CDVCommandStatus constants in Swift + +For plugins written in Swift, the old `CDVCommandStatus_*` constants are deprecated in favour of the enum based aliases: + +```swift +// Old code +self.commandDelegate.send(CDVPluginResult(status: CDVCommandStatus_OK), callbackId: command.callbackId); +``` + +```swift +// New code +self.commandDelegate.send(CDVPluginResult(status: .ok), callbackId: command.callbackId); +``` + +These aliases were introduced in and are backwards compatible with all existing versions since Cordova iOS 5.0.0. See ``CDVCommandStatus`` for a list of the enum values. + +## Public API Removals Review Comment: TODO: Reformat and clean up everything listed below here ########## CordovaLib/CordovaLib.docc/upgrading-8.md: ########## @@ -0,0 +1,189 @@ +# Upgrading Plugins to Cordova iOS 8.x +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +--> + +A guide for plugin authors to understand the API changes in Cordova iOS 8.x. + Review Comment: TODO: Add an intro paragraph explaining why some of these changes were made and emphasizing the use of deprecation warnings rather than outright breaking -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@cordova.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@cordova.apache.org For additional commands, e-mail: issues-h...@cordova.apache.org
