Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mauriceconrad/photon
Clone native desktop UI's like cocoa and develop native feeling applications using web technologies
https://github.com/mauriceconrad/photon
atom css css3 electron electron-app javascript native node-js nodejs web-app
Last synced: about 2 months ago
JSON representation
Clone native desktop UI's like cocoa and develop native feeling applications using web technologies
- Host: GitHub
- URL: https://github.com/mauriceconrad/photon
- Owner: MauriceConrad
- License: mit
- Created: 2017-02-07T17:53:56.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2021-08-22T10:23:01.000Z (over 3 years ago)
- Last Synced: 2024-10-12T15:43:13.435Z (2 months ago)
- Topics: atom, css, css3, electron, electron-app, javascript, native, node-js, nodejs, web-app
- Language: CSS
- Homepage: https://mauriceconrad.github.io/Photon/
- Size: 13.9 MB
- Stars: 409
- Watchers: 15
- Forks: 38
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Photon
[Official Website](https://mauriceconrad.github.io/Photon/)
Develop native looking UI's for **Electron** with HTML, CSS & JS.
## Install
```bash
npm install electron-photon
```
[NPM](https://www.npmjs.com/package/electron-photon)
## Usage
```javascript
// Require photon
const Photon = require("electron-photon");
```
### Use in Browser
If you want to use Photon in a Browser, you have to mention some things.
First of all, embed the browserified script file like anything else using a `` Tag.
But now, you also have to set a relative path for loading the components.
```html
<script src="photon.browser.js">
Photon.__baseDir = "/myPhotonMaster";
```
#### Why?
This is because Photon needs an “endpoint” that contains a `/dist` folder to load each component.
The problem is, that we are embedding the `photon.browser.js` using a former script tag. And sadly, there exist no API to get the relative source of an embedded script from himself. Of course there exist a lot of hacks workarounds but currently this is the only “clean” solution.
**Just look at the magic! Everything works out of the box.**
Your `Photon` instance is just used to contain the component controllers and to perform special actions like `Dialog()` (More about [Dialogs](dist/PhotonDialog)). Or if you want to *hack* a components lifecycle, there you get the classes you need.
### Troubleshooting
**I get an error** `ERR_FILE_NOT_FOUND` when *requiring* the **Photon**. Sometimes the components will not load and you may ask yourself why.
Generally, `Photon` loads each component on its own. Therefore, a general `/dist` folder is required that contains all component folders. By default, the module tries to use the `/dist` folder relative to the location of `photon.js` using node's `__dirname`. Because of the fact that browsers does not support a clear solution to get the relative path of embedded javascript file by itself, you have to set `Photon.__baseDir` manually when using the browserified version. And if you do not contain your `/dist` directory relative to the location of `photon.js` (which is the `main` file for the node module), you also have to set `Photon.__baseDir` manually.
Therefore, if you get such an error, just try to set the `Photon.__baseDir` manually to the `/dist` folder you want to use to load your components
## Example
Just run the `demo/ShowReel` folder with `electron` and will see the whole beauty of Photon!
## Application Layout
The main layout of your application needs a `` element in which the ``'s and your `` will find their place.
```html
Toolbar Header
Window Content
Footer Header
```
## Components
* [Panes](#panes)
* [Navigation](#navigation-list)
* [Toolbar](#toolbar)
* [Table](#table-view)
* [Tabs](#tabs)
* [Lists/Swipes](#lists--swipes)
* [Button](#button)
* [Button Group](#button-group)
* [Circular Slider](#circular-slider)
* [ContentFrame/SelectList](#content-frame--select-list)
* [Input](#input)
* [NumberInput/Stepper](#number-input--stepper)
* [NumberInput](#number-input)
* [ProgressCircle](#progress-circle)
* [Slider](#slider)
* [Dialog](#dialog)
If you have a look at the project's structure, you will see that there exist a very well balanced component system you theoretically can contribute to with custom components.
### Styles
How do I set the **style** of the UI?
`Photon` supports multiple styles, inspired by native user interfaces from *macOS* or *Windows*.
By default, `Photon` tries to use the `style` that is connected to the running OS, stored in `process.platform`. But you can easily set the style to one of the supported ones. Note that the styles do not have the name of an operating system but their **real** name such as *cocoa*.
|Style Name|Related Operating System| Support
|----------|------------------------|------------
| `cocoa` | macOS (Apple) | True
| `metro` | Windows (Microsoft) |Coming soon
| `unity` | Ubuntu (Linux) |Coming soon
#### Set Style
You can easily control the current style just with the `style` property of your `Photon` instance.
```javascript
// Set style
Photon.style = "cocoa";
// Works as expected
```
You can do this whenever you want while your application is running ;-)
Note, that when you set a style the first time in your session, it may takes time to load the resources because they are not cached.
#### Set An Invalid Style
```javascript
// Set style
Photon.style = "xxx";
// Occurs an error
```
### Panes
More about the panes in
[Panes](dist/PhotonPanes)
### Navigation List
More about the navigation list in
[Navigation List](dist/PhotonNavigation)
### Toolbar
More about toolbars in [Toolbar](dist/PhotonToolbar)
### Table View
More about the table view in [Table View](dist/PhotonTable)
### Tabs
More about tabs in [Tabs](dist/PhotonTab)
### Lists & Swipes
#### Lists
#### Swipes
(GIF is slower than in reality)
More about lists & swipe actions in [Lists & Swipes](dist/PhotonSwipe)
### Button
More about all buttons in [Button](dist/PhotonButton)
### Button Group
More about the button group component in [Button Group](dist/PhotonBtnGroup)
### Circular Slider
More about the circular slider in [Circular Slider](dist/PhotonCircularSlider)
### Content Frame & Select List
More about the content frames and selectable lists in [Content Frame & Select List](dist/PhotonContent)
### Input
#### Simple Text Field
#### Number Input & Stepper
More about input fields in [Input](dist/PhotonInput)
### Messages
More about messages view in [Messages](dist/PhotonMessages)
### Number Input
More about number input in [Number Input](dist/PhotonNumberInput)
### Progress Circle
More about progress circle in [Progress Circle](dist/PhotonProgressCircle)
### Slider
More about sliders in [Slider](dist/PhotonSlider)
### Dialog
More about dialog controller in [Dialog](dist/PhotonDialog)
### Drop Down Menu
More about drop down menu controller in [Drop Down Menu](dist/Drop Down Menu)
### Browserify
You can `browserify` the `photon.js` file completely using the `--ignore-missing` flag which ignores the missing `electron` requirements. Please note, that not all features are supported in browsers because they may need electron or node functions.
If you browserify `photon.js` and execute it in a non-node enviroment, the `Photon` instance will adopted globally to the *window* object.
This repository contains a valid browserified file named `photon-browser.js`, you normally should use.
### More
**You are missing something or do you have improvements?**
Please open a *pull-request* or an *Issue* and I will do my best ;-)
## Disclaimer
This framework is a **hard fork** of the original *PhotonKit* framework of *connors*. Because *connors* project is not developed anymore since more than **2** years, this is the release of Photon to version `1.0`.
Pieces of the code that is used here, is originally written by *connors*. The original code is contained within the CSS file `dist/PhotonOriginal/photon-original.css`.
But I made some important changes on the original components. E.g. I use modern technologies like **Custom Elements** to handle components much easier and cleaner and to provide a lighter API ;-)