mirror of
https://github.com/Part-DB/Part-DB-server.git
synced 2025-06-21 01:25:55 +02:00
Improved documentation
This commit is contained in:
Jan Böhmer
parent
d219851143
commit
421f2682d6
17 changed files with 177 additions and 58 deletions
|
|
@ -7,54 +7,50 @@ nav_order: 4
|
|||
# Getting started
|
||||
|
||||
After Part-DB you should begin with customizing the settings, and setting up the basic structures.
|
||||
Before starting its useful to read a bit about the [concepts of Part-DB](https://github.com/Part-DB/Part-DB-symfony/wiki/Concepts).
|
||||
Before starting its useful to read a bit about the [concepts of Part-DB]({% link concepts.md %}).
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
## Customize config files
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
Before you start creating data structures, you should configure Part-DB to your needs by changing possible configuration options.
|
||||
This is done either via changing the `.env.local` file in a direct installation or by changing the env variables in your `docker-compose.yaml` file.
|
||||
A list of possible configuration options, can be found [here](Configuration).
|
||||
|
||||
</details>
|
||||
A list of possible configuration options, can be found [here]({% link configuration.md %}).
|
||||
|
||||
## Change password, Set up Two-Factor-Authentication & Customize User settings
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
If you have not already done, you should change your user password. You can do this in the user settings (available in the navigation bar drop down with the user symbol).
|
||||
|
||||
|
||||
|
||||
|
||||
There you can also find the option, to set up Two Factor Authentication methods like Google Authenticator. Using this is highly recommended (especially if you have admin permissions) to increase the security of your account. (Two Factor Authentication even can be enforced for all members of a user group)
|
||||
|
||||
In the user settings panel you can change account infos like your username, your first and last name (which will be shown alongside your username to identify you better), department information and your email address. The email address is used to send password reset mails, if your system is configured to use this.
|
||||
|
||||
|
||||
|
||||
|
||||
In the configuration tab you can also override global settings, like your preferred UI language (which will automatically be applied after login), the timezone you are in (and in which times will be shown for you), your preferred currency (all money values will be shown converted to this to you, if possible) and the theme that should be used.
|
||||
</details>
|
||||
|
||||
## (Optional) Customize homepage banner
|
||||
|
||||
The banner which is shown on the homepage, can be customized/changed by changing the `config/banner.md` file with a text editor. You can use markdown and (safe) HTML here, to style and customize the banner.
|
||||
You can even use Latex style equations by wrapping the expressions into `$` (like `$E=mc^2$`, which is rendered inline: $E=mc^2$) or `$$` (like `$$E=mc^2$$`) which will be rendered as a block, like so: $$E=mc^2$$
|
||||
|
||||
## Create groups, users and customize permissions
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
### Users
|
||||
|
||||
When logged in as administrator, you can open the users menu in the `Tools` section of the sidebar under `System -> Users`.
|
||||
At this page you can create new users, change their passwords and settings and change their permissions.
|
||||
For each user which should use Part-DB you should setup a own account, so that tracking of what user did what works properly.
|
||||
|
||||
|
||||
|
||||
|
||||
You should check the permissions for every user and ensure that they are in the intended way, and no user has more permissions than he needs.
|
||||
For each capability you can choose between allow, forbid and inherit. In the last case, the permission is determined by the group a user has (if no group is chosen, it equals forbid)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Anonymous user
|
||||
|
|
@ -75,18 +71,14 @@ Users only use the setting of a capability from a group, if the user has a group
|
|||
Groups are organized as trees, meaning a group can have parent and child permissions and child groups can inherit permissions from their parents.
|
||||
To inherit the permissions from a parent group set the capability to inherit, otherwise set it explicitly to override the parents permission.
|
||||
|
||||
</details>
|
||||
|
||||
## Create Attachment types
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
Every attachment (that is an file associated with a part, data structure, etc.) must have an attachment type. They can be used to group attachments logically, like differentiating between datasheets, pictures and other documents.
|
||||
|
||||
You can create/edit attachment types in the tools sidebar under "Edit -> Attachment types":
|
||||
|
||||
|
||||
|
||||
|
||||
Depending on your usecase different entries here make sense. For part mananagment the following (additional) entries maybe make sense:
|
||||
|
||||
|
|
@ -95,42 +87,77 @@ Depending on your usecase different entries here make sense. For part mananagmen
|
|||
|
||||
For every attachment type a list of allowed file types, which can be uploaded to an attachment with this attachment type, can be defined. You can either pass a list of allowed file extensions (e.g. `.pdf, .zip, .docx`) and/or a list of [Mime Types](https://en.wikipedia.org/wiki/Media_type) (e.g. `application/pdf, image/jpeg`) or a combination of both here. To allow all browser supported images, you can use `image/*` wildcard here.
|
||||
|
||||
</details>
|
||||
|
||||
## (Optional) Create Currencies
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
If you want to save priceinformations for parts in a currency different to your global currency (by default Euro), you have to define the additional currencies you want to use under `Edit -> Currencies`:
|
||||
|
||||
|
||||
|
||||
|
||||
You create a new currency, name it however you want (it is recommended to use the official name of the currency) and select the currency ISO code from the list and save it. The currency symbol is determined automatically from chose ISO code.
|
||||
You can define a exchange rate in terms of your base currency (e.g. how much euros is one unit of your currency worth) to convert the currencies values in your preferred display currency automatically.
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## (Optional) Create Measurement Units
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
By default Part-DB assumes that the parts in inventory can be counted by individual indivisible pieces, like LEDs in a box or books in a shelf. However if you want to manage things, that are divisible and and the instock is described by a physical quantity, like length for cables, or volumina of a liquid, you have to define additional measurement units.
|
||||
By default Part-DB assumes that the parts in inventory can be counted by individual indivisible pieces, like LEDs in a box or books in a shelf.
|
||||
However if you want to manage things, that are divisible and and the instock is described by a physical quantity, like length for cables, or volumina of a liquid, you have to define additional measurement units.
|
||||
|
||||
This is possible under `Edit -> Measurement Units`:
|
||||
|
||||
|
||||
|
||||
You can give the measurement unit a name and an optional unit symbol (like `m` for meters) which is shown when quantities in this unit are displayed. The option `Use SI prefix` is useful for almost all physical quantities, as big and small numbers are automatically formatted with SI-prefixes (like 1.5kg instead 1500 grams).
|
||||
|
||||
The measurement unit can be selected for each part individually, by setting the option in the advanced tab of a part`s edit menu.
|
||||
|
||||
</details>
|
||||
## Create Categories
|
||||
|
||||
## (Optional) Customize homepage banner
|
||||
A category is used to group parts logically by their function (e.g. all NPN transistors would be put in a "NPN-Transistors" category).
|
||||
Categories are hierarchical structures meaning that you can create logical trees to group categories together.
|
||||
See [Concepts]({% link concepts.md %}) for an example tree structure.
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
The banner which is shown on the homepage, can be customized/changed by changing the `config/banner.md` file with a text editor. You can use markdown and (safe) HTML here, to style and customize the banner.
|
||||
You can even use Latex style equations by wrapping the expressions into `$` (like `$E=mc^2$`, which is rendered inline: $E=mc^2$) or `$$` (like `$$E=mc^2$$`) which will be rendered as a block, like so: $$E=mc^2$$
|
||||
</details>
|
||||
Creating/Editing categories is done in the tools sidebar under "Edit -> Categories".
|
||||
|
||||
Every part has to be assigned to a category, so you should create at least one category before you start adding parts.
|
||||
|
||||
## (Optional) Create Footprints
|
||||
|
||||
Footprints are used to describe the physical shape of a part, like a resistor or a capacitor.
|
||||
They can be used to group parts by their physical shape and to find parts with in the same package.
|
||||
|
||||
You can create/edit footprints in the tools sidebar under "Edit -> Footprints".
|
||||
|
||||
It is useful to create footprints for the most common packages, like SMD resistors, capacitors, etc. to make it easier to find parts with the same footprint.
|
||||
You should create these as a tree structure, so that you can group footprints by their type.
|
||||
See [Concepts]({% link concepts.md %}) for an example tree structure.
|
||||
|
||||
You can define attachments here which are associated with the footprint. The attachment set as preview image, will be
|
||||
used whenever a visual representation of the footprint is needed (e.g. in the part list).
|
||||
|
||||
For many common footprints, you can use the built-in footprints, which can be found in the "Builtin footprint image gallery", which you can find in the tools menu.
|
||||
Type the name of the image you want to use in the URL field of the attachment and select the image from the dropdown menu.
|
||||
|
||||
## (Optional) Create Storage locations
|
||||
|
||||
A storelocation represents a place where parts can be stored.
|
||||
|
||||
You can create/edit storage locations in the tools sidebar under "Edit -> Storage locations".
|
||||
|
||||
## (Optional) Create Manufacturers and suppliers
|
||||
|
||||
You can create/edit [manufacturers]({% link concepts.md %}#manufacturers) and [suppliers]({% link concepts.md %}#suppliers) in the tools sidebar under "Edit -> Manufacturers" and "Edit -> Suppliers".
|
||||
|
||||
## Create parts
|
||||
|
||||
You are now ready to create your first part. You can do this by clicking either by clicking "Edit -> New Part" in the tools sidebar tree
|
||||
or by clicking the "Create new Part" above the (empty) part list, after clicking on one of your newly created categories.
|
||||
|
||||
You will be presented with a form where you can enter the basic information about your part:
|
||||
|
||||
|
||||
|
||||
You have to enter at least a name for the part and choose a category for it, the other fields are optional.
|
||||
However, it is recommended to fill out as much information as possible, as this will make it easier to find the part later.
|
||||
|
||||
You can choose from your created datastructures to add manufacturer information, supplier information, etc. to the part.
|
||||
You can also create new datastructures on the fly, if you want to add additional information to the part, by typing the
|
||||
name of the new datastructure in the field and select the "New ..." option in the dropdown menu. See [tips]({% link usage/tips_tricks.md %}) for more information.
|
||||
|
|
@ -85,11 +85,11 @@ You can use the "Placeholders" dropdown in content editor, to automatically inse
|
|||
|
||||
If you select "Twig" in parser mode under advanced settings, you can input a twig template in the lines field (activate source mode). You can use most of the twig tags and filters listed in [offical documentation](https://twig.symfony.com/doc/3.x/).
|
||||
|
||||
The following variables are in injected into Twig and can be accessed using `{{ variable }}` (or `{{ variable.property }}`):
|
||||
The following variables are in injected into Twig and can be accessed using `{% raw %}{{ variable }}` (or `{% raw %}{{ variable.property }}{% endraw %}`):
|
||||
|
||||
| Variable name | Description |
|
||||
| ------------- | ----------- |
|
||||
| `{{ element }}` | The target element, selected in label dialog |
|
||||
| `{{ user }}` | The current logged in user. Null if you are not logged in |
|
||||
| `{{ install_title }}` | The name of the current Part-DB instance (similar to [[INSTALL_NAME]] placeholder). |
|
||||
| `{{ page }}` | The page number (the nth-element for which the label is generated |
|
||||
| Variable name | Description |
|
||||
|--------------------------------------| ----------- |
|
||||
| `{% raw %}{{ element }}{% endraw %}` | The target element, selected in label dialog |
|
||||
| `{% raw %}{{ user }}{% endraw %}` | The current logged in user. Null if you are not logged in |
|
||||
| `{% raw %}{{ install_title }}{% endraw %}` | The name of the current Part-DB instance (similar to [[INSTALL_NAME]] placeholder). |
|
||||
| `{% raw %}{{ page }}{% endraw %}` | The page number (the nth-element for which the label is generated |
|
||||
65
docs/usage/tips_tricks.md
Normal file
65
docs/usage/tips_tricks.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
title: Tips & Tricks
|
||||
layout: default
|
||||
parent: Usage
|
||||
---
|
||||
|
||||
# Tips & Tricks
|
||||
|
||||
Following you can find miscellaneous tips and tricks for using Part-DB.
|
||||
|
||||
## Create datastructures directly from part edit page
|
||||
|
||||
Instead of first creating a category, manufacturer, footprint, etc. and then creating the part, you can create the
|
||||
datastructures directly from the part edit page: Just type the name of the datastructure you want to create into the
|
||||
select field on the part edit page and press "Create new ...". The new datastructure will be created, when you save
|
||||
the part changes.
|
||||
|
||||
You can create also create nested datastructures this way. For example, if you want to create a new category "AVRs",
|
||||
as a subcategory of "MCUs", you can just type "MCUs->AVRs" into the category select field and press "Create new".
|
||||
The new category "AVRs" will be created as a subcategory of "MCUs". If the category "MCUs" does not exist, it will
|
||||
be created too.
|
||||
|
||||
## Builtin footprint images
|
||||
Part-DB includes several builtin images for common footprints. You can use these images in your footprint datastructures,
|
||||
by creating an attachment on the datastructure and selecting it as preview image.
|
||||
Type the name of the footprint image you want to use into the URL field of the attachment and select it from the
|
||||
dropdown menu. You can find a gallery of all builtin footprint images and their names in the "Builtin footprint image gallery",
|
||||
which you can find in the "Tools" menu (you maybe need to give your user the permission to access this tool).
|
||||
|
||||
## Parametric search
|
||||
In the "parameters" tab of the filter panel on parts list page, you can define constraints, which parameter values
|
||||
have to fullfill. This allows you to search for parts with specific parameters (or parameter ranges), for example you
|
||||
can search for all parts with a voltage rating of greater than 5 V.
|
||||
|
||||
## View own users permissions
|
||||
If you want to see which permissions your user has, you can find a list of the permissions in the "Permissions" panel
|
||||
on the user info page.
|
||||
|
||||
## Use LaTeX equations
|
||||
You can use LaTeX equations everywhere where markdown is supported (for example in the description or notes field of a part).
|
||||
[KaTeX](https://katex.org/) is used to render the equations.
|
||||
You can find a list of supported features in the [KaTeX documentation](https://katex.org/docs/supported.html).
|
||||
|
||||
To input a LaTeX equation, you have to wrap it in a pair of dollar signs (`$`). Single dollar signs mark inline equations,
|
||||
double dollar signs mark displayed equations (which will be its own line and centered). For example, the following equation
|
||||
will be rendered as an inline equation:
|
||||
|
||||
```
|
||||
$E=mc^2$
|
||||
```
|
||||
|
||||
while this one will be rendered as a displayed equation:
|
||||
|
||||
```
|
||||
$$E=mc^2$$
|
||||
```
|
||||
|
||||
## Update currency exchange rates automatically
|
||||
Part-DB can update the currency exchange rates of all defined currencies programatically
|
||||
by calling the `php bin/console partdb:currencies:update-exchange-rates`.
|
||||
|
||||
If you call this command regularly (e.g. with a cronjob), you can keep the exchange rates up-to-date.
|
||||
|
||||
Please note that if you use a base currency, which is not the Euro, you have to configure an exchange rate API, as the
|
||||
free API used by default only supports the Euro as base currency.
|
||||
Loading…
Add table
Add a link
Reference in a new issue