diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6432989 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,28 @@ +# Changelog + +## Changes in 1.5 + +- Support for iOS hibernation and wakeup + +## Changes in 1.4 + +- Support for `~H` sigil with `` +- Changed Menu XML escaping to LiveView automatic escaping logic from LiveView HTML tokenizer & engine. +- Removed `Menu.escape_attribute/1` and `Menu.escape/1` +- Dropped `:xmerl` dependency + +## Changes in 1.3 + +- Added `Env.subscribe/1` to listen to MacOS application events such as `{:open_url, url}` when a url associated with the application is clicked. +- Using (experimental) dbus support to render the systray icon on linux +- Added `Menu.escape_attribute/1` +- Added `Window.url/1` +- Added `Window.hide/1` and `Window.is_hidden/` +- Fixed MacOS "Quit" menu item +- Other fixes + +## Changes in 1.2 + +- Removed the bleeding edge notices because Erlang OTP 24 is now broadly available for Windows/Linux/MacOS +- Added build support for iOS devices +- Moved most phoenix dependencies out to allow using Phoenix 1.6 / esbuild diff --git a/README.md b/README.md index 49cc9c5..83c259d 100644 --- a/README.md +++ b/README.md @@ -6,59 +6,33 @@ [![License](https://img.shields.io/hexpm/l/desktop.svg)](https://github.com/elixir-desktop/desktop/blob/master/LICENSE.md) [![Last Updated](https://img.shields.io/github/last-commit/elixir-desktop/desktop.svg)](https://github.com/elixir-desktop/desktop/commits/master) - Building native-like Elixir apps for Windows, MacOS, Linux, iOS and Android using Phoenix LiveView! -## Changes in 1.5 -- Support for iOS hibernation and wakeup - -## Changes in 1.4 - -- Support for `~H` sigil with `` -- Changed Menu XML escaping to LiveView automatic escaping logic from LiveView HTML tokenizer & engine. -- Removed `Menu.escape_attribute/1` and `Menu.escape/1` -- Dropped `:xmerl` dependency - -## Changes in 1.3 - -- Added `Env.subscribe/1` to listen to MacOS application events such as `{:open_url, url}` when a url associated with the application is clicked. -- Using (experimental) dbus support to render the systray icon on linux -- Added `Menu.escape_attribute/1` -- Added `Window.url/1` -- Added `Window.hide/1` and `Window.is_hidden/` -- Fixed MacOS "Quit" menu item -- Other fixes - -## Changes in 1.2 - -- Removed the bleeding edge notices because Erlang OTP 24 is now broadly available for Windows/Linux/MacOS -- Added build support for iOS devices -- Moved most phoenix dependencies out to allow using Phoenix 1.6 / esbuild - ## Example -Checkout the Todo sample application for a starting point. https://github.com/elixir-desktop/desktop-example-app +Checkout [the example app](https://github.com/elixir-desktop/desktop-example-app) for a starting point. -![MacOS build](https://raw.githubusercontent.com/elixir-desktop/desktop-example-app/main/nodeploy/macos_todo.png "MacOS build") +![MacOS build](https://raw.githubusercontent.com/elixir-desktop/desktop-example-app/main/nodeploy/macos_todo.png 'MacOS build') ## Getting Started -Check out the [Getting your Environment Ready Guide](./guides/getting_started.md) and [Your first Desktop App](./guides/your_first_app.md) +Check out the [Getting your Environment Ready Guide](./guides/getting_started.md) and [Your first Desktop App](./guides/your_first_desktop_app.md) ## Status / Roadmap -1. Run elixir-desktop on MacOS/Windows/Android ✅ -1. Run elixir-desktop on Android/iOS ✅ -1. Package elixir-desktop based apps for Android/iOS ✅ (see example-app repo for iOS and Android) -1. Package elixir-desktop based apps in installers for MacOS/Windows/Linux -1. Update the desktop example app built installers for MacOS/Windows/Linux using GitHub actions -1. Use a repo of pre-compiled Erlang binaries for Android/iOS/MacOS/Windows/Linux when building Apps, so one call of `mix desktop.deploy` will create installer for all platforms. -1. Integrate Code Signing for Windows/MacOS -1. Build a GitHub actions based auto-update flow +1. ✅ Run elixir-desktop on Windows/MacOS/Linux +2. ✅ Run elixir-desktop on iOS/Android +3. ✅ Package elixir-desktop based apps for iOS/Android (see example-app repo for iOS and Android) +4. Package elixir-desktop based apps in installers for Windows/MacOS/Linux +5. Update the desktop example app built installers for Windows/MacOS/Linux using GitHub actions +6. Use a repo of pre-compiled Erlang binaries for Windows/MacOS/Linux/iOS/Android when building Apps, so one call of `mix desktop.deploy` will create installer for all platforms. +7. Integrate Code Signing for Windows/MacOS +8. Build a GitHub actions based auto-update flow ## Contributing and Raising Issues -Please checkout the github repo at https://github.com/elixir-desktop/desktop and raise any issues. For questions and comments best to use the Elixir forum: https://elixirforum.com/t/elixir-desktop-android-window-macos-linux-liveview-apps-with-elixir/ or contact me on Slack https://elixir-lang.slack.com/archives/C02429KJJCX +- Please checkout [the GitHub repo](https://github.com/elixir-desktop/desktop) and raise any issue. +- For questions and comments best to use the [Elixir forum](https://elixirforum.com/t/elixir-desktop-android-window-macos-linux-liveview-apps-with-elixir/) or contact me on [Slack](https://elixir-lang.slack.com/archives/C02429KJJCX). All suggestions are welcome! diff --git a/guides/your_first_app.md b/guides/your_first_app.md deleted file mode 100644 index ebef4f4..0000000 --- a/guides/your_first_app.md +++ /dev/null @@ -1,83 +0,0 @@ -# Your first Desktop App - -If you prefer to start with a working Desktop sample application, please refer to https://github.com/elixir-desktop/desktop-example-app - -To convert a barebones Phoenix Live View example to a Desktop Application you will need to add this to your application: - -1. Add the `desktop` dependency to your project's dependencies in `mix.exs` - - ```elixir - def deps do - [ - {:desktop, "~> 1.5"} - ] - end - ``` - -1. Add a Desktop.Window child to your supervision tree on startup. E.g. in `application.ex` - - ```elixir - children = [ - # After your other children - # Starting Desktop.Windows - {Desktop.Window, - [ - app: :your_app, - id: YourAppWindow, - url: &YourAppWeb.Endpoint.url/0 - ]} - ] - Supervisor.start_link() - ``` - - Note: you still need to start your phoenix Endpoint, add `Desktop.Window` in _addition_ to your `Desktop.Window` - -1. In `endpoint.ex` call `use Desktop.Endpoint` **instead of** `use Phoenix.Endpoint` - - ```elixir - defmodule YourAppWeb.Endpoint do - use Desktop.Endpoint, otp_app: :your_app - ... - end - ``` - - 1. Consider authenticating requests - - Adding the `Desktop.Auth` plug to your endpoint ensures that only request from the app's webview are allowed. - - ```elixir - defmodule YourAppWeb.Endpoint do - ... - plug Desktop.Auth - plug YourAppWeb.Router - end - ``` - -1. In your application configuration (by default in `config/dev.exs` and `config/runtime.exs)` ensure http is configured and the port is set to `0` so it's chosen automatically, as well as setting `server: true` so that your Phoenix Endpoint starts automatically (without having to explicitly call `mix phx.server`): - - ```elixir - # Configures the endpoint - config :your_app, YourAppWeb.Endpoint, - http: [ip: {127, 0, 0, 1}, port: 0], - server: true, - ... - ``` - -1. For localization and to autodetect the desktop language (optional), add the detection hook to your application startup. E.g. in `application.ex`: - - - ```elixir - def start(_type, args) do - Desktop.identify_default_locale(YourWebApp.Gettext) - - children = [ - ... - ] - - ... - end - ``` - -1. Run your application with `mix run` - - The desktop application window should now be visible! diff --git a/guides/your_first_desktop_app.md b/guides/your_first_desktop_app.md new file mode 100644 index 0000000..c4f7f73 --- /dev/null +++ b/guides/your_first_desktop_app.md @@ -0,0 +1,115 @@ +# Your first Desktop App + +> If you prefer to start with a working Desktop sample application, please refer to [elixir-desktop/desktop-example-app](https://github.com/elixir-desktop/desktop-example-app). + +## 1. Create a demo Phoenix LiveView app + +``` +$ mix phx.new demo --no-ecto --no-dashboard --no-mailer +``` + +After running this command, a demo Phoenix LiveView app will be created: + +- OTP app name is `:demo` +- root module name is `Demo` +- web root module name is `DemoWeb` + +## 2. Change above app as a Desktop app + +### 2.1 Add required dependency + +Add `desktop` package to the dependencies in `mix.exs`: + +```elixir +def deps do + [ + # ... + {:desktop, github: "elixir-desktop/desktop"} + ] +end +``` + +### 2.2 Tweak existing Phoenix endpoint + +```elixir +defmodule DemoWeb.Endpoint do + # Step 1: Change the endpoint as a `Desktop` endpoint. + use Desktop.Endpoint, otp_app: :demo + + # ... + + # Step 2: Add `Desktop.Auth` plug to ensure that only requests from + # the Desktop app's WebView are allowed. + plug Desktop.Auth + + plug YourAppWeb.Router +end +``` + +### 2.3 Add child specification for opening WebView window + +```elixir +defmodule Demo.Application do + # ... + + def start(_type, _args) do + children = [ + # ... + + DemoWeb.Endpoint, + {Desktop.Window, + [ + app: :demo, + id: DemoWindow, + url: &DemoWeb.Endpoint.url/0 + ]} + ] + + # ... + end +end +``` + +### 2.4 Configure the Desktop endpoint + +> You can configure it in `config/dev.exs` or `config/runtime.exs`. + +``` +config :demo, DemoWeb.Endpoint, + # Step 1: set the port number to 0, so the port can be chosen automatically. + http: [ip: {127, 0, 0, 1}, port: 0], + + # Step 2: start endpoint automatically, so we have no need to start it manually. + server: true, + # ... +``` + +## 3. Extra Steps (optional) + +### 3.1 Localization support + +For localization and to autodetect the desktop language, desktop provides a helper function for that. You can call it before starting the app: + +```elixir +defmodule Demo.Application do + # ... + + def start(_type, _args) do + Desktop.identify_default_locale(DemoWeb.Gettext) + + children = [ + # ... + ] + + # ... + end +end +``` + +## 4. Run it + +``` +$ mix run +``` + +The Desktop app should be visible now! diff --git a/mix.exs b/mix.exs index e280d0b..e143d60 100644 --- a/mix.exs +++ b/mix.exs @@ -1,6 +1,9 @@ defmodule Desktop.MixProject do use Mix.Project + @description """ + Building native-like Elixir apps for Windows, MacOS, Linux, iOS and Android using Phoenix LiveView! + """ @version "1.5.2" @url "https://github.com/elixir-desktop/desktop" @@ -10,10 +13,8 @@ defmodule Desktop.MixProject do name: "Desktop", version: @version, source_url: @url, - description: """ - Write Windows, Linux, MacOS, Android, iOS Apps with Elixir. - """, - elixir: "~> 1.10", + description: @description, + elixir: "~> 1.11", elixirc_paths: elixirc_paths(Mix.env()), compilers: Mix.compilers(), aliases: aliases(), @@ -101,8 +102,9 @@ defmodule Desktop.MixProject do extras: [ "LICENSE.md": [title: "License"], "README.md": [title: "Overview"], + "CHANGELOG.md": [title: "Changelog"], "guides/getting_started.md": [title: "Getting your Environment Ready"], - "guides/your_first_app.md": [title: "Your first Desktop App"] + "guides/your_first_desktop_app.md": [title: "Your first Desktop App"] ], main: "readme", source_ref: "v#{@version}",