This is not finished article

Please note that documentation is still in progress. This article may not be finished yet. If you have questions please refer the Github documentation or email us.

Advanced features

Scaffolding

Scaffolding is the automate generation code. Current version of Caravel can generates the left menu.

It works in very simple steps:

  • After you register in Caravel dashboard you create a project and add a project member
  • you provide a Yaml file describing the menu items
  • you send the request to the server using your email and API key
  • server sends the code back and the scaffolding module that is already in the open source version parses it and creates or updates all files.

Let's look at these steps in details

1. Register and get your API key

After the registration you want to create a project and add members. A project is just some entity related with you SaaS application you are working now. Members are emails related to this application. You may use only one email but in many cases it's pretty inconvenient.
To create a project open Projects left menu, you will see the following interface. Click New project button to create a new project. Enter name, description, click Save. Then click Members from the left menu, click Add a new member link, enter user name and email. Return to the projects, click a project you recently created, and you will see the following interface: You can add a new member to the project clicking on From existing members: dropdown. Select a user and click the Add button, the list is updated right now: You can see the this member has an API key - she will use this key (along with her email) do make all API calls to the server.

Projects-members is many-to-many relationship

One user may be included in multiple projects.
One project may have multiple users.
API key is the unique entity describing this relationship (that is every key is always about one project - one member connection).
So, now you are ready to try scaffolding.

2. Create the YAML file describing your menu

Now come back to your SaaS app.
The menu structure is described as Yaml file. This format is pretty straightforward. Navigate to your scaffold folder and open it: Click on left_menu.yaml file that is already included in the code:

  1. Path to the left menu HTML layout file
  2. JavaScript file with route objects that will be used by Vue router and components folder where Vue components files will be put later
  3. If yes the files with components will be generated and put into component folder
  4. Generate breadcrumbs
  5. If no files will not be rewritten - existing code will be commented and new code will go first; the same about files, they will not be touched - so you can put your own code safely
  6. menu details
  7. subment details.
The menu and submenu objects consist of possible elements:
  1. name - The text that will put to the menu item
  2. component - The name of component; if you omit it, the name of component will be generated from the menu text name (all spaces and delimiters will be replaced by underscores).
  3. href - The route url, if omit, the menu item will not open any page; if auto the url will be formed from the component menu
  4. icon - icon styles, for example, "far fa-file". Currently Fontawesome is supported. If omit, no icon will be added to the menu item.

3. Run the command

After you've done with Yaml file you need to add your credentials (API key you created before) info config file or (better) to the environment variables. Navigate to venv/Scripts/activate.bat and provide the following keys: Then open the terminal and run the virtual environment if you didn't do it yet. Just run the project as usual but then stop it (you also can just run venv/Scripts/activate.bat script to run it).
Then in the terminal print the command flask scaffold left_menu or flask scaffold left_menu -u which will run NPM to rebuild the frontend too. You will watch the whole process in the terminal: If you didn't use -u key in the previous comman run NPM: It's all done now!

4. Get the generated menu and all files

Run the project and open the browser. Don't forget to "Empty cache and hard reload". You will see something like that:

You see that scaffolding module sent the request to the server and updates files. Let's see which ones: As you can see the module updated 2 files and generated 4 - each new page is a separate Vue component.