Creating a Package

    The goal of this tutorial is to extend Umbraco and create a package. The tutorials starting point is to create a package out of the dashboard from the Creating a Custom Dashboard tutorial. The process is the same for most packages so feel free to follow along with something else.

    Creating a package in the backoffice

    To create a package through the Umbraco backoffice:

    1. Go to the Packages section.

    2. Select Created in the top-right corner of the screen.

    3. Select the Create package button.

      Buttons to select for creating a package in the backoffice

    4. On the Create package page, there are 4 sections each with different information to fill out. Some of the fields are mandatory, most of it is not.

    5. Enter the package name at the top - we will call our dashboard the same as in the Tutorial: Custom Welcome Dashboard.

    We will now take a look at the individual sections and the values that can be filled in:

    Package Properties section

    This section contains mostly meta data about the package and the creator. We will fill in the following things:

    Property Value Note
    Url https://umbraco.com This URL will be shown as the package's URL when others install it. It will likely be a Github repository, or similar.
    Version 1.0.0 This is automatically set to 1.0.0 but can be changed as appropriate.
    Icon Url Blank Not a mandatory value, but will appear as the package's icon in different places in the backoffice if set.
    Umbraco version 9.0.0 This will automatically select the Umbraco version you are currently using and is set as the compatible version for the package.
    Author Your name Here you get to take credit for your awesome work!
    Author URL Your website or maybe a link to your Twitter profile This will be linked to from the author name when displayed in the backoffice.
    Contributors Blank Here you can add the names of other contributors if you have any.
    License MIT License Will be set to MIT by default. Please consider how you want your package licensed. If in doubt when deciding an open-source license there are good resources available.
    License URL http://opensource.org/licenses/MIT Will be set to the URL for the MIT license and can be changed as needed.
    Package readme This will add a dashboard to your content section.

    The dashboard will show each user the most recent nodes they have saved.
    This will be shown when someone looks at the package in the packages dashboard.

    Package Content section

    This section is used to determine which things the package should contain. We will fill in the following things:

    Property Value Note
    Content Empty Here, you can include content - e.g. if you want to create a starter kit. Not relevant for this package though.
    Media Empty Here, you can include media - e.g. if you want to add media to the starter kit. Not relevant for this package though.
    Document Types Empty Similar to the Content picker above. It is important to note that if you include content you will need to also pick all its dependencies in this and the next steps for them to be packaged together!
    Media Types Empty Similar to the Media picker above. It is important to note that if you include media you will need to also pick all its dependencies in this and the next steps for them to be packaged together!
    Templates Empty See Document Types above
    Stylesheets Empty These will come from the wwwroot/css folder. If you have stylesheets you want to include from other locations you can do so at a later step.
    Macros Empty See Document Types above
    Languages Empty See Document Types above - all text is hardcoded or within our own lang folder in this package, so this is not needed
    Dictionary Empty See Document Types above
    Data Types Empty See Document Types above

    Package Files section

    In this section you will be able to select all of your own custom files. We will start with the Path to file option.

    Since everything in our Dashboard is from the same folder in App_Plugins, we can select the folder and it will include all items inside that folder:

    Selecting the files you want in your package

    We will leave the Package options view selector empty, but in case you were wondering you can select an HTML file here that will show up as package options. Here is an example from the package Articulate:

    Gif of Articulates use of Package options

    Package Actions section

    Here, you can add package actions. There are a number of default package actions and you can also create your own custom package actions

    Finally, after filling out all the information we can select Create to create the package. We will download it, in order to take a closer look at what it contains in the generated zip file.

    Inspecting a package zip

    When you download and then open the zip package you will find that it looks like this:

    Content of a zip package

    The 5 highlighted files contained in the package are the ones that we created in the Creating a Custom Dashboard Tutorial. However, there is another file here called package.xml - so let's take a look at that. It looks like this:

    <?xml version="1.0" encoding="utf-8"?>
    <umbPackage>
      <files>
        <file>
          <guid>customwelcomedashboard.controller.js</guid>
          <orgPath>~/App_Plugins/CustomWelcomeDashboard</orgPath>
          <orgName>customwelcomedashboard.controller.js</orgName>
        </file>
        <file>
          <guid>customwelcomedashboard.css</guid>
          <orgPath>~/App_Plugins/CustomWelcomeDashboard</orgPath>
          <orgName>customwelcomedashboard.css</orgName>
        </file>
        <file>
          <guid>package.manifest</guid>
          <orgPath>~/App_Plugins/CustomWelcomeDashboard</orgPath>
          <orgName>package.manifest</orgName>
        </file>
        <file>
          <guid>WelcomeDashboard.html</guid>
          <orgPath>~/App_Plugins/CustomWelcomeDashboard</orgPath>
          <orgName>WelcomeDashboard.html</orgName>
        </file>
        <file>
          <guid>en-US.xml</guid>
          <orgPath>~/App_Plugins/CustomWelcomeDashboard/lang</orgPath>
          <orgName>en-US.xml</orgName>
        </file>
      </files>
      <info>
        <package>
          <name>Custom Welcome Dashboard</name>
          <version>1.0.0</version>
          <iconUrl></iconUrl>
          <license url="http://opensource.org/licenses/MIT">MIT License</license>
          <url>https://github.com/umbraco/customwelcomedashboard</url>
          <requirements type="Strict">
            <major>9</major>
            <minor>0</minor>
            <patch>0</patch>
          </requirements>
        </package>
        <author>
          <name>Jesper Mayntzhusen</name>
          <website>https://jesper.com</website>
        </author>
        <contributors></contributors>
        <readme><![CDATA[This will add a dashboard to your content section. 
    
    The dashboard will show each user the most recent nodes they have saved.]]></readme>
      </info>
      <DocumentTypes />
      <Templates />
      <Stylesheets />
      <Macros />
      <DictionaryItems />
      <Languages />
      <DataTypes />
      <Actions />
    </umbPackage>
    

    You will notice that the values for each of the fields we provided are found inside this XML file. Each file has an orgPath element associated with it - this is where the file will be moved to when the package is installed. So, don't worry if you organised your package in folders and they are not visible in this structure within the zip archive.

    It is very important to get the list of files included correct, as all dependencies are required for the package features to work. On the other hand everything included here will be deleted on uninstall, so you also have to make sure not to include unnecessary things!