{"id":767,"url":"https://github.com/joeldev/JLRoutes","last_synced_at":"2025-07-30T19:32:09.203Z","repository":{"id":6880263,"uuid":"8129518","full_name":"joeldev/JLRoutes","owner":"joeldev","description":"URL routing library for iOS with a simple block-based API","archived":false,"fork":false,"pushed_at":"2023-02-21T14:37:00.000Z","size":684,"stargazers_count":5701,"open_issues_count":10,"forks_count":695,"subscribers_count":136,"default_branch":"master","last_synced_at":"2024-10-29T15:02:55.725Z","etag":null,"topics":["applink","carthage","cocoapods","deep-linking","deep-links","deeplink","ios","ios-lib","objective-c","routing","routing-engine"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joeldev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2013-02-10T23:09:45.000Z","updated_at":"2024-10-29T06:52:52.000Z","dependencies_parsed_at":"2022-08-06T20:00:53.912Z","dependency_job_id":"950f77f5-4149-4ba8-be57-550774786461","html_url":"https://github.com/joeldev/JLRoutes","commit_stats":{"total_commits":253,"total_committers":38,"mean_commits":6.657894736842105,"dds":0.5138339920948616,"last_synced_commit":"462682e6d07331950c539f54bcd2d6f6d0b449db"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeldev%2FJLRoutes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeldev%2FJLRoutes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeldev%2FJLRoutes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeldev%2FJLRoutes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joeldev","download_url":"https://codeload.github.com/joeldev/JLRoutes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226574367,"owners_count":17653621,"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":["applink","carthage","cocoapods","deep-linking","deep-links","deeplink","ios","ios-lib","objective-c","routing","routing-engine"],"created_at":"2024-01-05T20:15:30.891Z","updated_at":"2024-12-04T19:31:55.600Z","avatar_url":"https://github.com/joeldev.png","language":"Objective-C","funding_links":[],"categories":["App Routing","Objective-C","URL Scheme","Object-C 库","Foundation"],"sub_categories":["Other free courses","Getting Started"],"readme":"JLRoutes\n========\n\n[![Platforms](https://img.shields.io/cocoapods/p/JLRoutes.svg?style=flat)](http://cocoapods.org/pods/JLRoutes)\n[![CocoaPods Compatible](https://img.shields.io/cocoapods/v/JLRoutes.svg)](http://cocoapods.org/pods/JLRoutes)\n[![Carthage Compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![Build Status](https://travis-ci.org/joeldev/JLRoutes.svg?branch=master)](https://travis-ci.org/joeldev/JLRoutes)\n[![Apps](https://img.shields.io/cocoapods/at/JLRoutes.svg?maxAge=2592000)](https://cocoapods.org/pods/JLRoutes)\n\n### What is it? ###\nJLRoutes is a URL routing library with a simple block-based API. It is designed to make it very easy to handle complex URL schemes in your application with minimal code.\n\n### Installation ###\nJLRoutes is available for installation using [CocoaPods](https://cocoapods.org/pods/JLRoutes) or Carthage (add `github \"joeldev/JLRoutes\"` to your `Cartfile`).\n\n### Requirements ###\nJLRoutes 2.x require iOS 8.0+ or macOS 10.10+. If you need to support iOS 7 or macOS 10.9, please use version 1.6.4 (which is the last 1.x release).\n\n### Documentation ###\nDocumentation is available [here](http://cocoadocs.org/docsets/JLRoutes/).\n\n### Getting Started ###\n\n[Configure your URL schemes in Info.plist.](https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Inter-AppCommunication/Inter-AppCommunication.html#//apple_ref/doc/uid/TP40007072-CH6-SW2)\n\n```objc\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions\n{\n  JLRoutes *routes = [JLRoutes globalRoutes];\n\n  [routes addRoute:@\"/user/view/:userID\" handler:^BOOL(NSDictionary *parameters) {\n    NSString *userID = parameters[@\"userID\"]; // defined in the route by specifying \":userID\"\n\n    // present UI for viewing user with ID 'userID'\n\n    return YES; // return YES to say we have handled the route\n  }];\n\n  return YES;\n}\n\n- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary\u003cNSString *, id\u003e *)options\n{\n  return [JLRoutes routeURL:url];\n}\n```\n\nRoutes can also be registered with subscripting syntax:\n```objc\nJLRoutes.globalRoutes[@\"/user/view/:userID\"] = ^BOOL(NSDictionary *parameters) {\n  // ...\n};\n```\n\nAfter adding a route for `/user/view/:userID`, the following call will cause the handler block to be called with a dictionary containing `@\"userID\": @\"joeldev\"`:\n```objc\nNSURL *viewUserURL = [NSURL URLWithString:@\"myapp://user/view/joeldev\"];\n[JLRoutes routeURL:viewUserURL];\n```\n\n### The Parameters Dictionary ###\n\nThe parameters dictionary always contains at least the following three keys:\n```json\n{\n  \"JLRouteURL\":  \"(the NSURL that caused this block to be fired)\",\n  \"JLRoutePattern\": \"(the actual route pattern string)\",\n  \"JLRouteScheme\": \"(the route scheme, defaults to JLRoutesGlobalRoutesScheme)\"\n}\n```\n\nThe JLRouteScheme key refers to the scheme that the matched route lives in. [Read more about schemes.](https://github.com/joeldev/JLRoutes#scheme-namespaces)\n\nSee JLRoutes.h for the list of constants.\n\n### Handler Block Chaining ###\n\nThe handler block is expected to return a boolean for if it has handled the route or not. If the block returns `NO`, JLRoutes will behave as if that route is not a match and it will continue looking for a match. A route is considered to be a match if the pattern string matches **and** the block returns `YES`.\n\nIt is also important to note that if you pass nil for the handler block, an internal handler block will be created that simply returns `YES`.\n\n### Global Configuration ###\n\nThere are multiple global configuration options available to help customize JLRoutes behavior for a particular use-case. All options only take affect for the next operation.\n\n```objc\n/// Configures verbose logging. Defaults to NO.\n+ (void)setVerboseLoggingEnabled:(BOOL)loggingEnabled;\n\n/// Configures if '+' should be replaced with spaces in parsed values. Defaults to YES.\n+ (void)setShouldDecodePlusSymbols:(BOOL)shouldDecode;\n\n/// Configures if URL host is always considered to be a path component. Defaults to NO.\n+ (void)setAlwaysTreatsHostAsPathComponent:(BOOL)treatsHostAsPathComponent;\n\n/// Configures the default class to use when creating route definitions. Defaults to JLRRouteDefinition.\n+ (void)setDefaultRouteDefinitionClass:(Class)routeDefinitionClass;\n```\n\nThese are all configured at the `JLRoutes` class level:\n```objc\n[JLRoutes setAlwaysTreatsHostAsPathComponent:YES];\n```\n\n### More Complex Example ###\n\n```objc\n[[JLRoutes globalRoutes] addRoute:@\"/:object/:action/:primaryKey\" handler:^BOOL(NSDictionary *parameters) {\n  NSString *object = parameters[@\"object\"];\n  NSString *action = parameters[@\"action\"];\n  NSString *primaryKey = parameters[@\"primaryKey\"];\n  // stuff\n  return YES;\n}];\n```\n\nThis route would match things like `/user/view/joeldev` or `/post/edit/123`. Let's say you called `/post/edit/123` with some URL params as well:\n\n```objc\nNSURL *editPost = [NSURL URLWithString:@\"myapp://post/edit/123?debug=true\u0026foo=bar\"];\n[JLRoutes routeURL:editPost];\n```\n\nThe parameters dictionary that the handler block receives would contain the following key/value pairs:\n```json\n{\n  \"object\": \"post\",\n  \"action\": \"edit\",\n  \"primaryKey\": \"123\",\n  \"debug\": \"true\",\n  \"foo\": \"bar\",\n  \"JLRouteURL\": \"myapp://post/edit/123?debug=true\u0026foo=bar\",\n  \"JLRoutePattern\": \"/:object/:action/:primaryKey\",\n  \"JLRouteScheme\": \"JLRoutesGlobalRoutesScheme\"\n}\n```\n\n### Schemes ###\n\nJLRoutes supports setting up routes within a specific URL scheme. Routes that are set up within a scheme can only be matched by URLs that use a matching URL scheme. By default, all routes go into the global scheme.\n\n```objc\n[[JLRoutes globalRoutes] addRoute:@\"/foo\" handler:^BOOL(NSDictionary *parameters) {\n  // This block is called if the scheme is not 'thing' or 'stuff' (see below)\n  return YES;\n}];\n\n[[JLRoutes routesForScheme:@\"thing\"] addRoute:@\"/foo\" handler:^BOOL(NSDictionary *parameters) {\n  // This block is called for thing://foo\n  return YES;\n}];\n\n[[JLRoutes routesForScheme:@\"stuff\"] addRoute:@\"/foo\" handler:^BOOL(NSDictionary *parameters) {\n  // This block is called for stuff://foo\n  return YES;\n}];\n```\n\nThis example shows that you can declare the same routes in different schemes and handle them with different callbacks on a per-scheme basis.\n\nContinuing with this example, if you were to add the following route:\n\n```objc\n[[JLRoutes globalRoutes] addRoute:@\"/global\" handler:^BOOL(NSDictionary *parameters) {\n  return YES;\n}];\n```\n\nand then try to route the URL `thing://global`, it would not match because that route has not been declared within the `thing` scheme but has instead been declared within the global scheme (which we'll assume is how the developer wants it). However, you can easily change this behavior by setting the following property to `YES`:\n\n```objc\n[JLRoutes routesForScheme:@\"thing\"].shouldFallbackToGlobalRoutes = YES;\n```\n\nThis tells JLRoutes that if a URL cannot be routed within the `thing` scheme (aka, it starts with `thing:` but no appropriate route can be found), try to recover by looking for a matching route in the global routes scheme as well. After setting that property to `YES`, the URL `thing://global` would be routed to the `/global` handler block.\n\n\n### Wildcards ###\n\nJLRoutes supports setting up routes that will match an arbitrary number of path components at the end of the routed URL. An array containing the additional path components will be added to the parameters dictionary with the key `JLRouteWildcardComponentsKey`.\n\nFor example, the following route would be triggered for any URL that started with `/wildcard/`, but would be rejected by the handler if the next component wasn't `joker`.\n\n```objc\n[[JLRoutes globalRoutes] addRoute:@\"/wildcard/*\" handler:^BOOL(NSDictionary *parameters) {\n  NSArray *pathComponents = parameters[JLRouteWildcardComponentsKey];\n  if (pathComponents.count \u003e 0 \u0026\u0026 [pathComponents[0] isEqualToString:@\"joker\"]) {\n    // the route matched; do stuff\n    return YES;\n  }\n\n  // not interested unless 'joker' is in it\n  return NO;\n}];\n```\n\n### Optional Routes ###\n\nJLRoutes supports setting up routes with optional parameters. At the route registration moment, JLRoute will register multiple routes with all combinations of the route with the optional parameters and without the optional parameters. For example, for the route `/the(/foo/:a)(/bar/:b)`, it will register the following routes:\n\n- `/the/foo/:a/bar/:b`\n- `/the/foo/:a`\n- `/the/bar/:b`\n- `/the`\n\n### Querying Routes ###\n\nThere are multiple ways to query routes for programmatic uses (such as powering a debug UI). There's a method to get the full set of routes across all schemes and another to get just the specific list of routes for a given scheme. One note, you'll have to import `JLRRouteDefinition.h` as it is forward-declared.\n\n```objc\n/// All registered routes, keyed by scheme\n+ (NSDictionary \u003cNSString *, NSArray \u003cJLRRouteDefinition *\u003e *\u003e *)allRoutes;\n\n/// Return all registered routes in the receiving scheme namespace.\n- (NSArray \u003cJLRRouteDefinition *\u003e *)routes;\n```\n\n### Handler Block Helper ###\n\n`JLRRouteHandler` is a helper class for creating handler blocks intended to be passed to an addRoute: call.\n\nThis is specifically useful for cases in which you want a separate object or class to be the handler for a deeplink route. An example might be a view controller that you want to instantiate and present in response to a deeplink being opened.\n\nIn order to take advantage of this helper, your target class must conform to the `JLRRouteHandlerTarget` protocol. For example:\n\n```objc\n@interface MyTargetViewController : UIViewController \u003cJLRRouteHandlerTarget\u003e\n\n@property (nonatomic, copy) NSDictionary \u003cNSString *, id\u003e *parameters;\n\n@end\n\n\n@implementation MyTargetViewController\n\n- (instancetype)initWithRouteParameters:(NSDictionary \u003cNSString *, id\u003e *)parameters\n{\n  self = [super init];\n\n  _parameters = [parameters copy]; // hold on to do something with later on\n\n  return self;\n}\n\n- (void)viewDidLoad\n{\n  [super viewDidLoad];\n  // do something interesting with self.parameters, initialize views, etc...\n}\n\n@end\n```\n\nTo hook this up via `JLRRouteHandler`, you could do something like this:\n\n```objc\nid handlerBlock = [JLRRouteHandler handlerBlockForTargetClass:[MyTargetViewController class] completion:^BOOL (MyTargetViewController *viewController) {\n  // Push the created view controller onto the nav controller\n  [self.navigationController pushViewController:viewController animated:YES];\n  return YES;\n}];\n\n[[JLRoutes globalRoutes] addRoute:@\"/some/route\" handler:handlerBlock];\n```\n\nThere's also a `JLRRouteHandler` convenience method for easily routing to an existing instance of an object vs creating a new instance. For example:\n\n```objc\nMyTargetViewController *rootController = ...; // some object that exists and conforms to JLRRouteHandlerTarget.\nid handlerBlock = [JLRRouteHandler handlerBlockForWeakTarget:rootController];\n\n[[JLRoutes globalRoutes] addRoute:@\"/some/route\" handler:handlerBlock];\n```\n\nWhen the route is matched, it will call a method on the target object:\n\n```objc\n- (BOOL)handleRouteWithParameters:(NSDictionary\u003cNSString *, id\u003e *)parameters;\n```\n\nThese two mechanisms (weak target and class target) provide a few other ways to organize deep link handlers without writing boilerplate code for each handler or otherwise having to solve that for each app that integrates JLRoutes.\n\n### Custom Route Parsing ###\n\nIt is possible to control how routes are parsed by subclassing `JLRRouteDefinition` and using the `addRoute:` method to add instances of your custom subclass.\n\n```objc\n// Custom route defintion that always matches\n@interface AlwaysMatchRouteDefinition : JLRRouteDefinition\n@end\n\n\n@implementation AlwaysMatchRouteDefinition\n\n- (JLRRouteResponse *)routeResponseForRequest:(JLRRouteRequest *)request\n{\n  // This method is called when JLRoutes is trying to determine if we are a match for the given request object.\n\n  // Create the parameters dictionary\n  NSDictionary *variables = [self routeVariablesForRequest:request];\n  NSDictionary *matchParams = [self matchParametersForRequest:request routeVariables:variables];\n\n  // Return a valid match!\n  return [JLRRouteResponse validMatchResponseWithParameters:matchParams];\n}\n\n@end\n```\n\nThis route can now be created an added:\n```objc\nid handlerBlock = ... // assume exists\nAlwaysMatchRouteDefinition *alwaysMatch = [[AlwaysMatchRouteDefinition alloc] initWithPattern:@\"/foo\" priority:0 handlerBlock:handlerBlock];\n[[JLRoutes globalRoutes] addRoute:alwaysMatch];\n```\n\nAlternatively, if you've written a custom route definition and want JLRoutes to always use it when adding a route (using one of the `addRoute:` methods that takes in raw parameters), use `+setDefaultRouteDefinitionClass:` to configure it as the routing definition class:\n```objc\n[JLRoutes setDefaultRouteDefinitionClass:[MyCustomRouteDefinition class]];\n```\n\n### License ###\nBSD 3-clause. See the [LICENSE](LICENSE) file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeldev%2FJLRoutes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoeldev%2FJLRoutes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeldev%2FJLRoutes/lists"}