mirror of https://github.com/tycrek/ass
Josh Moore
3 years ago
parent
bec15e77b6
commit
7739b2562c
@ -0,0 +1,184 @@
|
||||
### Prior reading
|
||||
|
||||
Please read through the [README][1] before continuing.
|
||||
|
||||
# Create a new repo
|
||||
|
||||
Custom frontends work best when using [Git Submodules][2]. Using submodules makes updates for both ass and your own frontend easier, as the separated codebases won't have any conflicts at all. Any breaking changes to frontend submodules will be clearly noted in release notes, if necessary. Submodules also allow developer freedom for both public & private frontends using any framework they want.
|
||||
|
||||
Start by [creating a new repo][3]:
|
||||
|
||||
![ass frontend repo setup][4]
|
||||
|
||||
# Clone & branch ass
|
||||
|
||||
To make updates easier for both ass and your submodule, **clone** ass locally and checkout a new branch. Don't forget to [install ass][12]!
|
||||
|
||||
![clone both repos][5]
|
||||
|
||||
# Add your frontend repo as a Git Submodule
|
||||
|
||||
While in the ass root directory, run `git submodule add https://github.com/user/repo.git`. This does two things: it clones your repo into the ass project directory; and makes a new file, `.gitmodules`, which tells Git, GitHub, and your IDE to treat your frontends directory as a submodule and not another directory.
|
||||
|
||||
![add a submodule][6]
|
||||
![.gitmodules][7]
|
||||
|
||||
You should notice that your active branch changed from `frontend` to `main`. This is because you are now in your submodules directory, and are technically working on a different Git project now. Any `git` commands will now run for your frontend, rather than ass. To run `git` for ass, simply `cd ../`.
|
||||
|
||||
# Make ass recognize your frontend
|
||||
|
||||
By default, ass tries to search for the `ass-x` frontend (my own private frontend). To make it use your own frontend, [change the `FRONTEND_NAME`][8].
|
||||
|
||||
![change FRONTEND_NAME][9]
|
||||
|
||||
# Set up your frontend project
|
||||
|
||||
`cd` back into your submodule directory. You'll need to run a few commands to get set up. The only required package for developing frontends is [Express.js][10]. [Pug.js][11] is recommended, but optional.
|
||||
|
||||
```bash
|
||||
# You may accept all defaults, **except** for `entry point`, which should be set to **`router.js`**.
|
||||
npm init
|
||||
|
||||
# Get package-lock.json generated
|
||||
npm i
|
||||
|
||||
# The bare minimum package to install is just Express
|
||||
npm i express
|
||||
```
|
||||
|
||||
# Build the router
|
||||
|
||||
Next you need to create your frontend router. Use your preferred editor to create `router.js` (should be located in `path/to/ass/your-frontend/router.js`). You may copy/paste this code snippet and tweak it to your liking:
|
||||
|
||||
```js
|
||||
const { name, version } = require('./package.json');
|
||||
const express = require('express');
|
||||
const router = express.Router();
|
||||
|
||||
// This path will be located at https://your-ass-domain/dashboard/
|
||||
router.get('/', (req, res) => res.send('Welcome to my awesome dashboard!'));
|
||||
|
||||
// https://your-ass-domain/dashboard/login
|
||||
// We will talk about using render later in this wiki
|
||||
router.get('/login', (req, res) => res.render('/path/to/login.pug'));
|
||||
|
||||
// These exports are REQUIRED by ass, so don't forget to set them!
|
||||
// By setting these values, ass will automatically set up Express to host your dashboard.
|
||||
module.exports = {
|
||||
router, // The dashboard router itself
|
||||
enabled: true, // Required to activate frontend in ass; DO NOT change unless you want to disable your frontend
|
||||
brand: `${name} v${version}`, // Printed in ass logs & reported to client. Can be changed to your liking
|
||||
endpoint: '/dashboard' // URL to use for your dashboard router. Can be changed to your liking
|
||||
};
|
||||
```
|
||||
|
||||
Run ass and go to http://localhost:40115/dashboard. You should see `Welcome to my awesome dashboard!`. In the console, ass should have printed your frontend version.
|
||||
|
||||
![dashboard test][13]
|
||||
|
||||
![frontend version in console][14]
|
||||
|
||||
# Success!
|
||||
|
||||
If you see both of the above, then setting up your own custom frontend was a success. From here, you are free to build the dashboard however you wish. ass configures Express to use your router for your chosen `endpoint`, so you just need to make your router return anything a browser can recognize. This means you are able to use Pug, Vue, Angular, React, or even static files to build your frontend (note that static files will be to `your-ass-domain/dashboard-endpoint/static-path` since it is going through your router).
|
||||
|
||||
# Accessing data
|
||||
|
||||
ass manages resource and user data in global managers. To access these managers, simply add these two lines to your router:
|
||||
|
||||
```js
|
||||
// Make sure you either have no extension or use .js, using .json will not work!
|
||||
const users = require('../auth');
|
||||
const data = require('../data');
|
||||
```
|
||||
|
||||
![router with data access][15]
|
||||
|
||||
To test if this worked, you can modify your route to show how many files have been uploaded:
|
||||
|
||||
```js
|
||||
const { name, version } = require('./package.json');
|
||||
const express = require('express');
|
||||
const router = express.Router();
|
||||
|
||||
const users = require('../auth');
|
||||
const data = require('../data');
|
||||
|
||||
router.get('/', (req, res) => res.send(`${Object.keys(data).length} uploads`));
|
||||
```
|
||||
|
||||
![accessing data][16]
|
||||
|
||||
If this worked, you can now use resource and user data however you like within your frontend router.
|
||||
|
||||
# Rendering with Pug
|
||||
|
||||
Don't forget to install Pug with `npm i pug`.
|
||||
|
||||
Because ass sets the Express template engine, you will have to write your frontend in [Pug.js][11] if you want to use `res.render` in your router. If you want to use something other than Pug, no problem! Just write your router to use the other frameworks rendering features, or render them to static HTML (and CSS/JS) files then serve them with `express.static`.
|
||||
|
||||
This introduces a problem though: ass sets the views path as well. Lucky for us, `res.render` accepts absolute paths, so you can make a `views/` directory within your frontend directory, then use `res.render('/path/to/your/frontend/views/filename.pug')`.
|
||||
|
||||
One more issue: because of how your frontend is being loaded, using `__dirname` to make your paths may not always work as expected. Instead, use `process.cwd()` like so:
|
||||
|
||||
```js
|
||||
const { name, version } = require('./package.json');
|
||||
const path = require('path'); // <-- Don't forget to require path
|
||||
const express = require('express');
|
||||
const router = express.Router();
|
||||
|
||||
const users = require('../auth');
|
||||
const data = require('../data');
|
||||
|
||||
/**
|
||||
* Returns an absolute path to a view for Pug using process.cwd()
|
||||
* (helper function I wrote for getting paths consistently)
|
||||
* @param {String} view The view to build a path for
|
||||
* @returns {String} An absolute path
|
||||
*/
|
||||
function getRenderPath(view) {
|
||||
return path.join(process.cwd(), name, 'views/', `${view}.pug`);
|
||||
}
|
||||
|
||||
router.get('/', (req, res) => res.render(getRenderPath('index'), { uploads: Object.entries(data) }));
|
||||
```
|
||||
|
||||
Now make a file at `path/to/your/frontend/views/index.pug`. You can copy/paste these contents to test rendering and using resource data in Pug:
|
||||
|
||||
```
|
||||
h1 Hello!
|
||||
p!= uploads.length
|
||||
```
|
||||
|
||||
When you go to your dashboard endpoint, you should see something similar to this:
|
||||
|
||||
![render pug with data][17]
|
||||
|
||||
If so, then you are now able to render Pug files and also pass data into them.
|
||||
|
||||
# Conclusion
|
||||
|
||||
At this point, you have all the tools you need to build the frontend of your dreams. Custom frontends are still experimental, so expect many improvements and new features in the future. If you have any ideas on how to improve this system, by all means feel free to [open an Issue][18] or [Pull Request][19].
|
||||
|
||||
If you need any further assistance, @ me on the [Official ass Support Discord][20] and I'll try my best to help.
|
||||
|
||||
[1]: https://github.com/tycrek/ass#readme
|
||||
[2]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
|
||||
[3]: https://github.com/new
|
||||
[4]: https://ass.rip/zJMKgJ6XM5qS/direct
|
||||
[5]: https://ass.rip/7GVMD5l5WkFA/direct
|
||||
[6]: https://ass.rip/xUIReBedpJpy/direct
|
||||
[7]: https://ass.rip/6M8VGSgT0Dxu/direct
|
||||
[8]: https://github.com/tycrek/ass/blob/releases/0.6.0/ass.js#L23
|
||||
[9]: https://ass.rip/z3b90x1pDnRt/direct
|
||||
[10]: https://expressjs.com/
|
||||
[11]: https://pugjs.org/
|
||||
[12]: https://github.com/tycrek/ass#installation
|
||||
[13]: https://ass.rip/cFnZctQbkXwQ/direct
|
||||
[14]: https://ass.rip/k4bRfjULy3Vz/direct
|
||||
[15]: https://ass.rip/xlSUx4SHPFEL/direct
|
||||
[16]: https://ass.rip/k52pvaMpj1Et/direct
|
||||
[17]: https://ass.rip/c9J6dUyLYhBe/direct
|
||||
[18]: https://github.com/tycrek/ass/issues/new/choose
|
||||
[19]: https://github.com/tycrek/ass/compare
|
||||
[20]: https://discord.gg/wGZYt5fasY
|
||||
Loading…
Reference in new issue