Welcome to the documentation for Criollo, a Swift and Objective-C web application framework for iOS, macOS, and tvOS.
Table of Contents
- Introduction
- Getting Started
- Features
- Routing
- Middleware
- Views and Templates
- Static File Support
- WebSockets
- Authentication
- Deployment
- Troubleshooting
Introduction
Criollo is a powerful web application framework designed for building efficient and scalable iOS, macOS, and tvOS applications. It allows developers to easily create and manage web services, APIs, and dynamic web pages within their native applications.
Getting Started
Getting started with Criollo is simple. Follow the steps below to quickly set up your project:
- Install Criollo using CocoaPods or Carthage.
- Create a new Swift or Objective-C project in Xcode.
- Import the Criollo framework and initialize it in your AppDelegate.
- Implement your web application logic by defining routes and handlers.
- Build and run your project. Your web application will start running on a local server.
Features
Criollo provides a range of powerful features that enable developers to build robust web applications:
- Routing: Define URL routes and map them to handlers.
- Middleware: Implement modular and reusable request processing components.
- Views and Templates: Render dynamic web pages using powerful templating engines.
- Static File Support: Serve static files such as CSS, JavaScript, and images.
- WebSockets: Build real-time communication channels using WebSockets.
- Authentication: Implement secure authentication and authorization mechanisms.
- Deployment: Deploy your Criollo application to production environments.
Routing
Criollo enables you to define URL routes and map them to specific handlers. This allows you to handle different HTTP methods and dynamically route requests to the appropriate logic based on the URL path and parameters.
To define routes, you can use the CRRoute
class:
let route = CRRoute(httpMethod: "GET", url: "/users/:userId", handler: { (request, response, context) in
// Handle the request and send the response
})
The above code snippet defines a route for handling GET requests with a URL pattern of “/users/:userId”. The colon in the URL pattern indicates a parameter, which can be accessed in the handler using the context.params
dictionary.
Middleware
Criollo supports middleware components that allow you to intercept and modify incoming requests before they reach the route handler. Middleware provides a modular and reusable way to implement common logic such as authentication, logging, and error handling.
To add middleware to your application, you can use the CRMiddleware
protocol:
class MyMiddleware: CRMiddleware {
func process(request: CRRequest, response: CRResponse, next: @escaping () -> Void) {
// Perform middleware logic
// Call next() to pass control to the next middleware or route handler
}
}
// Add the middleware to your application
let app = CRApplication()
app.use(MyMiddleware())
Views and Templates
Criollo supports rendering dynamic web pages by using powerful templating engines. Templating allows you to separate your presentation logic from your application’s business logic, making it easier to manage and maintain large-scale web applications.
You can render a template using the built-in templating engine, or integrate your preferred templating engine:
class MyWebController: CRRouteCollection {
let templateEngine = CRTemplateEngine()
override init(basePath: String) {
super.init(basePath: basePath)
templateEngine.setTemplate(path: "/path/to/template", for: "myTemplate")
}
override func registerRoutes() {
self.get("/users/:userId") { (request, response, context) in
// Render the template with provided data
let renderedTemplate = self.templateEngine.render(template: "myTemplate", data: ["userId": context.params["userId"]])
response.sendText(renderedTemplate)
}
}
}
Static File Support
Criollo makes it easy to serve static files such as CSS, JavaScript, and images. This allows you to include client-side assets in your web application without the need for a separate web server.
To serve static files, use the CRStaticFileManager
class:
// Create a static file manager
let staticFileManager = CRStaticFileManager(basePath: "/path/to/static/files")
// Add the static file manager to your application
let app = CRApplication()
app.use(staticFileManager)
// Access static files using the specified URL path
// For example, "/css/styles.css" will serve the CSS file located at "/path/to/static/files/css/styles.css"
WebSockets
Criollo supports real-time communication channels using WebSockets. WebSockets allow bi-directional communication between the server and clients, enabling real-time updates and interactive features.
To handle WebSocket connections, use the CRWebSocketHandler
class:
class MyWebSocketHandler: CRWebSocketHandler {
override func didOpen(connection: CRWebSocket) {
// Handle WebSocket connection establishment
connection.sendText("Welcome to my WebSocket server!")
}
override func didReceive(text: String, from connection: CRWebSocket) {
// Handle received WebSocket text message
}
override func willClose(connection: CRWebSocket, code: UInt16, reason: String?) {
// Handle WebSocket connection closure
}
}
// Create a WebSocket route
let webSocketRoute = CRWebSocketRoute(url: "/ws", handler: MyWebSocketHandler())
// Add the WebSocket route to your application
let app = CRApplication()
app.addRoute(webSocketRoute)
Authentication
Criollo facilitates implementing secure authentication and authorization mechanisms to protect your web application from unauthorized access. You can integrate various authentication methods such as JSON Web Tokens (JWT) or OAuth.
Deployment
To deploy your Criollo application to production environments, you can utilize various hosting options and deployment strategies. Criollo is flexible and can be deployed as a standalone server or integrated with existing web servers such as Nginx or Apache.
Troubleshooting
If you encounter any issues while using Criollo, refer to the following troubleshooting tips:
- Check the Criollo documentation for relevant information.
- Search the Criollo GitHub repository for known issues and solutions.
- Contact the Criollo community for assistance via the official support channels.
With Criollo, you have the power to build scalable and feature-rich web applications for iOS, macOS, and tvOS. Explore the documentation and unleash the full potential of Criollo in your projects!