mirror/Part-DB.Part-DB-server
1
0
Fork 1
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2025-07-08 17:34:32 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Fixed formatting and typos in documentation

Browse source
This commit is contained in:
Jan Böhmer 2023-10-15 13:21:14 +02:00
parent 47fc7db953
commit f32c0f52b6
24 changed files with 1512 additions and 730 deletions
Download patch file Download diff file Expand all files Collapse all files

49
docs/usage/backup_restore.md
View file

@ -6,48 +6,75 @@ parent: Usage
# Backup and Restore Data
When working productively you should backup the data and configuration of Part-DB regularly to prevent data loss. This is also useful, if you want to migrate your Part-DB instance from one server to another. In that case you just have to backup the data on server 1, move the backup to server 2, install Part-DB on server 2 and restore the backup.
When working productively you should back up the data and configuration of Part-DB regularly to prevent data loss. This
is also useful, if you want to migrate your Part-DB instance from one server to another. In that case you just have to
back up the data on server 1, move the backup to server 2, install Part-DB on server 2 and restore the backup.
## Backup (automatic / Part-DB supported)
Part-DB includes a command `php bin/console partdb:backup` which automatically collects all the needed data (described below) and saves them to a ZIP file.
Part-DB includes a command `php bin/console partdb:backup` which automatically collects all the needed data (described
below) and saves them to a ZIP file.
If you are using a MySQL/MariaDB database you need to have `mysqldump` installed and added to your `$PATH` env.
### Usage
To backup all possible data, run the following command: `php bin/console partdb:backup --full /path/to/backup/partdb_backup.zip`.
It is possible to do only partial backups (config, attachments, or database). See `php bin/console partdb:backup --help` for more infos about these options.
To back up all possible data, run the following
command: `php bin/console partdb:backup --full /path/to/backup/partdb_backup.zip`.
It is possible to do only partial backups (config, attachments, or database). See `php bin/console partdb:backup --help`
for more infos about these options.
## Backup (manual)
There are 3 parts which have to be backup-ed: The configuration files, which contains the instance specific options, the uploaded files of attachments, and the database containing the most data of Part-DB.
There are 3 parts which have to be backup-ed: The configuration files, which contains the instance specific options, the
uploaded files of attachments, and the database containing the most data of Part-DB.
Everything else like thumbnails and cache files, are recreated automatically when needed.
### Configuration files
You have to copy the `.env.local` file and (if you have changed it) the `config/parameters.yaml` and `config/banner.md` to your backup location.
You have to copy the `.env.local` file and (if you have changed it) the `config/parameters.yaml` and `config/banner.md`
to your backup location.
### Attachment files
You have to recursively copy the `uploads/` folder and the `public/media` folder to your backup location.
### Database
#### Sqlite
If you are using sqlite, it is sufficient to just copy your `app.db` from your database location (normally `var/app.db`) to your backup location.
If you are using sqlite, it is sufficient to just copy your `app.db` from your database location (normally `var/app.db`)
to your backup location.
#### MySQL / MariaDB
For MySQL / MariaDB you have to dump the database to an SQL file. You can do this manually with phpmyadmin, or you use [`mysqldump`](https://mariadb.com/kb/en/mariadb-dumpmysqldump/) to dump the database to an SQL file via command line interface (`mysqldump -uBACKUP -pPASSWORD DATABASE`)
For MySQL / MariaDB you have to dump the database to an SQL file. You can do this manually with phpmyadmin, or you
use [`mysqldump`](https://mariadb.com/kb/en/mariadb-dumpmysqldump/) to dump the database to an SQL file via command line
interface (`mysqldump -uBACKUP -pPASSWORD DATABASE`)
## Restore
Install Part-DB as usual as described in the installation section, with the exception of the database creation / migration part. You have to use the same database type (sqlite or mysql) as on the back-uped server instance.
Install Part-DB as usual as described in the installation section, except the database creation / migration part. You
have to use the same database type (sqlite or mysql) as on the back-up server instance.
### Restore configuration
Copy configuration files `.env.local`, (and if existing) `config/parameters.yaml` and `config/banner.md` from the backup to your new Part-DB instance and overwrite the existing files there.
Copy configuration files `.env.local`, (and if existing) `config/parameters.yaml` and `config/banner.md` from the backup
to your new Part-DB instance and overwrite the existing files there.
### Restore attachment files
Copy the `uploads/` and the `public/media/` folder from your backup into your new Part-DB folder.
### Restore database
#### Sqlite
Copy the backup-ed `app.db` into the database folder normally `var/app.db` in Part-DB root folder.
#### MySQL / MariaDB
Recreate a database and user with the same credentials as before (or update the database credentials in the `.env.local` file).
Recreate a database and user with the same credentials as before (or update the database credentials in the `.env.local`
file).
Import the dumped SQL file from the backup into your new database.

25
docs/usage/bom_import.md
View file

@ -7,23 +7,30 @@ parent: Usage
# Import Bill of Material (BOM) for Projects
Part-DB supports the import of Bill of Material (BOM) files for projects. This allows you to directly import a BOM file from your ECAD software into your Part-DB project.
Part-DB supports the import of Bill of Material (BOM) files for projects. This allows you to directly import a BOM file
from your ECAD software into your Part-DB project.
The import process is currently semi-automatic. This means Part-DB will take the BOM file and create entries for all parts in the BOM file in your project and assign fields like
mountnames (e.g. 'C1, C2, C3'), quantity and more.
However, you still have to assign the parts from Part-DB database to the entries (if applicable) after the import by hand,
The import process is currently semi-automatic. This means Part-DB will take the BOM file and create entries for all
parts in the BOM file in your project and assign fields like
mount names (e.g. 'C1, C2, C3'), quantity and more.
However, you still have to assign the parts from Part-DB database to the entries (if applicable) after the import by
hand,
as Part-DB can not know which part you had in mind when you designed your schematic.
## Usage
In the project view or edit click on the "Import BOM" button, below the BOM table. This will open a dialog where you can
select the BOM file you want to import and some options for the import process:
* **Type**: The format/type of the BOM file. See below for explanations of the different types.
* **Clear existing BOM entries before import**: If this is checked, all existing BOM entries, which are currently associated with the project, will be deleted before the import.
* **Clear existing BOM entries before import**: If this is checked, all existing BOM entries, which are currently
associated with the project, will be deleted before the import.
### Supported BOM file formats
* **KiCAD Pcbnew BOM (CSV file)**: A CSV file of the Bill of Material (BOM) generated by [KiCAD Pcbnew](https://www.kicad.org/).
Please note that you have to export the BOM from the PCB editor, the BOM generated by the schematic editor (Eeschema) has a different format and does not work with this type.
You can generate this BOM file by going to "File" -> "Fabrication Outputs" -> "Bill of Materials" in Pcbnew and save the file to your desired location.
* **KiCAD Pcbnew BOM (CSV file)**: A CSV file of the Bill of Material (BOM) generated
by [KiCAD Pcbnew](https://www.kicad.org/).
Please note that you have to export the BOM from the PCB editor, the BOM generated by the schematic editor (Eeschema)
has a different format and does not work with this type.
You can generate this BOM file by going to "File" -> "Fabrication Outputs" -> "Bill of Materials" in Pcbnew and save
the file to your desired location.

41
docs/usage/console_commands.md
View file

@ -10,29 +10,46 @@ Part-DB provides some console commands to display various information or perform
The commands are invoked from the main directory of Part-DB with the command `php bin/console [command]` in the context
of the database user (so usually the webserver user), so you maybe have to use `sudo` or `su` to execute the commands.
You can get help for every command with the parameter `--help`. See `php bin/console` for a list of all available commands.
You can get help for every command with the parameter `--help`. See `php bin/console` for a list of all available
commands.
## User management commands
## User managment commands
* `php bin/console partdb:users:list`: List all users of this Part-DB instance
* `php bin/console partdb:users:set-password [username]`: Set/Changes the password of the user with the given username. This allows administrators to reset a password of a user, if he forgot it.
* `php bin/console partdb:users:enable [username]`: Enable/Disable the user with the given username (use `--disable` to disable the user, which prevents login)
* `php bin/console partdb:users:set-password [username]`: Set/Changes the password of the user with the given username.
This allows administrators to reset a password of a user, if he forgot it.
* `php bin/console partdb:users:enable [username]`: Enable/Disable the user with the given username (use `--disable` to
disable the user, which prevents login)
* `php bin/console partdb:users:permissions`: View/Change the permissions of the user with the given username
* `php bin/console partdb:users:upgrade-permissions-schema`: Upgrade the permissions schema of users to the latest version (this is normally automatically done when the user visits a page)
* `php bin/console partdb:users:upgrade-permissions-schema`: Upgrade the permissions schema of users to the latest
version (this is normally automatically done when the user visits a page)
* `php bin/console partdb:logs:show`: Show the most recent entries of the Part-DB event log / recent activity
* `php bin/console partdb:user:convert-to-saml-user`: Convert a local user to a SAML/SSO user. This is needed, if you want to use SAML/SSO authentication for a user, which was created before you enabled SAML/SSO authentication.
* `php bin/console partdb:user:convert-to-saml-user`: Convert a local user to a SAML/SSO user. This is needed, if you
want to use SAML/SSO authentication for a user, which was created before you enabled SAML/SSO authentication.
## Currency commands
* `php bin/console partdb:currencies:update-exchange-rates`: Update the exchange rates of all currencies from the internet)
* `php bin/console partdb:currencies:update-exchange-rates`: Update the exchange rates of all currencies from the
internet
## Installation/Maintenance commands
* `php bin/console partdb:backup`: Backup the database and the attachments
* `php bin/console partdb:version`: Display the current version of Part-DB and the used PHP version
* `php bin/console partdb:check-requirements`: Check if the requirements for Part-DB are met (PHP version, PHP extensions, etc.) and make suggestions what could be improved
* `partdb:migrations:convert-bbcode`: Migrate the old BBCode markup codes used in legacy Part-DB versions (< 1.0.0) to the new markdown syntax
* `partdb:attachments:clean-unused`: Remove all attachments which are not used by any database entry (e.g. orphaned attachments)
* `partdb:cache:clear`: Clears all caches, so the next page load will be slower, but the cache will be rebuild. This can maybe fix some issues, when the cache were corrupted. This command is also needed after changing things in the `parameters.yaml` file or upgrading Part-DB.
* `partdb:migrations:import-partkeepr`: Imports an mysqldump XML dump of a PartKeepr database into Part-DB. This is only needed for users, which want to migrate from PartKeepr to Part-DB. *All existing data in the Part-DB database is deleted!*
* `php bin/console partdb:check-requirements`: Check if the requirements for Part-DB are met (PHP version, PHP
extensions, etc.) and make suggestions what could be improved
* `partdb:migrations:convert-bbcode`: Migrate the old BBCode markup codes used in legacy Part-DB versions (< 1.0.0) to
the new Markdown syntax
* `partdb:attachments:clean-unused`: Remove all attachments which are not used by any database entry (e.g. orphaned
attachments)
* `partdb:cache:clear`: Clears all caches, so the next page load will be slower, but the cache will be rebuilt. This can
maybe fix some issues, when the cache were corrupted. This command is also needed after changing things in
the `parameters.yaml` file or upgrading Part-DB.
* `partdb:migrations:import-partkeepr`: Imports a mysqldump XML dump of a PartKeepr database into Part-DB. This is only
needed for users, which want to migrate from PartKeepr to Part-DB. *All existing data in the Part-DB database is
deleted!*
## Database commands
* `php bin/console doctrine:migrations:migrate`: Migrate the database to the latest version
* `php bin/console doctrine:migrations:up-to-date`: Check if the database is up-to-date

133
docs/usage/getting_started.md
View file

@ -7,111 +7,146 @@ 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]({% link concepts.md %}).
Before starting, it's useful to read a bit about the [concepts of Part-DB]({% link concepts.md %}).
1. TOC
{:toc}
## Customize config files
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.
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]({% link configuration.md %}).
## Change password, Set up Two-Factor-Authentication & Customize User settings
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).
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).
![image]({% link assets/getting_started/change_password.png %})
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)
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 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.
![image]({% link assets/getting_started/user_settings.png %})
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.
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.
## (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$$
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
### Users
When logged in as administrator, you can open the users menu in the `Tools` section of the sidebar under `System -> 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.
For each user which should use Part-DB you should set up an own account, so that tracking of what user did what works
properly.
![image]({% link assets/getting_started/user_admin.png %})
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)
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)
![image]({% link assets/getting_started/user_permissions.png %})
### Anonymous user
The `anonymous` user is special, as its settings and permissions are used for everybody who is not logged in. By default the anonymous user has read capabilities for your parts. If your Part-DB instance is publicly available you maybe want to restrict the permissions.
The `anonymous` user is special, as its settings and permissions are used for everybody who is not logged in. By default,
the anonymous user has read capabilities for your parts. If your Part-DB instance is publicly available you maybe want
to restrict the permissions.
### Groups
If you have many users which should share the same permissions, it is useful to define the permissions using user groups, which you can create and edit in the `System -> Groups` menu.
If you have many users which should share the same permissions, it is useful to define the permissions using user
groups, which you can create and edit in the `System -> Groups` menu.
By default 3 groups are defined:
* `readonly` which users have only have read permissions (like viewing, searching parts, attachments, etc.)
* `readonly` which users only have read permissions (like viewing, searching parts, attachments, etc.)
* `users` which users also have rights to edit/delete/create elements
* `admin` which users can do administrative operations (like creating new users, show global system log, etc.)
Users only use the setting of a capability from a group, if the user has a group associated and the capability on the user is set to `inherit` (which is the default if creating a new user). You can override the permissions settings of a group per user by explicitly settings the permission at the user.
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.
Users only use the setting of a capability from a group, if the user has a group associated and the capability on the
user is set to `inherit` (which is the default if creating a new user). You can override the permissions settings of a
group per user by explicitly settings the permission at the user.
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.
## Create Attachment types
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.
Every attachment (that is a 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":
![image]({% link assets/getting_started/attachment_type_admin.png %})
Depending on your usecase different entries here make sense. For part mananagment the following (additional) entries maybe make sense:
Depending on your use case different entries here make sense. For part management the following (additional) entries
maybe make sense:
* Datasheets (restricted to pdfs, Allowed filetypes: `application/pdf`)
* Pictures (for generic pictures of components, storage locations, etc., Allowed filetypes: `image/*`
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.
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.
## (Optional) Create Currencies
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`:
If you want to save price information 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`:
![image]({% link assets/getting_started/currencies_admin.png %})
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.
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 an exchange rate in terms of your base currency (e.g. how many euros is one unit of your currency worth)
to convert the currencies values in your preferred display currency automatically.
## (Optional) Create 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.
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 the stock 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`:
![image]({% link assets/getting_started/units_admin.png %})
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).
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.
The measurement unit can be selected for each part individually, by setting the option in the advanced tab of a part`s
edit menu.
## Create Categories
A category is used to group parts logically by their function (e.g. all NPN transistors would be put in a "NPN-Transistors" category).
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.
@ -121,43 +156,51 @@ Every part has to be assigned to a category, so you should create at least one c
## (Optional) Create Footprints
Footprints are used to describe the physical shape of a part, like a resistor or a capacitor.
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.
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.
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.
A storage location 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".
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 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:
![image]({% link assets/getting_started/new_part.png %})
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.
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.
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.

130
docs/usage/import_export.md
View file

@ -7,50 +7,81 @@ parent: Usage
# Import & Export data
Part-DB offers the possibility to import existing data (parts, datastructures, etc.) from existing datasources into Part-DB. Data can also be exported from Part-DB into various formats.
Part-DB offers the possibility to import existing data (parts, datastructures, etc.) from existing data sources into
Part-DB. Data can also be exported from Part-DB into various formats.
## Import
{: .note }
> As data import is a very powerful feature and can easily fill up your database with lots of data, import is by default only available for
> administrators. If you want to allow other users to import data, or can not import data, check the permissions of the user. You can enable import for each data structure
> As data import is a very powerful feature and can easily fill up your database with lots of data, import is by default
> only available for
> administrators. If you want to allow other users to import data, or can not import data, check the permissions of the
> user. You can enable import for each data structure
> individually in the permissions settings.
If you want to import data from PartKeepr you might want to look into the [PartKeepr migration guide]({% link upgrade_legacy.md %}).
If you want to import data from PartKeepr you might want to look into the [PartKeepr migration guide]({% link
upgrade_legacy.md %}).
### Import parts
Part-DB supports the import of parts from CSV files and other formats. This can be used to import existing parts from other databases or datasources into Part-DB. The import can be done via the "Tools -> Import parts" page, which you can find in the "Tools" sidebar panel.
Part-DB supports the import of parts from CSV files and other formats. This can be used to import existing parts from
other databases or data sources into Part-DB. The import can be done via the "Tools -> Import parts" page, which you can
find in the "Tools" sidebar panel.
{: .important }
> When importing data, the data is immediatley written to database during the import process, when the data is formally valid.
> You will not be able to check the data before it is written to the database, so you should review the data before using the import tool.
> When importing data, the data is immediately written to database during the import process, when the data is formally
> valid.
> You will not be able to check the data before it is written to the database, so you should review the data before
> using the import tool.
You can upload the file which should be imported here and choose various options on how the data should be treated:
* **Format**: By default "auto" is selected here and Part-DB will try to detect the format of the file automatically based on its file extension. If you want to force a specific format or Part-DB can not auto-detect the format, you can select it here.
* **CSV delimiter**: If you upload an CSV file, you can select the delimiter character which is used to separate the columns in the CSV file. Depending on the CSV file, this might be a comma (`,`), semicolon (`;`).
* **Category override**: You can select (or create) a category here, to which all imported parts should be assigned, no matter what was specified in the import file. This can be useful if you want to assign all imports to a certain category or if no category is specified in the data. If you leave this field empty, the category will be determined by the import file (or the export will error, if no category is specified).
* **Mark all imported parts as "Needs review"**: If this is selected, all imported parts will be marked as "Needs review" after the import. This can be useful if you want to review all imported parts before using them.
* **Create unknown datastructures**: If this is selected Part-DB will create new datastructures (like categories, manufacturers, etc.) if no datastructure(s) with the same name and path already exists. If this is not selected, only existing datastructures will be used and if no matching datastrucure is found, the imported parts field will be empty.
* **Path delimiter**: Part-DB allows you to create/select nested datastructures (like categories, manufacturers, etc.) by using a path (e.g. `Category 1->Category 1.1`, which will select/create the `Category 1.1` whose parent is `Category 1`). This path is separated by the path delimiter. If you want to use a different path delimiter than the default one (which is `>`), you can select it here.
* **Abort on validation error**: If this is selected, the import will be aborted if a validation error occurs (e.g. if a required field is empty) for any of the imported parts and validation errors will be shown on top of the page. If this is not selected, the import will continue for the other parts and only the invalid parts will be skipped.
After you have selected the options, you can start the import by clicking the "Import" button. When the import is finished, you will see the results of the import in the lower half of the page. You find a table with the imported parts (including links to them) there.
* **Format**: By default "auto" is selected here and Part-DB will try to detect the format of the file automatically
based on its file extension. If you want to force a specific format or Part-DB can not auto-detect the format, you can
select it here.
* **CSV delimiter**: If you upload an CSV file, you can select the delimiter character which is used to separate the
columns in the CSV file. Depending on the CSV file, this might be a comma (`,`), semicolon (`;`).
* **Category override**: You can select (or create) a category here, to which all imported parts should be assigned, no
matter what was specified in the import file. This can be useful if you want to assign all imports to a certain
category or if no category is specified in the data. If you leave this field empty, the category will be determined by
the import file (or the export will error, if no category is specified).
* **Mark all imported parts as "Needs review"**: If this is selected, all imported parts will be marked as "Needs
review" after the import. This can be useful if you want to review all imported parts before using them.
* **Create unknown datastructures**: If this is selected Part-DB will create new datastructures (like categories,
manufacturers, etc.) if no datastructure(s) with the same name and path already exists. If this is not selected, only
existing datastructures will be used and if no matching datastrucure is found, the imported parts field will be empty.
* **Path delimiter**: Part-DB allows you to create/select nested datastructures (like categories, manufacturers, etc.)
by using a path (e.g. `Category 1->Category 1.1`, which will select/create the `Category 1.1` whose parent
is `Category 1`). This path is separated by the path delimiter. If you want to use a different path delimiter than the
default one (which is `>`), you can select it here.
* **Abort on validation error**: If this is selected, the import will be aborted if a validation error occurs (e.g. if a
required field is empty) for any of the imported parts and validation errors will be shown on top of the page. If this
is not selected, the import will continue for the other parts and only the invalid parts will be skipped.
After you have selected the options, you can start the import by clicking the "Import" button. When the import is
finished, you will see the results of the import in the lower half of the page. You find a table with the imported
parts (including links to them) there.
#### Fields description
For the importing of parts, you can use the following fields which will be imported into each part. Please note that the field names are case sensitive (so `name` is not the same as `Name`). All fields (besides name) are optional, so you can leave them empty or do not include the column in your file.
For the importing of parts, you can use the following fields which will be imported into each part. Please note that the
field names are case-sensitive (so `name` is not the same as `Name`). All fields (besides name) are optional, so you can
leave them empty or do not include the column in your file.
* **`name`** (required): The name of the part. This is the only required field, all other fields are optional.
* **`description`**: The description of the part, you can use markdown/HTML syntax here for rich text formatting.
* **`notes`** or **`comment`**: The notes of the part, you can use markdown/HTML syntax here for rich text formatting.
* **`category`**: The category of the part. This can be a path (e.g. `Category 1->Category 1.1`), which will select/create the `Category 1.1` whose parent is `Category 1`. If you want to use a different path delimiter than the default one (which is `->`), you can select it in the import options. If the category does not exist and the option "Create unknown datastructures" is selected, it will be created.
* **`category`**: The category of the part. This can be a path (e.g. `Category 1->Category 1.1`), which will
select/create the `Category 1.1` whose parent is `Category 1`. If you want to use a different path delimiter than the
default one (which is `->`), you can select it in the import options. If the category does not exist and the option "
Create unknown datastructures" is selected, it will be created.
* **`footprint`**: The footprint of the part. Can be a path similar to the category field.
* **`favorite`**: If this is set to `1`, the part will be marked as favorite.
* **`manufacturer`**: The manufacturer of the part. Can be a path similar to the category field.
* **`manufacturer_product_number`** or **`mpn`**: The manufacturer product number of the part.
* **`manufacturer_product_url`: The URL to the product page of the manufacturer of the part.
* **`manufacturing_status`**: The manufacturing status of the part, must be one of the following values: `announced`, `active`, `nrfnd`, `eol`, `discontinued` or left empty.
* **`manufacturing_status`**: The manufacturing status of the part, must be one of the following
values: `announced`, `active`, `nrfnd`, `eol`, `discontinued` or left empty.
* **`needs_review`** or **`needs_review`**: If this is set to `1`, the part will be marked as "needs review".
* **`tags`**: A comma separated list of tags for the part.
* **`mass`**: The mass of the part in grams.
@ -58,46 +89,73 @@ For the importing of parts, you can use the following fields which will be impor
* **`minamount`**: The minimum amount of the part which should be in stock.
* **`partUnit`**: The measurement unit of the part to use. Can be a path similar to the category field.
With the following fields you can specify storage locations and amount / quantiy in stock of the part. An PartLot will be created automatically from the data and assigned to the part. The following fields are helpers for an easy import for parts at one storage location. If you need to create a Part with multiple PartLots you have to use JSON format (or CSV) with nested objects:
With the following fields you can specify storage locations and amount / quantity in stock of the part. An PartLot will
be created automatically from the data and assigned to the part. The following fields are helpers for an easy import for
parts at one storage location. If you need to create a Part with multiple PartLots you have to use JSON format (or CSV)
with nested objects:
**`storage_location`** or **`storelocation`**: The storage location of the part. Can be a path similar to the category field.
**`amount`**, **`quantity`** or **`instock`**: The amount of the part in stock. If this value is not set, the part lot will be marked with "unknown amount"
**`storage_location`** or **`storelocation`**: The storage location of the part. Can be a path similar to the category
field.
**`amount`**, **`quantity`** or **`instock`**: The amount of the part in stock. If this value is not set, the part lot
will be marked with "unknown amount"
The following fields can be used to specify the supplier/distributor, supplier product number and the price of the part. This is only possible for a single supplier/distributor and price with this fields. If you need to specify multiple suppliers/distributors or prices, you have to use JSON format (or CSV) with nested objects.
**Please note that the supplier fields is required, if you want to import prices or supplier product numbers.**. If the supplier is not specified, the price and supplier product number fields will be ignored:
The following fields can be used to specify the supplier/distributor, supplier product number and the price of the part.
This is only possible for a single supplier/distributor and price with these fields. If you need to specify multiple
suppliers/distributors or prices, you have to use JSON format (or CSV) with nested objects.
**Please note that the supplier fields is required, if you want to import prices or supplier product numbers**. If the
supplier is not specified, the price and supplier product number fields will be ignored:
* **`supplier`**: The supplier of the part. Can be a path similar to the category field.
* **`supplier_product_number`** or **`supplier_part_number`** or * **`spn`**: The supplier product number of the part.
* **`price`**: The price of the part in the base currency of the database (by default euro).
#### Example data
Here you can find some example data for the import of parts, you can use it as a template for your own import (especially the CSV file).
Here you can find some example data for the import of parts, you can use it as a template for your own import (
especially the CSV file).
* [Part import CSV example]({% link assets/usage/import_export/part_import_example.csv %}) with all possible fields
## Export
By default every user, who can read the datastructure, can also export the data of this datastructure, as this does not give the user any additional information.
By default, every user, who can read the datastructure, can also export the data of this datastructure, as this does not
give the user any additional information.
### Exporting data structures (categories, manufacturers, etc.)
You can export data structures (like categories, manufacturers, etc.) in the respective edit page (e.g. Tools Panel -> Edit -> Category).
If you select a certain datastructure from your list, you can export it (and optionally all sub-datastructures) in the "Export" tab.
If you want to export all datastructures of a certain type (e.g. all categories in your database), you can select the "Export all" function in the "Import / Export" tab of the "new element" page.
You can export data structures (like categories, manufacturers, etc.) in the respective edit page (e.g. Tools Panel ->
Edit -> Category).
If you select a certain datastructure from your list, you can export it (and optionally all sub-datastructures) in the "
Export" tab.
If you want to export all datastructures of a certain type (e.g. all categories in your database), you can select the "
Export all" function in the "Import / Export" tab of the "new element" page.
You can select between the following export formats:
* **CSV** (Comma Separated Values): A semicolon separated list of values, where every line represents an element. This format can be imported into Excel or LibreOffice Calc and is easy to work with. However it does not support nested datastructures or sub data (like parameters, attachments, etc.), very well (many columns are generated, as every possible sub data is exported as a separate column).
* **JSON** (JavaScript Object Notation): A text-based format, which is easy to work with programming laguages. It supports nested datastructures and sub data (like parameters, attachments, etc.) very well. However it is not easy to work with in Excel or LibreOffice Calc and you maybe need to write some code to work with the exported data efficiently.
* **YAML** (Yet another Markup Language): Very similar to JSON
* **XML** (Extensible Markup Language): Good support with nested datastructures. Similar usecase as JSON and YAML.
Also you can select between the following export levels:
* **CSV** (Comma Separated Values): A semicolon separated list of values, where every line represents an element. This
format can be imported into Excel or LibreOffice Calc and is easy to work with. However, it does not support nested
datastructures or sub data (like parameters, attachments, etc.), very well (many columns are generated, as every
possible sub data is exported as a separate column).
* **JSON** (JavaScript Object Notation): A text-based format, which is easy to work with programming languages. It
supports nested datastructures and sub data (like parameters, attachments, etc.) very well. However, it is not easy to
work with in Excel or LibreOffice Calc and you maybe need to write some code to work with the exported data
efficiently.
* **YAML** (Yet another Markup Language): Very similar to JSON
* **XML** (Extensible Markup Language): Good support with nested datastructures. Similar use case as JSON and YAML.
Also, you can select between the following export levels:
* **Simple**: This will only export very basic information about the name (like the name, or description for parts)
* **Extended**: This will export all commonly used information about this datastructure (like notes, options, etc)
* **Extended**: This will export all commonly used information about this datastructure (like notes, options, etc.)
* **Full**: This will export all available information about this datastructure (like all parameters, attachments)
Please note that the level will also be applied to all sub data or children elements. So if you select "Full" for a part, all the associated categories, manufacturers, footprints, etc. will also be exported with all available information, this can lead to very large export files.
Please note that the level will also be applied to all sub data or children elements. So if you select "Full" for a
part, all the associated categories, manufacturers, footprints, etc. will also be exported with all available
information, this can lead to very large export files.
### Exporting parts
You can export parts in all part tables. Select the parts you want via the checkbox in the table line and select the export format and level in the appearing menu.
You can export parts in all part tables. Select the parts you want via the checkbox in the table line and select the
export format and level in the appearing menu.
See the section about exporting datastructures for more information about the export formats and levels.

177
docs/usage/information_provider_system.md
View file

@ -6,149 +6,208 @@ parent: Usage
# Information provider system
Part-DB can create parts based on information from external sources: For example with the right setup you can just search for a part number
and Part-DB will query selected distributors and manufacturers for the part and create a part with the information it found.
Part-DB can create parts based on information from external sources: For example with the right setup you can just
search for a part number
and Part-DB will query selected distributors and manufacturers for the part and create a part with the information it
found.
This way your Part-DB parts automatically get datasheet links, prices, parameters and more, with just a few clicks.
## Usage
Before you can use the information provider system, you have to configure at least one information provider, which act as data source.
Before you can use the information provider system, you have to configure at least one information provider, which act
as data source.
See below for a list of available information providers and available configuration options.
For many providers it is enough, to setup the API keys in the env configuration, some require an additional OAuth connection.
You can list all enabled information providers in the browser at `https://your-partdb-instance.tld/tools/info_providers/providers` (you need the right permission for it, see below).
For many providers it is enough, to set up the API keys in the env configuration, some require an additional OAuth
connection.
You can list all enabled information providers in the browser
at `https://your-partdb-instance.tld/tools/info_providers/providers` (you need the right permission for it, see below).
To use the information provider system, your user need to have the right permissions. Go to the permission management page of
To use the information provider system, your user need to have the right permissions. Go to the permission management
page of
a user or a group and assign the permissions of the "Info providers" group in the "Miscellaneous" tab.
If you have the required permission you will find in the sidebar in the "Tools" section the entry "Create part from info provider".
Click this and you will land on a search page. Enter the part number you want to search for and select the information providers you want to use.
If you have the required permission you will find in the sidebar in the "Tools" section the entry "Create part from info
provider".
Click this and you will land on a search page. Enter the part number you want to search for and select the information
providers you want to use.
After you click Search, you will be presented with the results and can select the result that fits best.
With a click on the blue plus button, you will be redirected to the part creation page with the information already filled in.
After you click Search, you will be presented with the results and can select the result that fits best.
With a click on the blue plus button, you will be redirected to the part creation page with the information already
filled in.
![image]({% link assets/usage/information_provider_system/animation.gif %})
## Alternative names
Part-DB tries to automatically find existing elements from your database for the information it got from the providers for fields like manufacturer, footprint, etc.
For this it searches for a element with the same name (case-insensitive) as the information it got from the provider. So e.g. if the provider returns "EXAMPLE CORP" as manufacturer,
Part-DB tries to automatically find existing elements from your database for the information it got from the providers
for fields like manufacturer, footprint, etc.
For this it searches for an element with the same name (case-insensitive) as the information it got from the provider. So
e.g. if the provider returns "EXAMPLE CORP" as manufacturer,
Part-DB will automatically select the element with the name "Example Corp" from your database.
As the names of these fields differ from provider to provider (and maybe not even normalized for the same provider), you
As the names of these fields differ from provider to provider (and maybe not even normalized for the same provider), you
can define multiple alternative names for an element (on their editing page).
For example if define a manufacturer "Example Corp" with the alternative names "Example Corp.", "Example Corp", "Example Corp. Inc." and "Example Corporation",
For example if define a manufacturer "Example Corp" with the alternative names "Example Corp.", "Example Corp", "Example
Corp. Inc." and "Example Corporation",
then the provider can return any of these names and Part-DB will still automatically select the right element.
If Part-DB finds no matching element, it will automatically create a new one, when you do not change the value before saving.
If Part-DB finds no matching element, it will automatically create a new one, when you do not change the value before
saving.
## Attachment types
The information provider system uses attachment types to differentiate between datasheets and image attachments.
For this it will create a "Datasheet" and "Image" attachment type on the first run. You can change the names of these
For this it will create a "Datasheet" and "Image" attachment type on the first run. You can change the names of these
types in the attachment type settings (as long as you keep the "Datasheet"/"Image" in the alternative names field).
If you already have attachment types for images and datasheets and want the information provider system to use them, you can
If you already have attachment types for images and datasheets and want the information provider system to use them, you
can
add the alternative names "Datasheet" and "Image" to the alternative names field of the attachment types.
## Data providers
The system tries to be as flexible as possible, so many different information sources can be used.
Each information source is called am "info provider" and handles the communication with the external source.
The providers are just a driver which handles the communication with the different external sources and converts them into a common format Part-DB understands.
The providers are just a driver which handles the communication with the different external sources and converts them
into a common format Part-DB understands.
That way it is pretty easy to create new providers as they just need to do very little work.
Normally the providers utilize an API of a service, and you need to create a account at the provider and get an API key.
Also there are limits on how many requests you can do per day or months, depending on the provider and your contract with them.
Normally the providers utilize an API of a service, and you need to create an account at the provider and get an API key.
Also, there are limits on how many requests you can do per day or months, depending on the provider and your contract
with them.
The following providers are currently available and shipped with Part-DB:
(All trademarks are property of their respective owners. Part-DB is not affiliated with any of the companies.)
### Ocotpart
The Octopart provider uses the [Octopart / Nexar API](https://nexar.com/api) to search for parts and getting informations.
To use it you have to create an account at Nexar and create a new application on the [Nexar Portal](https://portal.nexar.com/).
The name does not matter, but it is important that the application has access to the "Supply" scope.
In the Authorization tab, you will find the client ID and client secret, which you have to enter in the Part-DB env configuration (see below).
### Octopart
Please note that the Nexar API in the free plan is limited to 1000 results per month.
That means if you search for a keyword and results in 10 parts, then 10 will be substracted from your monthly limit. You can see your current usage on the Nexar portal.
Part-DB caches the search results internally, so if you have searched for a part before, it will not count against your monthly limit again, when you create it from the search results.
The Octopart provider uses the [Octopart / Nexar API](https://nexar.com/api) to search for parts and getting
information.
To use it you have to create an account at Nexar and create a new application on
the [Nexar Portal](https://portal.nexar.com/).
The name does not matter, but it is important that the application has access to the "Supply" scope.
In the Authorization tab, you will find the client ID and client secret, which you have to put in the Part-DB env
configuration (see below).
Please note that the Nexar API in the free plan is limited to 1000 results per month.
That means if you search for a keyword and results in 10 parts, then 10 will be subtracted from your monthly limit. You
can see your current usage on the Nexar portal.
Part-DB caches the search results internally, so if you have searched for a part before, it will not count against your
monthly limit again, when you create it from the search results.
Following env configuration options are available:
* `PROVIDER_OCTOPART_CLIENT_ID`: The client ID you got from Nexar (mandatory)
* `PROVIDER_OCTOPART_SECRET`: The client secret you got from Nexar (mandatory)
* `PROVIDER_OCTOPART_CURRENCY`: The currency you want to get prices in if available (optional, 3 letter ISO-code, default: `EUR`). If an offer is only available in a certain currency,
Part-DB will save the prices in their native currency, and you can use Part-DB currency conversion feature to convert it to your preferred currency.
* `PROVIDER_OCOTPART_COUNTRY`: The country you want to get prices in if available (optional, 2 letter ISO-code, default: `DE`). To get correct prices, you have to set this and the currency setting to the correct value.
* `PROVIDER_OCTOPART_SEARCH_LIMIT`: The maximum number of results to return per search (optional, default: `10`). This affects how quickly your monthly limit is used up.
* `PROVIDER_OCTOPART_ONLY_AUTHORIZED_SELLERS`: If set to `true`, only offers from [authorized sellers](https://octopart.com/authorized) will be returned (optional, default: `false`).
* `PROVIDER_OCTOPART_CURRENCY`: The currency you want to get prices in if available (optional, 3 letter ISO-code,
default: `EUR`). If an offer is only available in a certain currency,
Part-DB will save the prices in their native currency, and you can use Part-DB currency conversion feature to convert
it to your preferred currency.
* `PROVIDER_OCOTPART_COUNTRY`: The country you want to get prices in if available (optional, 2 letter ISO-code,
default: `DE`). To get correct prices, you have to set this and the currency setting to the correct value.
* `PROVIDER_OCTOPART_SEARCH_LIMIT`: The maximum number of results to return per search (optional, default: `10`). This
affects how quickly your monthly limit is used up.
* `PROVIDER_OCTOPART_ONLY_AUTHORIZED_SELLERS`: If set to `true`, only offers
from [authorized sellers](https://octopart.com/authorized) will be returned (optional, default: `false`).
**Attention**: If you change the octopart clientID after you have already used the provider, you have to remove the OAuth token in the Part-DB database. Remove the entry in the table `oauth_tokens` with the name `ip_octopart_oauth`.
**Attention**: If you change the octopart clientID after you have already used the provider, you have to remove the
OAuth token in the Part-DB database. Remove the entry in the table `oauth_tokens` with the name `ip_octopart_oauth`.
### Digi-Key
The Digi-Key provider uses the [Digi-Key API](https://developer.digikey.com/) to search for parts and getting shopping information from [Digi-Key](https://www.digikey.com/).
To use it you have to create an account at Digi-Key and get an API key on the [Digi-Key API page](https://developer.digikey.com/).
You must create an organization there and create a "Production app". Most settings are not important, you just have to grant access to the "Product Information" API.
You will get an Client ID and a Client Secret, which you have to enter in the Part-DB env configuration (see below).
The Digi-Key provider uses the [Digi-Key API](https://developer.digikey.com/) to search for parts and getting shopping
information from [Digi-Key](https://www.digikey.com/).
To use it you have to create an account at Digi-Key and get an API key on
the [Digi-Key API page](https://developer.digikey.com/).
You must create an organization there and create a "Production app". Most settings are not important, you just have to
grant access to the "Product Information" API.
You will get a Client ID and a Client Secret, which you have to put in the Part-DB env configuration (see below).
Following env configuration options are available:
* `PROVIDER_DIGIKEY_CLIENT_ID`: The client ID you got from Digi-Key (mandatory)
* `PROVIDER_DIGIKEY_SECRET`: The client secret you got from Digi-Key (mandatory)
* `PROVIDER_DIGIKEY_CURRENCY`: The currency you want to get prices in (optional, default: `EUR`)
* `PROVIDER_DIGIKEY_LANGUAGE`: The language you want to get the descriptions in (optional, default: `en`)
* `PROVIDER_DIGIKEY_COUNTRY`: The country you want to get the prices for (optional, default: `DE`)
The Digi-Key provider needs an additional OAuth connection. To do this, go to the information provider list (`https://your-partdb-instance.tld/tools/info_providers/providers`),
go the Digi-Key provider (in the disabled page) and click on the "Connect OAuth" button. You will be redirected to Digi-Key, where you have to login and grant access to the app.
The Digi-Key provider needs an additional OAuth connection. To do this, go to the information provider
list (`https://your-partdb-instance.tld/tools/info_providers/providers`),
go the Digi-Key provider (in the disabled page) and click on the "Connect OAuth" button. You will be redirected to
Digi-Key, where you have to log in and grant access to the app.
To do this your user needs the "Manage OAuth tokens" permission from the "System" section in the "System" tab.
The OAuth connection should only be needed once, but if you have any problems with the provider, just click the button again, to establish a new connection.
The OAuth connection should only be needed once, but if you have any problems with the provider, just click the button
again, to establish a new connection.
### TME
The TME provider use the API of [TME](https://www.tme.eu/) to search for parts and getting shopping information from them.
The TME provider use the API of [TME](https://www.tme.eu/) to search for parts and getting shopping information from
them.
To use it you have to create an account at TME and get an API key on the [TME API page](https://developers.tme.eu/en/).
You have to generate a new anonymous key there and enter the key and secret in the Part-DB env configuration (see below).
You have to generate a new anonymous key there and enter the key and secret in the Part-DB env configuration (see
below).
Following env configuration options are available:
* `PROVIDER_TME_KEY`: The API key you got from TME (mandatory)
* `PROVIDER_TME_KEY`: The API key you got from TME (mandatory)
* `PROVIDER_TME_SECRET`: The API secret you got from TME (mandatory)
* `PROVIDER_TME_CURRENCY`: The currency you want to get prices in (optional, default: `EUR`)
* `PROVIDER_TME_LANGUAGE`: The language you want to get the descriptions in (`en`, `de` and `pl`) (optional, default: `en`)
* `PROVIDER_TME_LANGUAGE`: The language you want to get the descriptions in (`en`, `de` and `pl`) (optional,
default: `en`)
* `PROVIDER_TME_COUNTRY`: The country you want to get the prices for (optional, default: `DE`)
* `PROVIDER_TME_GET_GROSS_PRICES`: If this is set to `1` the prices will be gross prices (including tax), otherwise net prices (optional, default: `0`)
* `PROVIDER_TME_GET_GROSS_PRICES`: If this is set to `1` the prices will be gross prices (including tax), otherwise net
prices (optional, default: `0`)
### Farnell / Element14 / Newark
The Farnell provider uses the [Farnell API](https://partner.element14.com/) to search for parts and getting shopping information from [Farnell](https://www.farnell.com/).
You have to create an account at Farnell and get an API key on the [Farnell API page](https://partner.element14.com/).
Register a new application there (settings does not matter, as long as you select the "Product Search API") and you will get an API key.
The Farnell provider uses the [Farnell API](https://partner.element14.com/) to search for parts and getting shopping
information from [Farnell](https://www.farnell.com/).
You have to create an account at Farnell and get an API key on the [Farnell API page](https://partner.element14.com/).
Register a new application there (settings does not matter, as long as you select the "Product Search API") and you will
get an API key.
Following env configuration options are available:
* `PROVIDER_ELEMENT14_KEY`: The API key you got from Farnell (mandatory)
* `PROVIDER_ELEMENT14_STORE_ID`: The store ID you want to use. This decides the language of results, currency and country of prices (optional, default: `de.farnell.com`, see [here](https://partner.element14.com/docs/Product_Search_API_REST__Description) for availailable values)
* `PROVIDER_ELEMENT14_STORE_ID`: The store ID you want to use. This decides the language of results, currency and
country of prices (optional, default: `de.farnell.com`,
see [here](https://partner.element14.com/docs/Product_Search_API_REST__Description) for available values)
### Mouser
The Mouser provider uses the [Mouser API](https://www.mouser.de/api-home/) to search for parts and getting shopping information from [Mouser](https://www.mouser.com/).
You have to create an account at Mouser and register for an API key for the Search API on the [Mouser API page](https://www.mouser.de/api-home/).
You will receive an API token, which you have to enter in the Part-DB env configuration (see below):
The Mouser provider uses the [Mouser API](https://www.mouser.de/api-home/) to search for parts and getting shopping
information from [Mouser](https://www.mouser.com/).
You have to create an account at Mouser and register for an API key for the Search API on
the [Mouser API page](https://www.mouser.de/api-home/).
You will receive an API token, which you have to put in the Part-DB env configuration (see below):
At the registration you choose a country, language and currency in which you want to get the results.
Following env configuration options are available:
* `PROVIDER_MOUSER_KEY`: The API key you got from Mouser (mandatory)
* `PROVIDER_MOUSER_SEARCH_LIMIT`: The maximum number of results to return per search (maximum 50)
* `PROVIDER_MOUSER_SEARCH_OPTION`: You can choose an option here to restrict the search results to RoHs compliant and available parts. Possible values are `None`, `Rohs`, `InStock`, `RohsAndInStock`.
* `PROVIDER_MOUSER_SEARCH_WITH_SIGNUP_LANGUAGE`: A bit of an obscure option. The original description of Mouser is: Used when searching for keywords in the language specified when you signed up for Search API.
* `PROVIDER_MOUSER_SEARCH_OPTION`: You can choose an option here to restrict the search results to RoHs compliant and
available parts. Possible values are `None`, `Rohs`, `InStock`, `RohsAndInStock`.
* `PROVIDER_MOUSER_SEARCH_WITH_SIGNUP_LANGUAGE`: A bit of an obscure option. The original description of Mouser is: Used
when searching for keywords in the language specified when you signed up for Search API.
### Custom provider
To create a custom provider, you have to create a new class implementing the `InfoProviderInterface` interface. As long as it is a valid Symfony service, it will be automatically loaded and can be used.
Besides some metadata functions, you have to implement the `searchByKeyword()` and `getDetails()` functions, which do the actual API requests and return the information to Part-DB.
To create a custom provider, you have to create a new class implementing the `InfoProviderInterface` interface. As long
as it is a valid Symfony service, it will be automatically loaded and can be used.
Besides some metadata functions, you have to implement the `searchByKeyword()` and `getDetails()` functions, which do
the actual API requests and return the information to Part-DB.
See the existing providers for examples.
If you created a new provider, feel free to create a pull request to add it to the Part-DB core.
## Result caching
To reduce the number of API calls against the providers, the results are cached:
* The search results (exact search term) are cached for 7 days
* The product details are cached for 4 days
If you need a fresh result, you can clear the cache by running `php .\bin\console cache:pool:clear info_provider.cache` on the command line.
If you need a fresh result, you can clear the cache by running `php .\bin\console cache:pool:clear info_provider.cache`
on the command line.
The default `php bin/console cache:clear` also clears the result cache, as it clears all caches.

163
docs/usage/keybindings.md
View file

@ -9,104 +9,107 @@ parent: Usage
This page lists all the keybindings of Part-DB. Currently, there are only the special character keybindings.
## Special characters
Using the keybindings below (Alt + key) you can insert special characters into the text fields of Part-DB. This works on all text and search fields in Part-DB.
Using the keybindings below (Alt + key) you can insert special characters into the text fields of Part-DB. This works on
all text and search fields in Part-DB.
### Greek letters
| Key | Character |
|---------------------|---------------------|
| **Alt + a** | α (Alpha) |
| **Alt + Shift + A** | Α (Alpha uppercase) |
| **Alt + b** | β (Beta) |
| **Alt + Shift + B** | Β (Beta uppercase) |
| **Alt + g** | γ (Gamma) |
| **Alt + Shift + G** | Γ (Gamma uppercase) |
| **Alt + d** | δ (Delta) |
| **Alt + Shift + D** | Δ (Delta uppercase) |
| **Alt + e** | ε (Epsilon) |
| Key | Character |
|---------------------|-----------------------|
| **Alt + a** | α (Alpha) |
| **Alt + Shift + A** | Α (Alpha uppercase) |
| **Alt + b** | β (Beta) |
| **Alt + Shift + B** | Β (Beta uppercase) |
| **Alt + g** | γ (Gamma) |
| **Alt + Shift + G** | Γ (Gamma uppercase) |
| **Alt + d** | δ (Delta) |
| **Alt + Shift + D** | Δ (Delta uppercase) |
| **Alt + e** | ε (Epsilon) |
| **Alt + Shift + E** | Ε (Epsilon uppercase) |
| **Alt + z** | ζ (Zeta) |
| **Alt + Shift + Z** | Ζ (Zeta uppercase) |
| **Alt + h** | η (Eta) |
| **Alt + Shift + H** | Η (Eta uppercase) |
| **Alt + q** | θ (Theta) |
| **Alt + Shift + Q** | Θ (Theta uppercase) |
| **Alt + i** | ι (Iota) |
| **Alt + Shift + I** | Ι (Iota uppercase) |
| **Alt + k** | κ (Kappa) |
| **Alt + Shift + K** | Κ (Kappa uppercase) |
| **Alt + l** | λ (Lambda) |
| **Alt + Shift + L** | Λ (Lambda uppercase) |
| **Alt + m** | μ (Mu) |
| **Alt + Shift + M** | Μ (Mu uppercase) |
| **Alt + n** | ν (Nu) |
| **Alt + Shift + N** | Ν (Nu uppercase) |
| **Alt + x** | ξ (Xi) |
| **Alt + Shift + x** | Ξ (Xi uppercase) |
| **Alt + o** | ο (Omicron) |
| **Alt + z** | ζ (Zeta) |
| **Alt + Shift + Z** | Ζ (Zeta uppercase) |
| **Alt + h** | η (Eta) |
| **Alt + Shift + H** | Η (Eta uppercase) |
| **Alt + q** | θ (Theta) |
| **Alt + Shift + Q** | Θ (Theta uppercase) |
| **Alt + i** | ι (Iota) |
| **Alt + Shift + I** | Ι (Iota uppercase) |
| **Alt + k** | κ (Kappa) |
| **Alt + Shift + K** | Κ (Kappa uppercase) |
| **Alt + l** | λ (Lambda) |
| **Alt + Shift + L** | Λ (Lambda uppercase) |
| **Alt + m** | μ (Mu) |
| **Alt + Shift + M** | Μ (Mu uppercase) |
| **Alt + n** | ν (Nu) |
| **Alt + Shift + N** | Ν (Nu uppercase) |
| **Alt + x** | ξ (Xi) |
| **Alt + Shift + x** | Ξ (Xi uppercase) |
| **Alt + o** | ο (Omicron) |
| **Alt + Shift + O** | Ο (Omicron uppercase) |
| **Alt + p** | π (Pi) |
| **Alt + Shift + P** | Π (Pi uppercase) |
| **Alt + r** | ρ (Rho) |
| **Alt + Shift + R** | Ρ (Rho uppercase) |
| **Alt + s** | σ (Sigma) |
| **Alt + Shift + S** | Σ (Sigma uppercase) |
| **Alt + t** | τ (Tau) |
| **Alt + Shift + T** | Τ (Tau uppercase) |
| **Alt + u** | υ (Upsilon) |
| **Alt + p** | π (Pi) |
| **Alt + Shift + P** | Π (Pi uppercase) |
| **Alt + r** | ρ (Rho) |
| **Alt + Shift + R** | Ρ (Rho uppercase) |
| **Alt + s** | σ (Sigma) |
| **Alt + Shift + S** | Σ (Sigma uppercase) |
| **Alt + t** | τ (Tau) |
| **Alt + Shift + T** | Τ (Tau uppercase) |
| **Alt + u** | υ (Upsilon) |
| **Alt + Shift + U** | Υ (Upsilon uppercase) |
| **Alt + f** | φ (Phi) |
| **Alt + Shift + F** | Φ (Phi uppercase) |
| **Alt + y** | ψ (Psi) |
| **Alt + Shift + Y** | Ψ (Psi uppercase) |
| **Alt + c** | χ (Chi) |
| **Alt + Shift + C** | Χ (Chi uppercase) |
| **Alt + w** | ω (Omega) |
| **Alt + Shift + W** | Ω (Omega uppercase) |
| **Alt + f** | φ (Phi) |
| **Alt + Shift + F** | Φ (Phi uppercase) |
| **Alt + y** | ψ (Psi) |
| **Alt + Shift + Y** | Ψ (Psi uppercase) |
| **Alt + c** | χ (Chi) |
| **Alt + Shift + C** | Χ (Chi uppercase) |
| **Alt + w** | ω (Omega) |
| **Alt + Shift + W** | Ω (Omega uppercase) |
### Mathematical symbols
| Key | Character |
|----------------------|-------------------------------------------|
| **Alt + 1** | ∑ (Sum symbol) |
| **Alt + Shift + 1** | ∏ (Product symbol) |
| **Alt + 2** | ∫ (Integral symbol) |
| **Alt + Shift + 2** | ∂ (Partial derivation) |
| **Alt + 3** | ≤ (Less or equal symbol) |
| **Alt + Shift + 3** | ≥ (Greater or equal symbol) |
| **Alt + 4** | ∞ (Infinity symbol) |
| **Alt + Shift + 4** | ∅ (Empty set symbol) |
| **Alt + 5** | ≈ (Approximatley) |
| **Alt + Shift + 5** | ≠ (Not equal symbol) |
| **Alt + 6** | ∈ (Element of) |
| **Alt + Shift + 6** | ∉ (Not element of) |
| **Alt + 7** | ∨ (Logical or) |
| **Alt + Shift + 7** | ∧ (Logical and) |
| **Alt + 8** | ∠ (Angle symbol) |
| **Alt + Shift + 8** | ∝ (Proportional to) |
| **Alt + 9** | √ (Square root) |
| **Alt + Shift + 9** | ∛ (Cube root) |
| **Alt + 0** | ± (Plus minus) |
| **Alt + Shift + 0** | ∓ (Minus plus) |
| Key | Character |
|---------------------|-----------------------------|
| **Alt + 1** | ∑ (Sum symbol) |
| **Alt + Shift + 1** | ∏ (Product symbol) |
| **Alt + 2** | ∫ (Integral symbol) |
| **Alt + Shift + 2** | ∂ (Partial derivation) |
| **Alt + 3** | ≤ (Less or equal symbol) |
| **Alt + Shift + 3** | ≥ (Greater or equal symbol) |
| **Alt + 4** | ∞ (Infinity symbol) |
| **Alt + Shift + 4** | ∅ (Empty set symbol) |
| **Alt + 5** | ≈ (Approximately) |
| **Alt + Shift + 5** | ≠ (Not equal symbol) |
| **Alt + 6** | ∈ (Element of) |
| **Alt + Shift + 6** | ∉ (Not element of) |
| **Alt + 7** | ∨ (Logical or) |
| **Alt + Shift + 7** | ∧ (Logical and) |
| **Alt + 8** | ∠ (Angle symbol) |
| **Alt + Shift + 8** | ∝ (Proportional to) |
| **Alt + 9** | √ (Square root) |
| **Alt + Shift + 9** | ∛ (Cube root) |
| **Alt + 0** | ± (Plus minus) |
| **Alt + Shift + 0** | ∓ (Minus plus) |
### Currency symbols
Please not the following keybindings are bound to a specific keycode. The key character is not the same on all keyboards.
Please not the following keybindings are bound to a specific keycode. The key character is not the same on all
keyboards.
It is given here for a US keyboard layout.
For a German keyboard layout, replace ; with ö, and ' with ä.
| Key | Character |
|---------------------------------|---------------------------|
| **Alt + ;** (code 192) | € (Euro currency symbol) |
| **Alt + Shift + ;** (code 192) | £ (Pound currency symbol) |
| **Alt + '** (code 222) | ¥ (Yen currency symbol) |
| Key | Character |
|---------------------------------|----------------------------|
| **Alt + ;** (code 192) | € (Euro currency symbol) |
| **Alt + Shift + ;** (code 192) | £ (Pound currency symbol) |
| **Alt + '** (code 222) | ¥ (Yen currency symbol) |
| **Alt + Shift + '** (code 222) | $ (Dollar currency symbol) |
### Others
Please not the following keybindings are bound to a specific keycode. The key character is not the same on all keyboards.
Please not the following keybindings are bound to a specific keycode. The key character is not the same on all
keyboards.
It is given here for a US keyboard layout.
For a German keyboard layout, replace `[` with `0`, and `]` with `´`.
@ -114,6 +117,6 @@ For a German keyboard layout, replace `[` with `0`, and `]` with `´`.
| Key | Character |
|--------------------------------|--------------------|
| **Alt + [** (code 219) | © (Copyright char) |
| **Alt + Shift + [** (code 219) | (Registered char) |
| **Alt + Shift + [** (code 219) | (Registered char) |
| **Alt + ]** (code 221) | ™ (Trademark char) |
| **Alt + Shift + ]** (code 221) | (Degree char) |
| **Alt + Shift + ]** (code 221) | (Degree char) |

163
docs/usage/labels.md
View file

@ -6,103 +6,114 @@ parent: Usage
# Labels
Part-DB support the generation and printing of labels for parts, part lots and storelocation.
You can use the "Tools -> Labelgenerator" menu entry to create labels, or click the label generation link on the part.
Part-DB support the generation and printing of labels for parts, part lots and storage locations.
You can use the "Tools -> Label generator" menu entry to create labels, or click the label generation link on the part.
You can define label templates by creating Label profiles. This way you can create many similar looking labels with for
many parts.
The content of the labels is defined by the templates content field. You can use the WYSIWYG editor to create and style the content (or write HTML code).
The content of the labels is defined by the templates content field. You can use the WYSIWYG editor to create and style
the content (or write HTML code).
Using the "Label placeholder" menu in the editor, you can insert placeholders for the data of the parts.
It will be replaced by the concrete data when the label is generated.
## Label placeholders
A placeholder has the format `[[PLACEHOLDER]]` and will be filled with the concrete data by Part-DB.
You can use the "Placeholders" dropdown in content editor, to automatically insert the placeholders.
### Common
| Placeholder | Description | Example |
|---|---|---|
| `[[USERNAME]]` | The user name of the currently logged in user | admin |
| `[[USERNAME_FULL]]` | The full name of the current user | John Doe (@admin) |
| `[[DATETIME]]` | The current date and time in the selected locale | 31.12.2017, 18:34:11 |
| `[[DATE]]` | The current date in the selected locale | 31.12.2017 |
| `[[TIME]]` | The current time in the selected locale | 18:34:11 |
| `[[INSTALL_NAME]]` | The name of the current installation (see $config['partdb_title']) | Part-DB |
| `[[INSTANCE_URL]]` | The URL of the current installation | https://demo.part-db.de |
| Placeholder | Description | Example |
|---------------------|--------------------------------------------------------------------|-------------------------|
| `[[USERNAME]]` | The user name of the currently logged in user | admin |
| `[[USERNAME_FULL]]` | The full name of the current user | John Doe (@admin) |
| `[[DATETIME]]` | The current date and time in the selected locale | 31.12.2017, 18:34:11 |
| `[[DATE]]` | The current date in the selected locale | 31.12.2017 |
| `[[TIME]]` | The current time in the selected locale | 18:34:11 |
| `[[INSTALL_NAME]]` | The name of the current installation (see $config['partdb_title']) | Part-DB |
| `[[INSTANCE_URL]]` | The URL of the current installation | https://demo.part-db.de |
### Parts
| Placeholder | Description | Example |
|---|---|---|
| `[[ID]]` | The internal ID of the part | 24 |
| `[[NAME]]` | The name of the part | ATMega328 |
| `[[CATEGORY]]` | The name of the category (without path) | AVRs |
| `[[CATEGORY_FULL]]` | The full path of the category | Aktiv->MCUs->AVRs |
| `[[MANUFACTURER]]` | The name of the manufacturer | Atmel |
| `[[MANUFACTURER_FULL]]` | The full path of the manufacturer | Halbleiterhersteller->Atmel |
| `[[FOOTPRINT]]` | The name of the footprint (without path) | DIP-32 |
| `[[FOOTPRINT_FULL]]` | The full path of the footprint | Bedrahtet->DIP->DIP-32 |
| `[[MASS]]` | The mass of the part | 123.4 g |
| `[[MPN]]` | The manufacturer product number | BC547ACT |
| `[[TAGS]]` | The tags of the part | SMD, Tag1 |
| `[[M_STATUS]]` | The manufacturing status of the part | Active |
| `[[DESCRIPTION]]` | The rich text description of the part | *NPN* |
| `[[DESCRIPTION_T]]` | The description as plain text | NPN |
| `[[COMMENT]]` | The rich text comment of the part | |
| `[[COMMENT_T]]` | The comment as plain text | |
| `[[LAST_MODIFIED]]` | The datetime when the element was last modified | 2/26/16, 5:38 PM |
| `[[CREATION_DATE]]` | The datetime when the element was created | 2/26/16, 5:38 PM |
| Placeholder | Description | Example |
|-------------------------|-------------------------------------------------|-----------------------------|
| `[[ID]]` | The internal ID of the part | 24 |
| `[[NAME]]` | The name of the part | ATMega328 |
| `[[CATEGORY]]` | The name of the category (without path) | AVRs |
| `[[CATEGORY_FULL]]` | The full path of the category | Aktiv->MCUs->AVRs |
| `[[MANUFACTURER]]` | The name of the manufacturer | Atmel |
| `[[MANUFACTURER_FULL]]` | The full path of the manufacturer | Halbleiterhersteller->Atmel |
| `[[FOOTPRINT]]` | The name of the footprint (without path) | DIP-32 |
| `[[FOOTPRINT_FULL]]` | The full path of the footprint | Bedrahtet->DIP->DIP-32 |
| `[[MASS]]` | The mass of the part | 123.4 g |
| `[[MPN]]` | The manufacturer product number | BC547ACT |
| `[[TAGS]]` | The tags of the part | SMD, Tag1 |
| `[[M_STATUS]]` | The manufacturing status of the part | Active |
| `[[DESCRIPTION]]` | The rich text description of the part | *NPN* |
| `[[DESCRIPTION_T]]` | The description as plain text | NPN |
| `[[COMMENT]]` | The rich text comment of the part | |
| `[[COMMENT_T]]` | The comment as plain text | |
| `[[LAST_MODIFIED]]` | The datetime when the element was last modified | 2/26/16, 5:38 PM |
| `[[CREATION_DATE]]` | The datetime when the element was created | 2/26/16, 5:38 PM |
### Part lot
| Placeholder | Description | Example |
|---|---|---|
| `[[LOT_ID]]` | Part lot ID | 123 |
| `[[LOT_NAME]]` | Part lot name | |
| `[[LOT_COMMENT]]` | Part lot comment | |
| `[[EXPIRATION_DATE]]` | Expiration date of the part lot | |
| `[[AMOUNT]]` | The amount of parts in this lot | 12 |
| `[[LOCATION]]` | The storage location of this part lot | Location A |
| `[[LOCATION_FULL]]` | The full path of the storage location | Location -> Location A |
| Placeholder | Description | Example |
|-----------------------|---------------------------------------|------------------------|
| `[[LOT_ID]]` | Part lot ID | 123 |
| `[[LOT_NAME]]` | Part lot name | |
| `[[LOT_COMMENT]]` | Part lot comment | |
| `[[EXPIRATION_DATE]]` | Expiration date of the part lot | |
| `[[AMOUNT]]` | The amount of parts in this lot | 12 |
| `[[LOCATION]]` | The storage location of this part lot | Location A |
| `[[LOCATION_FULL]]` | The full path of the storage location | Location -> Location A |
### Storelocation
| Placeholder | Description | Example |
|---|---|---|
| `[[ID]]` | ID of the storage location | |
| `[[NAME]]` | Name of the storage location | Location A |
| `[[FULL_PATH]]` | The full path of the storage location | Location -> Location A |
| `[[PARENT]]` | The name of the parent location | Location |
| `[[PARENT_FULL_PATH]]` | The full path of the storage location | |
| `[[COMMENT]]` | The comment of the storage location | |
| `[[COMMENT_T]]` | The plain text version of the comment |
| `[[LAST_MODIFIED]]` | The datetime when the element was last modified | 2/26/16, 5:38 PM |
| `[[CREATION_DATE]]` | The datetime when the element was created | 2/26/16, 5:38 PM |
| Placeholder | Description | Example |
|------------------------|-------------------------------------------------|------------------------|
| `[[ID]]` | ID of the storage location | |
| `[[NAME]]` | Name of the storage location | Location A |
| `[[FULL_PATH]]` | The full path of the storage location | Location -> Location A |
| `[[PARENT]]` | The name of the parent location | Location |
| `[[PARENT_FULL_PATH]]` | The full path of the storage location | |
| `[[COMMENT]]` | The comment of the storage location | |
| `[[COMMENT_T]]` | The plain text version of the comment |
| `[[LAST_MODIFIED]]` | The datetime when the element was last modified | 2/26/16, 5:38 PM |
| `[[CREATION_DATE]]` | The datetime when the element was created | 2/26/16, 5:38 PM |
## Twig mode
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/).
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 [official documentation](https://twig.symfony.com/doc/3.x/).
The following variables are in injected into Twig and can be accessed using `{% raw %}{{ variable }}` (or `{% raw %}{{ variable.property }}{% endraw %}`):
| 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 |
The following variables are in injected into Twig and can be accessed using `{% raw %}{{ variable }}` (
or `{% raw %}{{ variable.property }}{% endraw %}`):
| 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 |
## Use custom fonts for PDF labels
You can use your own fonts for label generation. To do this, put the TTF files of the fonts you want to use into the `assets/fonts/dompdf` folder.
The filename will be used as name for the font family and you can use a `_bold` (or `_b`), `_italic` (or `_i`) or `_bold_italic` (or `_bi`) suffix to define
different styles of the font. So for example, if you copy the file `myfont.ttf` and `myfont_bold.ttf` into the `assets/fonts/dompdf` folder, you can use the font family `myfont` with regular and bold style.
Afterwards regenerate cache with `php bin/console cache:clear`, so the new fonts will be available for label generation.
The fonts will not be availble from the UI directly, you have to use it in the HTML directly either by defining a `style="font-family: 'myfont';"` attribute on the HTML element or by using a CSS class.
You can define the font globally for the label, by adding following statement to the "Additional styles (CSS)" option in the label generator settings:
You can use your own fonts for label generation. To do this, put the TTF files of the fonts you want to use into
the `assets/fonts/dompdf` folder.
The filename will be used as name for the font family, and you can use a `_bold` (or `_b`), `_italic` (or `_i`)
or `_bold_italic` (or `_bi`) suffix to define
different styles of the font. So for example, if you copy the file `myfont.ttf` and `myfont_bold.ttf` into
the `assets/fonts/dompdf` folder, you can use the font family `myfont` with regular and bold style.
Afterward regenerate cache with `php bin/console cache:clear`, so the new fonts will be available for label generation.
The fonts will not be available from the UI directly, you have to use it in the HTML directly either by defining
a `style="font-family: 'myfont';"` attribute on the HTML element or by using a CSS class.
You can define the font globally for the label, by adding following statement to the "Additional styles (CSS)" option in
the label generator settings:
```css
* {
font-family: 'myfont';
@ -110,9 +121,15 @@ You can define the font globally for the label, by adding following statement to
```
## Non-latin characters in PDF labels
The default used font (DejaVu) does not support all characters. Especially characters from non-latin languages like Chinese, Japanese, Korean, Arabic, Hebrew, Cyrillic, etc. are not supported.
For this we use [Unifont](http://unifoundry.com/unifont.html) as fallback font. This font supports all (or most) unicode characters, but is not as beautiful as DejaVu.
If you want to use a different (more beautiful) font, you can use the [custom fonts](#use-custom-fonts-for-pdf-labels) feature.
There is the [Noto](https://www.google.com/get/noto/) font family from Google, which supports a lot of languages and is available in different styles (regular, bold, italic, bold-italic).
For example you can use [Noto CJK](https://github.com/notofonts/noto-cjk) for more beautful Chinese, Japanese and Korean characters.
The default used font (DejaVu) does not support all characters. Especially characters from non-latin languages like
Chinese, Japanese, Korean, Arabic, Hebrew, Cyrillic, etc. are not supported.
For this we use [Unifont](http://unifoundry.com/unifont.html) as fallback font. This font supports all (or most) unicode
characters, but is not as beautiful as DejaVu.
If you want to use a different (more beautiful) font, you can use the [custom fonts](#use-custom-fonts-for-pdf-labels)
feature.
There is the [Noto](https://www.google.com/get/noto/) font family from Google, which supports a lot of languages and is
available in different styles (regular, bold, italic, bold-italic).
For example, you can use [Noto CJK](https://github.com/notofonts/noto-cjk) for more beautiful Chinese, Japanese
and Korean characters.

50
docs/usage/tips_tricks.md
View file

@ -10,39 +10,48 @@ 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
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",
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,
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",
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
have to fulfill. 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).
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
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:
```
@ -56,7 +65,8 @@ $$E=mc^2$$
```
## Update currency exchange rates automatically
Part-DB can update the currency exchange rates of all defined currencies programatically
Part-DB can update the currency exchange rates of all defined currencies programmatically
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.
@ -65,18 +75,26 @@ Please note that if you use a base currency, which is not the Euro, you have to
free API used by default only supports the Euro as base currency.
## Enforce log comments
On almost any editing operation it is possible to add a comment describing, what or why you changed something.
This comment will be written to change log and can be viewed later.
If you want to enforce your users to add comments to certain operations, you can do this by setting the `ENFORCE_CHANGE_COMMENTS_FOR` option.
If you want to enforce your users to add comments to certain operations, you can do this by setting
the `ENFORCE_CHANGE_COMMENTS_FOR` option.
See the configuration reference for more information.
## Personal stocks and stock locations
For makerspaces and universities with a lot of users, where each user can have his own stock, which only he should be able to access, you can assign
For makerspaces and universities with a lot of users, where each user can have his own stock, which only he should be
able to access, you can assign
the user as "owner" of a part lot. This way, only him is allowed to add or remove parts from this lot.
## Update notfications
Part-DB can show you a notification that there is a newer version than currently installed available. The notification will be shown on the homepage and the server info page.
## Update notifications
Part-DB can show you a notification that there is a newer version than currently installed available. The notification
will be shown on the homepage and the server info page.
It is only be shown to users which has the `Show available Part-DB updates` permission.
For the notification to work, Part-DB queries the GitHub API every 2 days to check for new releases. No data is sent to GitHub besides the metadata required for the connection (so the public IP address of your computer running Part-DB).
If you don't want Part-DB to query the GitHub API, or if your server can not reach the internet, you can disable the update notifications by setting the `CHECK_FOR_UPDATES` option to `false`.
For the notification to work, Part-DB queries the GitHub API every 2 days to check for new releases. No data is sent to
GitHub besides the metadata required for the connection (so the public IP address of your computer running Part-DB).
If you don't want Part-DB to query the GitHub API, or if your server can not reach the internet, you can disable the
update notifications by setting the `CHECK_FOR_UPDATES` option to `false`.