{"id":24441655,"url":"https://github.com/benrobinson16/settingsbundlebuilder","last_synced_at":"2025-04-12T20:13:14.309Z","repository":{"id":63905325,"uuid":"368930013","full_name":"benrobinson16/SettingsBundleBuilder","owner":"benrobinson16","description":"An easy way to build iOS settings bundles with a SwiftUI style syntax.","archived":false,"fork":false,"pushed_at":"2024-07-01T10:05:21.000Z","size":74,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T20:13:08.996Z","etag":null,"topics":["settings","spm","swift","swiftpackage","swiftui"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benrobinson16.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-19T16:14:38.000Z","updated_at":"2025-01-22T06:49:27.000Z","dependencies_parsed_at":"2022-11-28T19:16:13.393Z","dependency_job_id":null,"html_url":"https://github.com/benrobinson16/SettingsBundleBuilder","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benrobinson16%2FSettingsBundleBuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benrobinson16%2FSettingsBundleBuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benrobinson16%2FSettingsBundleBuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benrobinson16%2FSettingsBundleBuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benrobinson16","download_url":"https://codeload.github.com/benrobinson16/SettingsBundleBuilder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625517,"owners_count":21135514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["settings","spm","swift","swiftpackage","swiftui"],"created_at":"2025-01-20T21:18:31.941Z","updated_at":"2025-04-12T20:13:14.289Z","avatar_url":"https://github.com/benrobinson16.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SettingsBundleBuilder\n\n`SettingsBundleBuilder` provides an easy way to produce settings bundles for iOS apps with a SwiftUI-like syntax.\n\n## Motivation\n\nWorking with property list files is a nuisance - you might not know what key/values are required for each settings item. With a SwiftUI style syntax, there is the benefit of type-checking and autocomplete. You can then be told exactly where the errors are in your `plist` without running the app and inspecting it.\n\nAdditionally, property lists can become difficult to work with for large setting screens. Again, a SwiftUI style syntax drastically improves this because it is easier to see the hierachal view structure.\n\n## Quick Start\n\n1. Add a new Swift Package locally to your existing project.\n\n2. Mark the Swift Package as executable by changing the `Package.swift` file to list the following instead of a library:\n\n```swift\nproducts: [\n    .executable(name: \"PackageName\", targets: [\"PackageName\"])\n]\n```\n\n3. Add `SettingsBundleBuilder` as a dependency, by adding:\n\n```swift\n.package(\n    name: \"SettingsBundleBuilder\", \n    url: \"https://github.com/benrobinson16/SettingsBundleBuilder.git\", \n    from: \"1.0.0\"\n)\n```\n\n\u003e Don't forget to add `\"SettingsBundleBuilder\"` as a dependency to the main target in the package as well.\n\n3. In `main.swift`, create your settings bundle using the `makeSettingsBundle` method. A quick example:\n\n```swift\nimport SettingsBundleBuilder\n\nmakeSettingsBundle {\n    Group(\"Main settings:\") {\n        TextField(\"Name\", key: \"username\")\n        Toggle(\"Personalized features\", key: \"personalization\", defaultValue: false)\n    }\n}\n```\n\n4. Run the Swift Package (`⌘ + R`) which will generate the settings bundle and open it in a Finder window. Drag this into your main project and you're good to go!\n\n## Example Usage\n\nBelow is an example of a complex settings bundle using every `SettingsBundleItem` in the package:\n\n```swift\nimport SettingsBundleBuilder\n\nmakeSettingsBundle {\n    Group(\"Main settings:\") {\n        TextField(\"Name\", key: \"username\")\n        MultiValue(\n            \"Background music\",\n            key: \"background_music\",\n            defaultValue: \"ocean\",\n            possibleValues: [\"ocean\", \"forest\", \"city\", \"cafe\", \"river\"],\n            readableVersions: [\"Ocean\", \"Forest\", \"Bustling city\", \"Quiet cafe\", \"Gentle stream\"]\n        )\n    }\n    \n    RadioGroup(\n        \"Color scheme:\",\n        key: \"color_scheme\",\n        defaultValue: \"blue\",\n        possibleValues: [\"blue\", \"red\", \"green\"],\n        readableVersions: [\"Blue\", \"Red\", \"Green\"]\n    )\n    \n    Group(\"Info\") {\n        Text(\"App name\", constantValue: \"My app\")\n        Text(\"App version\", key: \"version\", defaultValue: \"1.0.0\")\n        Page(\"Advanced\") {\n            Toggle(\"Experimental features\", key: \"experimental_features\", defaultValue: false)\n            Slider(key: \"opacity\", defaultValue: 50.0, min: 0.0, max: 100.0)\n        }\n        Page(\"Secrets\", filename: \"Secrets\") {\n            Text(\"This page needs a persistent name\", constantValue: \"because we will edit it manually\")\n        }\n    }\n}\n```\n\n## SettingsBundleItem\n\nThere are many items provided in this package, each used to present a particular cell on the settings page. \n\nSome of the frequent properties used by the items are below:\n\n- `title` - the string displayed to the user describing this setting/item\n- `key` - the `UserDefaults` key to change when this setting is changed\n- `defaultValue` - the value to provide to the UI when the key cannot be found in `UserDefaults`\n\n\u003e There are many other parameters but these are fairly straightforward and documented using Xcode's documentation tool. To access documentation, use `command + click` on a method/type.\n\nThe full list of items are:\n\n- `Group`\n- `MultiValue`\n- `Page`\n- `RadioGroup`\n- `Slider`\n- `Text`\n- `TextField`\n- `Toggle`\n\n### MultiValue, RadioGroup and Text\n\nThe `MultiValue`, `RadioGroup` and `Text` items use a different strategy to display text to the user. To do so, they use these properties:\n\n- `possibleValues` - the possible string values that could be stored in `UserDefaults` for the provided key\n- `readableValues` - a mapping of the `possibleValues` to human readable versions; this array should be in the same order as the possible values\n\nFor `MultiValue` and `RadioGroup`, this is used to display the list of values a user can choose from.\n\nFor `Text`, this is used to display dynamic content based on a value in `UserDefaults`.\n\n### Groups\n\nA `Group` offers a way to organise multiple items. Optionally provide header and footer text.\n\nNote that groups cannot be nested inside one another. The `RadioGroup` item acts like a group in the UI so cannot be placed inside a `Group`.\n\n**NOTE**: If an non-group item is placed at the root level after a `Group`, it will appear in the group in the UI due to the formatting of a `.plist` settings bundle. To avoid this, embed this item in a group.\n\n### Pages\n\nA `Page` can offer nested pages of settings. Simply provide the `title` and `content`.\n_You may also optionally provide a `filename`_\n\nTo split code apart for clarity, use something similar to the following:\n\n```swift\n@SettingsBundleBuilder\nfunc mySecondPage() -\u003e [SettingsBundleItem] {\n    // second page content\n}\n\nmakeSettingsBundle {\n    Group(\"My Group\") {\n        Page(\"2nd page\", content: mySecondPage)\n    }\n}\n```\n\n## Future Improvements\n\nFuture improvements I may make to this package in the future include:\n\n- [ ] Support for localized strings\n- [ ] Support for `SupportedUserInterfaceIdioms` to change settings bundle for iOS and iPadOS\n- [ ] Ability to add a `MinimumValueImage` and `MaximumValueImage` for `Slider`\n\n## Legal\n\nPlease see LICENSE.md for license details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenrobinson16%2Fsettingsbundlebuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenrobinson16%2Fsettingsbundlebuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenrobinson16%2Fsettingsbundlebuilder/lists"}