You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Apr 29, 2024. It is now read-only.
The samples in this directory use the Xamarin.iOS toolchain and
5
-
Xamarin Studio project files to illustrate the basics of how to
6
-
work with iOS and the SDK. Visit the [iOS Sample Gallery](https://developer.xamarin.com/samples/ios/all/)
4
+
Xamarin project files to illustrate the basics of how to
5
+
work with iOS and the SDK. Visit the [iOS Sample Gallery](https://docs.microsoft.com/samples/browse/?term=Xamarin.iOS)
7
6
to download individual samples.
8
7
9
-
License
10
-
-------
8
+
## License
11
9
12
10
See the repo's [license file](LICENSE) and any additional license information attached to each sample.
13
11
14
-
Samples Layout
15
-
==============
12
+
## Samples Layout
16
13
17
-
Version Specific Samples
18
-
------------------------
14
+
### Version Specific Samples
19
15
20
16
Starting with iOS 8, we started adding samples that showcase specific
21
17
features introduced in a release into a directory for the release. So
22
18
all the new iOS 8 feature samples live in the ios8 directory, the
23
19
iOS 9 features live in the ios9 directory and the iOS 10 feature lives
24
-
in the ios10 directory, and so on for iOS 11.
20
+
in the ios10 directory, and so on for ios11, ios12, ios13...
25
21
22
+
### watchOS
26
23
27
-
watchOS
28
-
--------
29
-
watchOS samples are in the watchOS directory, there are a couple of them:
24
+
watchOS samples are in the watchOS directory, including:
30
25
31
-
*[WatchKit/WatchKitCatalog](https://github.com/xamarin/ios-samples/tree/master/WatchKit/WatchKitCatalog): contains a sample that shows all the UI elements available in WatchKit.
32
-
*[WatchKit/GpsWatch](https://github.com/xamarin/ios-samples/tree/master/WatchKit/GpsWatch): a GPS app for the Apple Watch.
33
-
*[WatchKit/WatchTables](https://github.com/xamarin/ios-samples/tree/master/WatchKit/WatchTables): the sample app used in our tutorials to show how to build WatchKit apps.
26
+
-[watchOS/WatchKitCatalog](https://github.com/xamarin/ios-samples/tree/master/watchOS/WatchKitCatalog): contains a sample that shows all the UI elements available in WatchKit.
27
+
-[watchOS/ActivityRings](https://github.com/xamarin/ios-samples/tree/master/watchOS/ActivityRings): Health Kit integration for Apple Watch.
28
+
-[watchOS/WatchTables](https://github.com/xamarin/ios-samples/tree/master/watchOS/WatchTables): the sample app used in our tutorials to show how to build WatchKit apps.
> NOTE: The [WatchKit samples](https://github.com/xamarin/ios-samples/tree/master/WatchKit) are deprecated, please refer to these samples in the **watchOS** directory.
32
+
33
+
### tvOS
37
34
38
35
tvOS samples are in the tvos directory, including the [tvOS UI Catalog](https://github.com/xamarin/ios-samples/tree/master/tvos/UICatalog).
39
36
40
-
Contributing
41
-
------------
37
+
## Contributing
42
38
43
39
Before adding a sample to the repository, please run either install-hook.bat
44
40
or install-hook.sh depending on whether you're on Windows or a Posix system.
45
41
This will install a Git hook that runs the Xamarin code sample validator before
46
42
a commit, to ensure that all samples are good to go.
47
-
48
-
49
-
Samples Submission Guidelines
50
-
=============================
51
43
52
-
## Galleries
44
+
## Samples Submission Guidelines
45
+
46
+
### Galleries
53
47
54
48
We love samples! Application samples show off our platform and provide a great way for people to learn our stuff. And we even promote them as a first-class feature of the docs site. You can find the sample galleries here:
The [mobile-samples](https://github.com/xamarin/mobile-samples) repository is for samples that are cross-platform.
81
75
The [mac-ios-samples](https://github.com/xamarin/mac-ios-samples) repository is for samples that are Mac/iOS only.
@@ -86,66 +80,58 @@ We welcome sample submissions, please start by creating an issue with your propo
86
80
87
81
Because the sample galleries are powered by the github sample repos, each sample needs to have the following things:
88
82
89
-
***Screenshots** - a folder called Screenshots that has at least one screen shot of the sample (preferably a screen shot for every page or every major functionality piece, people really key off these things). for the xplat samples, the folder should be split into platform folders, e.g. iOS, Android, Windows. see[https://github.com/xamarin/mobile-samples/tree/master/Tasky/Screenshots](https://github.com/xamarin/mobile-samples/tree/master/Tasky/Screenshots) for an example of this.
83
+
-**Screenshots** - a folder called Screenshots that has at least one screen shot of the sample on each platform (preferably a screen shot for every page or every major piece of functionality). For an example of this, see [ios11/MapKitSample](https://github.com/xamarin/ios-samples/tree/master/ios11/MapKitSample/Screenshots).
84
+
85
+
-**Readme** - a `README.md` file that explains the sample, and contains metadata to help customers find it. For an example of this, see [ios11/MapKitSample](https://github.com/xamarin/ios-samples/tree/master/ios11/MapKitSample/README.md). The README file should begin with a YAML header (delimited by `---`) with the following keys/values:
90
86
91
-
***Readme** - a[ README.md](http://readme.md/) file that has the name of the sample, a description, and author attribution. sample here:[https://github.com/xamarin/mobile-samples/blob/master/Tasky/README.md](https://github.com/xamarin/mobile-samples/blob/master/Tasky/README.md)
87
+
-**name** - must begin with `Xamarin.iOS -`
92
88
93
-
***Metadata** - Finally, it needs a Metadata.xml file ([https://github.com/xamarin/mobile-samples/blob/master/Tasky/Metadata.xml](https://github.com/xamarin/mobile-samples/blob/master/Tasky/Metadata.xml)) that has some information:
89
+
-**description** - brief description of the sample (< 150 chars) that appears in the sample code browser search
94
90
95
-
***ID** - A GUID for the sample. You can generate this in MD under Tools menu : Insert GUID. we need this to key between articles and their associated samples
91
+
-**page_type** - must be the string `sample`.
96
92
97
-
***IsFullApplication** - Boolean flag (true or false): whether or not this is a full application such as the MWC App, Tasky, etc., or it's just a feature sample, such as, how to use 'x' feature. the basic test here is, if you would submit this to the app store because it's useful, then it's a full app, otherwise it's just a feature sample.
93
+
-**languages** - coding language/s used in the sample, such as: `csharp`, `fsharp`, `vb`, `objc`
98
94
99
-
***Brief** - Short description or what your sample does. This allows us to display a nice and clean vignette on the sample page.
95
+
-**products**: should be `xamarin` for every sample in this repo
100
96
101
-
***Level** - Beginner, Intermediate, or Advanced: this is the intended audience level for the sample. only the getting started samples are Beginner, as they are intended for people who are _just_ starting with the platform. most samples are Intermediate, and a few, that dive deep into difficult APIs, should be Advanced.
97
+
-**urlFragment**: although this can be auto-generated, please supply an all-lowercase value that represents the sample's path in this repo, except directory separators are replaced with dashes (`-`) and no other punctuation.
102
98
103
-
***Minimum License Requirement** - Starter, Indie, Business, or Enterprise: denotes the license that a user has to have in order to build/run the sample.
99
+
Here is a working example from [_ios11/MapKitSample_ README raw view](https://raw.githubusercontent.com/xamarin/ios-samples/master/ios11/MapKitSample/README.md).
104
100
105
-
***Tags**: a list of relevant tags for the app. These are:
description: "Demo of new iOS 11 features in MapKit, grouping and splitting markers based on zoom-level. Tandm is a fictional bike sharing... (iOS11)"
105
+
page_type: sample
106
+
languages:
107
+
- csharp
108
+
products:
109
+
- xamarin
110
+
urlFragment: ios11-mapkitsample
111
+
---
112
+
# Heading 1
129
113
130
-
* **SupportedPlatforms**: this is only for cross plat samples. It's a comma-separated list, and the valid values are iOS, Android, and Windows.
114
+
rest of README goes here, including screenshot images and requirements/instructions to get it running
115
+
```
131
116
132
-
* **Gallery**: This tag must contain a value of true if you want the sample to show up in the samples gallery on the developer portal.
117
+
> NOTE: This must be valid YAML, so some characters in the name or description will require the entire string to be surrounded by " or ' quotes.
133
118
134
-
***Buildable Sln and CSProj file** - the project _must_ build and have the appropriate project scaffolding (solution + proj).
119
+
- **Buildable solution and .csproj file** - the project _must_ build and have the appropriate project scaffolding (solution + .csproj files).
135
120
136
-
A good example of this stuff is here in the drawing sample:[https://github.com/xamarin/monotouch-samples/tree/master/Drawing](https://github.com/xamarin/monotouch-samples/tree/master/Drawing)
121
+
This approach ensures that all samples integrate with the Microsoft [sample code browser](https://docs.microsoft.com/samples/browse/?term=Xamarin.iOS).
122
+
123
+
A good example of this stuff is here in the iOS 11 maps sample: [https://github.com/xamarin/ios-samples/tree/master/ios11/MapKitSample](https://github.com/xamarin/ios-samples/tree/master/ios11/MapKitSample)
137
124
138
125
For a cross-platform sample, please see: https://github.com/xamarin/mobile-samples/tree/master/Tasky
139
126
140
127
## GitHub Integration
141
128
142
129
We integrate tightly with Git to make sure we always provide working samples to our customers. This is achieved through a pre-commit hook that runs before your commit goes through, as well as a post-receive hook on GitHub's end that notifies our samples gallery server when changes go through.
143
130
144
-
To you, as a sample committer, this means that before you push to the repos, you should run the "install-hook.bat" or "install-hook.sh" (depending on whether you're on Windows or OS X/Linux, respectively). These will install the Git pre-commit hook. Now, whenever you try to make a Git commit, all samples in the repo will be validated. If any sample fails to validate, the commit is aborted; otherwise, your commit goes through and you can go ahead and push.
131
+
To you, as a sample committer, this means that before you push to the repos, you should run the "install-hook.bat" or "install-hook.sh" (depending on whether you're on Windows or macOS/Linux, respectively). These will install the Git pre-commit hook. Now, whenever you try to make a Git commit, all samples in the repo will be validated. If any sample fails to validate, the commit is aborted; otherwise, your commit goes through and you can go ahead and push.
145
132
146
133
This strict approach is put in place to ensure that the samples we present to our customers are always in a good state, and to ensure that all samples integrate correctly with the sample gallery (README.md, Metadata.xml, etc). Note that the master branch of each sample repo is what we present to our customers for our stable releases, so they must *always* Just Work.
147
134
148
-
Should you wish to invoke validation of samples manually, simply run "validate.windows" or "validate.posix" (again, Windows vs OS X/Linux, respectively). These must be run from a Bash shell (i.e. a terminal on OS X/Linux or the Git Bash terminal on Windows).
135
+
Should you wish to invoke validation of samples manually, simply run "validate.windows" or "validate.posix" (again, Windows vs macOS/Linux, respectively). These must be run from a Bash shell (i.e. a terminal on macOS/Linux or the Git Bash terminal on Windows).
149
136
150
137
If you have any questions, don't hesitate to ask on [Xamarin Forums](https://forums.xamarin.com/categories/ios)!
0 commit comments