Documentation and cleanup

docs/data-model/extras.md

@@ -1,5 +1,31 @@
 This section entails features of NetBox which are not crucial to its primary functions, but that provide additional value.
 
+# Custom Fields
+
+Each object in NetBox is represented in the database as a discrete table, and each attribute of an object exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address` and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows.
+
+However, some users might want to associate with objects attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number pointing to the support ticket that was opened to have it installed. This is certainly a legitimate use for NetBox, but it's perhaps not a common enough need to warrant expanding the internal data schema. Instead, you can create a custom field to hold this data.
+
+Custom fields must be created through the admin UI under Extras > Custom Fields. To create a new custom field, select the object(s) to which you want it to apply, and the type of field it will be. NetBox supports five field types:
+
+* Free-form text (up to 255 characters)
+* Integer
+* Boolean (true/false)
+* Date
+* Selection
+
+Assign the field a name. This should be a simple database-friendly string, e.g. `tps_report`. You may optionally assign the field a human-friendly label (e.g. "TPS report") as well; the label will be displayed on forms. If a description is provided, it will appear beneath the field in a form.
+
+Marking the field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields. (The default value has no effect for selection fields.)
+
+When creating a selection field, you must create at least two choices. These choices will be arranged first by weight, with lower weights appearing higher in the list, and then alphabetically.
+
+## Using Custom Fields
+
+When a single object is edited, the form will include any custom fields which have been defined for its type. These fields are included in the "Custom Fields" panel. Each custom field value must be saved independently from the core object, so it's best to avoid adding too many custom fields per object.
+
+When editing multiple objects, values are saved in bulk per field. That is, there is no significant difference in overhead when saving a custom field value for 100 objects versus one object. However, the bulk operation must be performed separately for each custom field.
+
 # Export Templates
 
 NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Extras > Export Templates under the admin interface.

netbox/extras/admin.py

@@ -20,6 +20,7 @@ def __init__(self, *args, **kwargs):
 
 class CustomFieldChoiceAdmin(admin.TabularInline):
     model = CustomFieldChoice
+    extra = 5
 
 
 @admin.register(CustomField)

netbox/extras/forms.py

@@ -54,7 +54,7 @@ def get_custom_fields_for_model(content_type, bulk_editing=False):
             field = forms.CharField(max_length=255, required=cf.required, initial=cf.default)
 
         field.model = cf
-        field.label = cf.label if cf.label else cf.name.capitalize()
+        field.label = cf.label if cf.label else cf.name.replace('_', ' ').capitalize()
         field.help_text = cf.description
 
         field_dict[field_name] = field

netbox/extras/models.py

@@ -98,7 +98,7 @@ class Meta:
         ordering = ['name']
 
     def __unicode__(self):
-        return self.label or self.name.capitalize()
+        return self.label or self.name.replace('_', ' ').capitalize()
 
     def serialize_value(self, value):
         """