Adding and Refactoring Custom Fields

Adding/Refactoring Custom Fields

If you're trying to change a custom field or adding new ones, please make sure your changes meet these requirements:

1. Changes in User Interface

If you planning to add a new custom field which is not a simple single input field, it would be best if you can file an issue first, so that we can discuss your approach on changing the UI/UX before actually implement the changes. I believe this will save us a lot of time down the road.

2. Best Practices & Convention

React and Electron are the two main technologies that Manta uses under the hood. Please make sure you follow their best practices and the convention that's used in the app.

For example, most of the application logic is handled inside the Redux middlewares, I found this approach makes the most sense (at least for Manta) as it makes it super easy to test different parts of the app and with the ability to intercept actions, talk to the store, a middleware can do almost anything that you want to do in your app.

If your changes introduce new logic to the app, this should be the first place that you should consider to place that logic.

If you're not sure about anything, please ask.

3. Integrate well with Form/App settings

Make sure the custom field works well with the form and the app settings. For example:

• If the custom field is not always required, it should default to off in the Settings/Invoice/Require Fields section.
• User can show/hide this field in the form by using the form settings
• The Save as Default action should override the above default setting.

If the field has its own settings (such as the Tax or Currency field), these settings should:

• Has a dedicated section under the Settings/Invoice.
• Can be overridden in the form.
• Can be overwritten by using the Save as Default action.

4. Work with Clear Form and Edit Invoice

Like the title mentions, your changes need to make sure that the custom field works well with these actions:

• The field value should be reset to its default value if the user hit the Clear button.
• When the user chooses to edit the invoice, the value of the custom field must be exactly the same as it was when creating the invoice.

Let me elaborate on the second point by using the implementation of the Due Date field as an example.

When creating a new invoice (using the form), you can choose a custom date (default) or choose a predefined term by clicking on the Choose Payment Term radio button then select one of the terms from the drop-down menu.

Let's say we choose Net 30 as the payment term for this invoice. If today is 1st of April then the due date should be 1st of May.

We have at least 2 approaches to handle this. We can either:

• Calculate the final due date to 1st of May and save it to the invoice record.
• Save net30 to the invoice and calculate the final due date whenever we need, for example when we need to display the date on the invoice.

At first glance, the first approach seems to be much simpler and easier to implement. However, it doesn't work well when the user try to edit the invoice. For example:

• We will need to convert it back to the correct payment term, which means we would need to write a new helper to do this.
• If we chose to use it as a custom date (which even wasn't the original input from the user), the user would need to click the Choose Payment Term radio button, select the dropdown list and choose the correct payment term again. This requires at least 3 extra clicks to achieve ...nothing. Bad UX!

A second approach would be keeping everything as it is. We'll only need to write a simple conversion helper to convert a payment term to a specific date. This helper is very simple to write and we only use it when necessary. This approach may not be clear at first but quite straightforward when implement. It makes sure the custom field works well for both creating an invoice and editing an invoice.

The point is, try to cover all edge cases and avoid creating side effects as much as you can.

5. Validation Rule

Each custom field needs at least one validation rule. It's simply to write and will save the user time so don't be lazy ;)

6. Validation Message

Please make sure that you provide:

• Good UX message. What's a good UX message, you asked. Good question 👍. I highly recommend reading this article.
• Translation. Since version 1.1.3, Manta starts to support multiple languages and the number of these languages will increase over time. Contributors should treat translation as part of the PR. I know this will take more time but we should all strike for delivering the best experience (regardless of circumstances) that we all enjoy.

7. C.R.U.D Operations

Please make sure all CRUD operation will still function properly after your changes are implemented. These operations include but are not limited to:

Invoice

• Create a new invoice
• Preview an invoice
• Update an invoice
• • Set status
• • Save template configs
• • Update other information
• Delete an invoice

Contact

• Create a new contact
• Delete a contact

8. Migration

If your changes are going to change the way a document (invoice, contact) is structured, you will need to write a migration script to make sure all existing documents (aka the user's data) will be "upgraded" to this new structure.

The script actually has already been written (and you're welcomed to improve it), the only thing that you need to provide is a function that tells how the old document should be upgraded to its newer version.

This is very important because, without it, it's very likely that the users won't be able to view their data or worst they will be corrupted. So please make sure you test the migration scheme properly before submitting the PR.

The users will really appreciate it! 👍

9. Display

If a custom field is going to be added or changed in some way, please make sure the invoices will still be displayed correctly in places such as:

• The Invoices page/tab
• The previewWindow
• The exported PDF

10. Tests

Tests are an important part of the development process of Manta so please make sure to include at least some unit tests for any logic, components, helpers … that your changes introduce. Also, check if your changes break existing tests. If it does, please fix them before submitting your PR.