Help understanding/documenting parts of the Manifest

[gerane]

There are parts of the manifest that I haven't been able to figure out yet. I was hoping to get more information on certain portions. I was just noting everything as I was going through and trying to get a good understanding of everything. Figured I might get some feedback and maybe this could be added to the documentation once refined.

I tried to leave questions I had in bold. I think it would be beneficial to have a list of the Nodes and their potential values etc. It would also be nice to have a place for proposed or potential ones as well. I did see one potential issue that I am going to file a bug report for with the Module Manifest.

PlasterManifest

Metadata

• id - Unique ID to for the Package
• title - Name of Package to Show in UIs
• description - Description message for UIs
• version - Package version
• tags - I am assuming these will be searchable if there is eventually a gallery type store or when searching through your own templates?

Parameters:

• Is the parameters section where you want a User to set a Custom variable? You could add a new type called Define or similar and they could so something like the following:

<parameter name='CustomDateFormat' type='define' default="$(([DateTime]::Now).ToString('yyyyMMdd'))" store='true'/>
<parameter name='StaticVariable' type='define' default="NoPromptStaticVariableValue" store='true'/>

I am not exactly sure what you had decided on with Code Execution and how that would impact this. If a user needed access to something like a Custom DateTime format, they could create their own variable like above. You could also just define variables without prompts. These could also be defined in a config file, but do you plan to give the ability to define variables in a config file without them needing a prompt

• The possible types and/or planned types
  • input - Prompts user for input
  • choice - Prompts user to select 1 choice
  • mulitchoice - Prompts user to select 1 or multiple choices
• required - The Parameter is required
• store - I'm not quite sure yet, I am guessing this has something to do with stored variables in a config file that is not fully implemented yet. I didn't see anything in invokeplaster.ps1 at first glance.
• prompt - What is prompted to the user. Is this Required? Can it be omitted? If omitted will the user still be prompted with a blank prompt?

Parameter Choice

• The Choices for a choice or multichoice Type. These are used with a $host.ui.PromptforChoice dialogue that should work in editors as well.
• label - Value Shown in Prompt to User
• help - Small Help Messahe explaining Choice
• value - The Actual Value

Dependencies

• id - Potential Dependency IDs based on package metadata IDs

Content

• This section defines the scaffolding to be built.
• Content Elements:
• file
  • source - Source File that will be copied.
  • destination - Destination where the file will be copied
  • condition - Condition that must be met for this to be invoked.
  • encoding - File encoding
  • template - Templates will have Plaster Variables that will be replaced.
• newModuleManifest - Creates a new Module Manifest for the Project.
  • destination - Module psd1
  • moduleVersion - Package version
  • rootModule - Module psm1
  • author - Author of the Module
  • condition - A little confused on the condition for newModuleManifest. $FileNode.condition is referenced to define the condition, but newModuleManifest is its own node and not a FileNode. If you add a condition to the Manifest, it will not respect it. I would need to test if creating a File Node for a Manifest and setting the condition to false would carry over to the newModuleManifest Node
• modify - Modifies Content with options for Conditions.
  • path - Path to file being modified
  • encoding - Encoding of the File (Should this be validated?)
  • condition - Condition that must be met for this to be invoked.
    • Replacement - Replaces content via pattern.

[rkeithhill]

tags - I am assuming these will be searchable if there is eventually a gallery type store or when searching through your own templates?

Distribution of templates has yet to be determined. Whether there are tags in the manifest may depend on the distribution mechanism. If we distribute these as PowerShell "modules" then the tags would probably be put at the module level.

Is the parameters section where you want a User to set a Custom variable?

The template author often needs the end user to supply information (module name, pick a license, etc). That is what parameters are for. They will result in the creation of a dynamic parameter on the Invoke-Plaster command and the user will be prompted if that parameter is not supplied.

WRT to code execution, we specifically do not allow arbitrary code execution when computing the value of a manifest attribute. So no $(Get-Date -f yyyyMMdd) and no $(Remove-Item C:\* -R -For). :-) While I don't see the value for setting "static" template defined variables, I do see the value for things like customized date format. We currently predefine a number of variable you can use PLASTER_Date, PLASTER_Time, PLASTER_Year, PLASTER_Guid1-5. I can add more of these but what we might do is try to find a way to allow for safe string formatting. I'll look into that.

store - I'm not quite sure yet, I am guessing this has something to do with stored variables in a config file that is not fully implemented yet. I didn't see anything in invokeplaster.ps1 at first glance.

This is not currently implemented. The feature will store the user's response to a parameter prompt like like FullName such that the next time the template prompts the user for this parameter, the stored value will be used as the default value. Template authors will be able to pick which parameters should be stored and whether the response is stored in plain text or encrypted.

prompt - What is prompted to the user. Is this Required? Can it be omitted? If omitted will the user still be prompted with a blank prompt?

This is required. This is the whole point of parameters. :-) For the user to supply the required value just like a command's mandatory parameters.

condition - A little confused on the condition for newModuleManifest. $FileNode.condition is referenced to define the condition, but newModuleManifest is its own node and not a FileNode. If you add a condition to the Manifest, it will not respect it. I would need to test if creating a File Node for a Manifest and setting the condition to false would carry over to the newModuleManifest Node

Oops, this is a (copy/paste) bug. It should be $NewModuleManifestNode.condition. I'll fix that tonight. Thanks for pointing it out. There is other work to do on this directive. The conflict handling doesn't really work yet either.

encoding - Encoding of the File (Should this be validated?)

What do you mean? Are you asking if the value provided to the attribute should be validated? If so, yes. If we decide to stick with the XML format I"ll bang out a XML schema for the manifest which can be used to validate against and drive Intellisense in an editor.

[daviwil]

If we distribute these as PowerShell "modules" then the tags would probably be put at the module level.

Yep, agreed with that.

[gerane]

This is required. This is the whole point of parameters. :-) For the user to supply the required value just like a command's mandatory parameters.

I guess what I was getting at, was where could a user define default settings if they will always have the same answer and don't want to see a prompt. That could be accomplished by allowing you to remove the prompt and just auto accept the default value, or it could be done in a config file.

There are times where I'd rather not have to feed the command a hashtable of my default values I want to skip if they are going to be static 99% of the time, and at the same time I don't want to remove them from the template because someone else will find them useful.

I am just thinking of some of the templates I am testing out. I could make them more open and try to share them, but then I have a large number of prompts that I might normally have just filled in by hand into my template. I'd like to be able to have a template that I can feed the defaults from a config file, and then in some cases, all I need to feed Plaster is the Projects name.

I suppose I could save my hashtables to clixml and run plaster with a splatted import-clixml, but I am guessing others would want that sort of config file too. What are the plans for a config file for this sort of thing?

[rkeithhill]

I guess what I was getting at, was where could a user define default settings if they will always have the same answer and don't want to see a prompt.

This is what the store is for. The user does not need to do anything other than to run the template once and answer the prompt. However they will get prompted the next time the template is run but the can accept the default value and not have to type anything in. Of course, if they do type in something else, that will become the new default value. The store mechanism works pretty well in the Yeoman world and I suspect it will work good for Plaster as well.

For your scenario, I'd configure a hashtable and take advantage of the dynamic parameters created from your template.

As for auto-accepting default values - that is something to think about. Perhaps using -Force could cause all the default values (stored or otherwise) to be used instead of prompting.

[gerane]

I guess there is always the ability to make a wrapper or custom Editor-Command if using VS Code as well. I know in VS Code I was already planning to make Custom wrapper Editor Commands so after the command finished it opens the new directory or project file in the editor.

[daviwil]

Regarding opening new directory/file in the editor, I'd like for that to be the default behavior in Plaster. If you create a new project it should open a new window for that directory. Likewise for a new file it should open the created file in the current workspace.

[rkeithhill]

@daviwil Are you referring to Plaster module or the ISE/VSCode integration bit (like the Yo extension for VSCode/Yeoman)? We wouldn't want to have editor specific code in the module, right?

[daviwil]

I'm referring to code using $psEditor built in to the module. I would only be using the editor-agnostic APIs in $psEditor so that the same behavior would appear in all editors. I think it'd be better to have the commands built in so that each editor didn't need its own wiring. Granted, there may be some pitfalls with that approach but we can work through them when we find them.

[rkeithhill]

Ah. So if another editor, say Sublime, wanted to participate they would use this same scheme? And when running from the command line, the $psEditor would be $null so we wouldn't attempt to open an editor?

[daviwil]

Yep, exactly. Sublime Text and all other major integrations will have $psEditor support. If an editor doesn't support it or if you're running in the console, $psEditor won't exist or will be $null. This will allow us to include the editor command integration with the module but have it only show up when in a host that supports it.

[cdhunt]

I assume templateFile has replaced file template=true.

[rkeithhill]

@cdhunt Yes it has. We needed a way to copy files raw (<file .../>) that was different from opening the file, looking for a template substitution pattern, replacing that pattern and then saving that file back out - hence <templateFile .../>. We didn't really want to be doing the latter operation on non-template (potentially binary) files.