## 1. Project Overview & Quickstart (hahwul/quick-start) # quick-start Open-source repository hahwul/quick-start ### Repository Details - **Repository:** [hahwul/quick-start](https://github.com/hahwul/quick-start) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (hahwul/docs) ## File: README.md # Introduction Amber is a web development framework written in the Crystal programming language. The framework implements the server-side MVC pattern using the object-oriented paradigm. Many of Amber's components and concepts will be familiar for developers with experience with other web frameworks like Phoenix, Ruby on Rails or Python's Django. Amber aims to deliver developer happiness, productivity, and bare metal performance. The Crystal language is heavily inspired by Ruby, delivering familiarity, productivity, and a low learning curve for experienced Ruby developers. Meanwhile, Crystal also has some modern features like macros, first class concurrency, union types, C bindings, and a built in dependency manager. Amber takes advantage of all these features providing you an opinionated structure to develop a web application. Amber offers a variety of familiar tools such as generators, database management, CLI, deployment tools, docker support, encrypted secrets, websockets, and more for fast prototyping and developing enterprise-grade web applications. If you come from a Ruby on Rails background you will feel right at home, but, be aware Amber is not Rails! Amber is type-safe, compiled, and embraces the best features from many different frameworks for example pipes for routing which is more similar to the Phoenix framework. The aim of this introductory guide is to present a high-level overview of Amber Framework and the layers underneath that support it. ## Getting Help If you’re stuck, there are a number of places you can get help. * [**Gitter**](https://gitter.im/amberframework/amber) for quick questions. * [**Stack Overflow**](https://stackoverflow.com/questions/tagged/amber-framework) for questions about the Crystal Language and Amber Framework. * [**Github**](https://github.com/amberframework/amber) for getting acquainted with source code, current issues and progress. * [**Online Guides**](https://docs.amberframework.org/amber) for getting down and dirty working with Amber. * [**Twitter**](https://twitter.com/amberframework) to see latest news and announcements about Amber Framework. ## Contributing Contributing to Amber can be a rewarding way to learn, teach, and build experience in just about any skill you can imagine. You don’t have to become a lifelong contributor to enjoy participating in Amber. Amber is a community effort and we want You to be part of ours [Join Amber Community!](https://github.com/amberframework/amber/blob/master/.github/CONTRIBUTING.md) ## First Steps Learning a new framework can be intimidating and exciting at the same time. To help you along, we have created a cookbook packed with examples and recipes to get the common tasks completed. If you are new, you should start off with the [guides](guides/). If you want a step by step tutorial try the [quick start](getting-started/). Happy developing! --- ## File: cli/README.md # CLI Amber has a built in CLI tool, to make your life easier while developing applications. Here is a list of the available commands: * **db, database** - Performs database maintenance tasks * **e, encrypt** - Encrypts environment YAML file. \[env \| -e --editor \| --noedit\] * **x, exec** - Executes Crystal code within the application scope * **g, generate** - Generate Amber classes * **n, new** - Generates a new Amber project * **routes** - Prints all defined application routes * **w, watch** - Starts amber development server and rebuilds on file changes Read a long this guide to learn more about these command and how much time and efficient it can make your development experience. ## Getting Command Help You can get help from each command by running `-h` or `--help` next to the command Eg. ```text $ amber --help ``` This will output to your shell the following documentation. ```text amber [OPTIONS] SUBCOMMAND Amber - Command Line Interface The `amber new` command creates a new Amber application with a default directory structure and configuration at the path you specify. You can specify extra command-line arguments to be used every time `amber new` runs in the .amber.yml configuration file in your project root directory Note that the arguments specified in the .amber.yml file does not affect the defaults values shown above in this help message. Usage: amber new [app_name] -d [pg | mysql | sqlite] -t [slang | ecr] -m [granite, crecto] --deps Subcommands: db, database # Performs database maintenance tasks e, encrypt # Encrypts environment YAML file. [env | -e --editor | --noedit] x, exec # Executes Crystal code within the application scope g, generate # Generate Amber classes n, new # Generates a new Amber project routes # Prints all defined application routes w, watch # Starts amber development server and rebuilds on file changes Options: -d, --database # Preconfigure for selected database. Options: pg | mysql | sqlite (default: pg) -m, --model # Preconfigure for selected model. Options: granite (default: granite) -t, --template # Preconfigure for selected template engine. Options: slang | ecr (default: slang) -h, --help # Describe available commands and usages -v, --version # Prints Amber version Example: amber new ~/Code/Projects/weblog This generates a skeletal Amber installation in ~/Code/Projects/weblog. ``` ## Usage ```bash amber new [your_app] -d [pg | mysql | sqlite] -t [slang | ecr] --deps cd [your_app] ``` ### Options * `-d` defaults to pg * `-t` defaults to slang * `--deps` will run `crystal deps` for you. --- ## File: cookbook/README.md # Cookbook This Amber Cookbook is inspired by original [Kemal Cookbook](http://kemalcr.com/cookbook/hello_world/) by [@sdogruyol](https://github.com/sdogruyol) {% page-ref page="from-scratch.md" %} {% page-ref page="hello-world.md" %} {% page-ref page="cors.md" %} {% page-ref page="file-download.md" %} {% page-ref page="file-upload.md" %} {% page-ref page="authenticate.md" %} {% page-ref page="json-api.md" %} {% page-ref page="json-mapping.md" %} {% page-ref page="websocket-chat.md" %} --- ## File: deployment/README.md --- --- # Deployment {% hint style="info" %} This section contain guides for deploying amber projects to Digital Ocean and Heroku {% endhint %} {% hint style="warning" %} Guides for other platforms like Amazon Web Services \(AWS\), Google Compute Engine \(GCE\) and Azure are work in progress... {% endhint %} {% page-ref page="manual-deploy.md" %} {% page-ref page="digital-ocean.md" %} {% page-ref page="heroku.md" %} {% page-ref page="dokku.md" %} --- ## File: examples/README.md # Examples {% page-ref page="amber-auth.md" %} {% page-ref page="crystal-debug.md" %} {% page-ref page="json-api-full-crud.md" %} {% page-ref page="minimal-configuration.md" %} --- ## File: getting-started/README.md # Getting Started ## Quick Start This quick start guide will help you get a full stack web application running in just a few minutes by leveraging amber’s code generators. It will take us just 7 steps. Let’s get started! ## 1. Install dependencies {% hint style="info" %} If you already have `crystal`, `amber`, and a database installed, you can [skip this step](quick-start.md#2-generate-a-new-amber-application). {% endhint %} ### 1.1 Install `crystal` and `amber` Instructions for OS X using Homebrew or MacPorts and Debian/Ubuntu are below. See full installation instructions [here](https://crystal-lang.org/docs/installation/) for RedHat & CentOS, ArchLinux & Derivatives, and more complete instructions. #### macOS Installing Amber with these package managers also installs Crystal. - Homebrew ```text brew tap amberframework/amber brew install amber ``` - MacPorts ```text sudo port selfupdate sudo port install amber ``` #### Ubuntu or Debian First install crystal (from the [official install documentation](https://crystal-lang.org/install/on_ubuntu/)): ```text curl -fsSL https://crystal-lang.org/install.sh | sudo bash ``` Then install Amber \(from source\) ```text sudo apt-get install libreadline-dev libsqlite3-dev libpq-dev libmysqlclient-dev libssl-dev libyaml-dev libpcre3-dev libevent-dev curl -L https://github.com/amberframework/amber/archive/stable.tar.gz | tar xz cd amber-stable/ shards install make install ``` You can also install Amber with [Linuxbrew](http://linuxbrew.sh/) ```bash brew tap amberframework/amber brew install amber ``` {% hint style="info" %} Above are the steps for building from source, the dependencies are specific to Ubuntu/Debian. See [full installation instructions](../guides/installation.md) for other Linux Distributions. {% endhint %} ### 1.2 Install a database Amber works with `postgresql` \(default\), `mysql`, or `sqlite`. If you don’t already have one of these installed, please follow the guides provided by each database maintainer: * [Postgresql Installation Guides](https://wiki.postgresql.org/wiki/Detailed_installation_guides) * [MySQL Installation Guides](https://dev.mysql.com/doc/refman/8.0/en/installing.html) * [Tutorial on installing SQLite](https://www.tutorialspoint.com/sqlite/sqlite_installation.htm) {% hint style="info" %} On OS X any of the databases can be installed with `brew install [database]` {% endhint %} {% hint style="info" %} Docker users can opt to use a database container to develop with as well. By default, a new Amber application generates a `docker-compose.yml` that can be used for this purpose. {% endhint %} ## 2. Generate a new Amber application With all dependencies successfully installed, we can generate a new application with `amber new` After the code for the new application is generated, we will `cd` into the new directory and execute a `shards install`. The shards install command may take a little while - it has to download all shard dependencies. {% hint style="info" %} The default setup will use a postgresql database, use `-d mysql` or `-d sqlite` for mysql and sqlite, respectively. {% endhint %} ```text amber new pet-tracker cd pet-tracker ``` ## 3. Generate a resource With the skeleton application generated, we can generate our first RESTful resource. The `amber generate scaffold` command will help us do this. {% hint style="info" %} `g` is shorthand for `generate` {% endhint %} ```text amber g scaffold Pet name:string breed:string age:integer ``` ## 4. Create and migrate the database Generating the application and the scaffolded resource provides the configuration and migration files needed to set up the database. `amber db` will help us do this, as you will see you can chain the `db` commands together. ```text amber db create migrate ``` This will create a new database and run the migration to create a `pets` table with the specified columns. ## 5. Build the application and run the server We can use `amber watch` to both build the binary application and start the server. Additionally, `amber watch` will detect code changes then recompile and restart the application automatically. ```text amber watch ``` The `watch` commands will keep observing for file changes within the project and recompiling the application. ## 6. Use your brand new web application! Open any browser and goto [http://localhost:3000](http://localhost:3000) You should see a home page load and “Pets” in the nav bar. If you click on the “Pets” link, you should be able to perform all seven RESTful actions for the “pets” resource. ## 7. Deploy your web application {% page-ref page="../deployment/" %} ## List of Commands You can use these commands to create new awesome applications :-\) ```text amber new pet-tracker cd pet-tracker shards install amber generate scaffold Pet name:string breed:string age:integer amber db create migrate amber watch ``` ## Demo Here is the Quick Start demo app and the source code is available on [Github](https://github.com/faustinoaq/pet-tracker). {% page-ref page="../guides/" %} --- ## File: guides/controllers/cookies.md # Cookies Cookies are read and written through **Amber::Base::Controller\#cookies**. The cookies being read are the ones received along with the request, the cookies being written will be sent out with the response. Reading a cookie does not get the cookie object itself back, just the value it holds. It's advisable that you only store simple data \(strings and numbers\) in cookies. If you have to store complex objects, you would need to handle the conversion manually when reading the values on subsequent requests. Amber also has an encrypted cookie jar for storing sensitive data. The encrypted cookie jar encrypts the values in addition to signing them, so that they cannot be read by the end user. ## Examples of writing ```ruby class CommentsController < ApplicationController def new # Auto-fill the commenter's name if it has been stored in a cookie @comment = Comment.new(author: cookies[:commenter_name]) end def create @comment = Comment.new(params[:comment]) if @comment.save flash[:notice] = "Thanks for your comment!" if params[:remember_name] # Remember the commenter's name. cookies[:commenter_name] = @comment.author else # Delete cookie for the commenter's name cookie, if any. cookies.delete(:commenter_name) end redirect_to @comment.article else render action: "new" end end end ``` ## Examples of reading ```ruby cookies[:user_name] # => "david" cookies.size # => 2 JSON.parse(cookies[:lat_lon]) # => [47.68, -122.37] cookies.encrypted[:discount] # => 45 ``` Please note that if you specify a :domain when setting a cookie, you must also specify the domain when deleting the cookie: ```ruby cookies.set "name", "a yummy cookie", expires: 1.year.from_now, domain: "domain.com" cookies.delete "name", domain: "domain.com" ``` The optional parameters for setting cookies are: ```ruby path # The path for which this cookie applies. Defaults to the root of the application. domain # The domain for which this cookie applies so you can restrict to the domain level. # If you use a schema like www.example.com and want to share session with user.example.com # set :domain to :all. Make sure to specify the :domain option with :all or Array again # when deleting cookies. domain: nil # Does not set cookie domain. (default) domain: :all # Allow the cookie for the top most level domain and subdomains. domain: %w(.example.com .example.org) # Allow the cookie for concrete domain names. tld_length # When using :domain => :all, this option can be used to explicitly set the TLD length # when using a short (<= 3 character) domain that is being interpreted as part of a TLD. # For example, to share cookies between user1.lvh.me and user2.lvh.me, set :tld_length to 1. expires # The time at which this cookie expires, as a Time object. secure # Whether this cookie is only transmitted to HTTPS servers. Default is false. httponly # Whether this cookie is accessible via scripting or only HTTP. Defaults to false. ``` --- ## File: guides/controllers/csrf.md # CSRF To use CSRF, enable the pipe in your `routes.cr` by adding the following pipe to a pipeline. ``` plug Amber::Pipe::CSRF.new ``` Then, insert the `csrf_tag` helper in your forms. ## How to use CSRF with AJAX Simply call the `csrf_tag` helper inside your controller and return it as part of a JSON object: ```ruby def my_action {csrf: csrf_tag}.to_json end ``` In your Javascript, after getting the JSON object back, refresh your CSRF tag with the one from the server. ```javascript $("input[name*=_csrf]").replaceWith(e['csrf']); ``` --- ## File: guides/controllers/filters.md # Filters Filters are methods that are run "before", "after" or "around" a controller action. Filters are inherited, so if you set a filter on`ApplicationController`, it will be run on every controller in your application. ## Before filter "before" filters may halt the request cycle. A common "before" filter is one which requires that a user is logged in for an action to be run. You can define the filter method this way: ```ruby # Filters are methods that are run "before", "after" a controller action. before_action do # runs for specified actions only [:index, :world, :show] { increment(1) } # runs for all actions all { increment(1) } end ``` ## After filter "after" filters are executed after the request cycle. A common "after" filter is one which requires to cleanup user data after an action has been run. You can define the filter method this way: ```ruby after_action do # runs for specified actions only [:index, :world] { increment(1) } end ```