+ + * **Hash Algorithm** *Default: SHA256* - You may choose the hashing algorithm here. This may affect build time if you choose a more complex option. (Hashes are used to help determine whether source files have changed between import/export operations.) + + * **Use short hashes in index** *Default: ON* - If checked, `git` style hashes (first 7 characters) will be used in the file index. *NOTE: This was done to improve readability and reduce file size, but you can always uncheck this box if you want to store the full hash.* -![](img/options-general.jpg) +
+
- * **Export Folder** - I like to keep this relative to the project, but it can be customized here.
+## Export Tab
+![Export Options Tab](img/options-export.jpg)
+
+ * **Export Folder** *Default: [Blank]* - I like to keep this relative to the project, but it can be customized here.
+
+ Click to expand folder options
+
* *[Blank]* - Use default name of `/[database.accdb].src`, i.e. `/Test.accdb.src`
* *Relative Path* - Prefix folder name with a backslash. For example, to export source into a subfolder called `Source`, you would enter `\Source` in this box.
* *Absolute Path* - You may also use a full path name to a folder. I.e. `W:\Git\Projects\Vehicles Database`
* *Placeholder* - In combination with the above options, you may also use a `%dbName%` [placeholder](https://github.com/joyfullservice/msaccess-vcs-integration/issues/139) to use the database filename in a custom path. I.e. `\src\%dbName%.src\`
+Click to expand levels...
+
+ **_NOTE:_ If you set Sanitize level to "*None (Off)*", none of the Sanitize Options (Sanitize Color, Strip out publish, etc.) will be used.**
+ * *None (Off)* Turn off sanitization, export raw files. These may not import properly, but they may be useful when trying to troubleshoot. _**Note:** Files will still be converted to UTF-8 or System Codepage encoding depending on Access Version in this mode._
+ * *Basic* Only basic sanitization to ensure reliable rebuilding of files.
+ * *Aggressive* Remove most exported noise (GUIDs, the like). Removes object GUIDs, name maps, and other data that changes from build to build. (These values are recreated automatically when importing source files.) From a development perspective, these are more like binary artifacts that just add noise to the version control commits, reducing clarity on actual code changes.
+ * *Advanced (Beta)* Remove as much as possible. This may lead to unexpected changes upon rebuilding. Features that are still in testing or confirmed to be tempermental may be introduced here prior to being implemented. **_User beware!_**
+Show Advanced Printer Options...
+ * **Sanitize Colors** *Default: Basic* - Removes color exports on forms where themes are used, or other situations where the color can be correctly set upon rebuild. These colors export differently in different machines, or different settings and are largely noise. ***NOTE:* The most aggressive options may lead to unexpected color changes on forms!**
-![](img/options-printer-settings.jpg)
+ * **Strip out Publish Option** *Default: ON* - Strips out some *Publish to Web* settings from source files that are irrelevant to most projects.
+ * **Save Printer Settings** *Default: ON* - Saves a copy of the print configuration for reports and forms. This is especially useful when you are using specific printer settings. The output is stored in human-readable json. By default, page orientation and paper size are saved with each report, but additional options are also available. Show Advanced Printer Options...
+![Printer Settings Options Screen Image](img/options-printer-settings.jpg)
Note that these options only determine what is *Exported* and saved to the JSON file. Any settings defined in the JSON source file will be applied when the report object is Imported, regardless of the currently specified options.
+
* **Update** - Save output specification changes for the selected table. You should see the Save Data column update in the list of tables when you click the Update button. ## Build - -![](img/options-build.jpg) +![Build Options Tab Image](img/options-build.jpg) One of the unique features of this add-in is the ability to build a fully functioning database completely from source files. This allows multi-user development in a more typical development workflow where source files are exported and combined to build the end product. * **Force import of original SQL for queries** - In some cases, such as when a query contains a subquery, _AND_ has been modified in the visual query designer, it may be imported incorrectly and unable to run. For these cases we have added an option to overwrite the .SQL property with the SQL that we saved separately during the export. See [issue #76](https://github.com/joyfullservice/msaccess-vcs-integration/issues/76) for further details. - * **Run Sub After Build** - Run the specified subroutine after building the project from source files. This is a great way to extend the add-in to add any custom post-build functionality that you need after the build finishes. For example, you might use this to trigger an automated testing routine that verifies that the application is fully functional. + * **Run Sub Before Build** - Same as below, except before the build. - * Save output specification changes for the selected table. You should see the Save Data column update in the list of tables when you click the Update button. + * **Run Sub After Build** - Run the specified subroutine after building the project from source files. This is a great way to extend the add-in to add any custom post-build functionality that you need after the build finishes. For example, you might use this to trigger an automated testing routine that verifies that the application is fully functional. -## Settings (Global) +## Settings These affect your system at large; not just the currently open Access Project. -![](img/options-settings.jpg) +![Settings Options Tab](img/options-settings.jpg) +### System Defaults * **Save as Default** - Save the current options as default for new projects. Anytime you export source and a `vcs-options.json` file does not already exist, it will use the default options that you have specified. @@ -91,5 +113,7 @@ These affect your system at large; not just the currently open Access Project. * **Clear Defaults** - Reset all the options to the default settings specified in the add-in source code. If you click this button, then the *Save as Default* button, it will reset any user customizations to the default options. -## Uninstalling +### Remove Add-In + * **Uninstall** - Uninstalls the add-in from your user profile, including all saved defaults and encryption keys. +[Click here for Install / Uninstall Instructions](Installation) \ No newline at end of file diff --git a/Wiki/Project-Scope.md b/Wiki/Project-Scope.md new file mode 100644 index 00000000..60268037 --- /dev/null +++ b/Wiki/Project-Scope.md @@ -0,0 +1,22 @@ +I personally believe that one of the keys to the long-term success of this project is establishing a clearly defined scope of what it is intended to do, and sticking to that scope. + +## Guiding Principles +Since much of this could be considered subjective archetecutual design decisions, let me outline some of the guiding principles that I am trying to keep in the forefront of this project. +* The **fundemental purpose** of this add-in is two-fold: + * **Export** database objects as source files + * **Import**/**Build**/**Merge** source files to database objects +* The goal is to replicate the original database as **closely as possible** when building from source. +* The add-in is **not intended** to fix/repair/enhance the target database, other than what is necessary to perform the basic functions of exporting and importing source files. +* The **user interface** should be as intuitive and user-friendly as possible. It should be both efficient for the expert, and easy for the beginner. Flexibility without clutter. +* The tool should be **extensible**, where internal code can be added to carry out additional tasks outside the scope of this add-in. + + +## How Features are Evaluated +Features add complexity, and complexity increases [cost of carry](https://martinfowler.com/bliki/Yagni.html). Great features are welcomed and make this tool better every year. Unecessary or overly complex features bog down the project and slow progress on more important issues. + +**Feature considerations:** +* How many users does this affect? Will this benefit everyone, or just a single user with a really unique setup? +* How complex is the feature? Is it limited to changes in a few areas of code, or are we talking about a significant refactoring? +* Do functionality changes cause any risks for those currently using the add-in in production environments? + +If your idea didn't get implemented, don't take it personally. :-) Remember, this is an ongoing work in progress, and someone has to make the hard decisions about what gets added and what doesn't. diff --git a/Wiki/Supported-Objects.md b/Wiki/Supported-Objects.md index 4f520782..41294c1d 100644 --- a/Wiki/Supported-Objects.md +++ b/Wiki/Supported-Objects.md @@ -23,62 +23,65 @@ If you are looking for a specific type of object or property that you want to ex The *Testing* column indicates whether a test item and testing code has been created in the *Testing.accdb* database to verify that particular item after import from source code. *Test location* indicates where to find the object in the database. -|Type |Export|Import|VBA Class| -|-----------------------|:----:|:----:|---------| +|Type |Export|Import|VBA Class| +|-------------------------|:----:|:----:|---------| |💼 **TABLES** -|Access Table |✔️|✔️|clsDbTableDef -|Extended Properties |✔️|✔️|clsDbTableDef -|Table SQL |✔️|✔️|clsDbTableDef -|Linked Table |✔️|✔️|clsDbTableDef -|Linked PrimaryKey |✔️|✔️|clsDbTableDef -|ODBC Table |✔️|✔️|clsDbTableDef -|Linked Structure |✔️|✔️|clsDbTableDef -|Table Data (TDF) |✔️|✔️|clsDbTableData -|Table Data (XML) |✔️|✔️|clsDbTableData -|Table Data Macros |✔️|✔️|clsDbTableDataMacro +|Access Table |✔️|✔️|clsDbTableDef +|Extended Properties |✔️|✔️|clsDbTableDef +|Table SQL |✔️|✔️|clsDbTableDef +|Linked Table |✔️|✔️|clsDbTableDef +|Linked PrimaryKey |✔️|✔️|clsDbTableDef +|ODBC Table |✔️|✔️|clsDbTableDef +|Linked Structure |✔️|✔️|clsDbTableDef +|Table Data (TDF) |✔️|✔️|clsDbTableData +|Table Data (XML) |✔️|✔️|clsDbTableData +|Table Data Macros |✔️|✔️|clsDbTableDataMacro |💼 **QUERIES** -|Designer Layout |✔️|✔️|clsDbQuery -|SQL Output |✔️|✔️|clsDbQuery -|Pass Through Queries |✔️|✔️|clsDbQuery +|Designer Layout |✔️|✔️|clsDbQuery +|SQL Output |✔️|✔️|clsDbQuery +|Pass Through Queries |✔️|✔️|clsDbQuery |💼 **FORMS** -|Form objects |✔️|✔️|clsDbForm -|Saved print settings |✔️|✔️|clsDbReport|Optional +|Form objects |✔️|✔️|clsDbForm +|Saved print settings |✔️|✔️|clsDbReport|Optional |💼 **REPORTS** -|Report objects |✔️|✔️|clsDbReport -|Saved print settings |✔️|✔️|clsDbReport|Optional +|Report objects |✔️|✔️|clsDbReport +|Saved print settings |✔️|✔️|clsDbReport|Optional |💼 **MACROS** -|Macro objects |✔️|✔️|clsDbMacro +|Macro objects |✔️|✔️|clsDbMacro |💼 **MODULES** -|Standard Modules |✔️|✔️|clsDbModule -|Class Modules |✔️|✔️|clsDbModule -|Object Modules |✔️|✔️|clsDbModule +|Standard Modules |✔️|✔️|clsDbModule +|Class Modules |✔️|✔️|clsDbModule +|Object Modules |✔️|✔️|clsDbModule +|Hidden VBE Attributes |✔️|✔️|clsDbModule |💼 **DATABASE** -|DAO Properties |✔️|✔️|clsDbProperty -|Project Properties |✔️|✔️|clsDbProjProperty -|Object Descriptions |✔️|✔️|clsDbDocument -|Application Icon |✔️|✔️|clsDbProperty -|Embedded Images |✔️|✔️|clsDbSharedImage -|Saved Imp/Exp Specs |✔️|✔️|clsDbSavedSpec -|System Imp/Exp Specs |✔️|✔️|clsDbImexSpec -|Summary Properties |✔️|✔️|clsDbDocument -|Relationships |✔️|✔️|clsDbRelation -|Nav. Pane Groups |✔️|✔️|clsNavPaneGroup -|Embedded Office Theme |✔️|✔️|clsDbTheme +|DAO Properties |✔️|✔️|clsDbProperty +|Project Properties |✔️|✔️|clsDbProjProperty +|Object Descriptions |✔️|✔️|clsDbDocument +|Hidden Attribute |✔️|✔️|clsDbHiddenAttribute +|Remove Personal Info |✔️|✔️|clsDbProject +|Application Icon |✔️|✔️|clsDbProperty +|Embedded Images |✔️|✔️|clsDbSharedImage +|Saved Imp/Exp Specs |✔️|✔️|clsDbSavedSpec +|System Imp/Exp Specs |✔️|✔️|clsDbImexSpec +|Summary Properties |✔️|✔️|clsDbDocument +|Relationships |✔️|✔️|clsDbRelation +|Nav. Pane Groups |✔️|✔️|clsDbNavPaneGroup +|Embedded Office Theme(s) |✔️|✔️|clsDbTheme |💼 **VBE PROJECT** -|Project Properties |✔️|✔️|clsDbVbeProject -|Compilation Arguments |✔️|✔️|clsDbVbeProject -|GUID References |✔️|✔️|clsDbVbeReference -|File/Lib References |✔️|✔️|clsDbVbeReference -|Forms 2.0 documents |✔️|✔️|clsDbVbeForm +|Project Properties |✔️|✔️|clsDbVbeProject +|Compilation Arguments |✔️|✔️|clsDbVbeProject +|GUID References |✔️|✔️|clsDbVbeReference +|File/Lib References |✔️|✔️|clsDbVbeReference +|Forms 2.0 documents |✔️|✔️|clsDbVbeForm |💼 **ADP PROJECTS** -|Connection Settings |||clsDbProjProperty -|SQL Functions |✔️|n/a|clsAdpFunction -|SQL Views |✔️|n/a|clsAdpServerView -|SQL Stored Procedures |✔️|n/a|clsAdpProcedure -|SQL Tables |✔️|n/a|clsAdpTable -|SQL Triggers |✔️|n/a|clsAdpTrigger +|Connection Settings |||clsDbProjProperty +|SQL Functions |✔️|n/a|clsAdpFunction +|SQL Views |✔️|n/a|clsAdpServerView +|SQL Stored Procedures |✔️|n/a|clsAdpProcedure +|SQL Tables |✔️|n/a|clsAdpTable +|SQL Triggers |✔️|n/a|clsAdpTrigger |💼 **OTHER** -|Saved VCS Options |✔️|✔️|clsOptions +|Saved VCS Options |✔️|✔️|clsOptions ## ADP Projects diff --git a/Wiki/img/install.jpg b/Wiki/img/install.jpg new file mode 100644 index 00000000..0aff9cdf Binary files /dev/null and b/Wiki/img/install.jpg differ diff --git a/Wiki/img/main.jpg b/Wiki/img/main.jpg new file mode 100644 index 00000000..f3b90ca8 Binary files /dev/null and b/Wiki/img/main.jpg differ diff --git a/Wiki/img/options-build.jpg b/Wiki/img/options-build.jpg index 69dac84c..412976eb 100644 Binary files a/Wiki/img/options-build.jpg and b/Wiki/img/options-build.jpg differ diff --git a/Wiki/img/options-export.jpg b/Wiki/img/options-export.jpg new file mode 100644 index 00000000..af29a212 Binary files /dev/null and b/Wiki/img/options-export.jpg differ diff --git a/Wiki/img/options-general.jpg b/Wiki/img/options-general.jpg index 2494c60f..12c7c827 100644 Binary files a/Wiki/img/options-general.jpg and b/Wiki/img/options-general.jpg differ