criollo

Welcome to the documentation for Criollo, a Swift and Objective-C web application framework for iOS, macOS, and tvOS.

Table of Contents

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:

  1. Install Criollo using CocoaPods or Carthage.
  2. Create a new Swift or Objective-C project in Xcode.
  3. Import the Criollo framework and initialize it in your AppDelegate.
  4. Implement your web application logic by defining routes and handlers.
  5. 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!