Nonsense Placement Mandatory

    pptx-automizer
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.1 • Public • Published

    pptx-automizer

    This is a pptx generator for Node.js based on templates. It can read pptx files and insert selected slides or single slide elements into another presentation. pptx-automizer will not write files from scratch, but edit and merge existing pptx files. Template slides are styled within PowerPoint and will be merged into the output presentation. Most of the content can be modified by using callbacks with xmldom.

    pptx-automizer will fit best to users who try to maintain their own library of pptx template files. This is perfect to anyone who uses complex and well-styled customized layouts. Any existing slide and even a single element can be a data driven template for output pptx files.

    This project comes along with automizer-data. You can use automizer-data to import, browse and transform XSLX-data into perfectly fitting graph or table data.

    Requirements

    This generator can only be used on the server-side and requires a Node.js environment.

    Limitations

    Please note that this project is work in progress. At the moment, you might encounter difficulties for special shape types that require further relations (e.g. links will not work properly). Although, most shape types are already supported, such as connection shapes, tables or charts. You are welcome to report any issue.

    All testing focuses on PowerPoint 2019 pptx file format.

    Install

    There are basically two ways to use pptx-automizer.

    As a cloned repository

    If you want to see how it works and you like to run own tests, you should clone this repository and install the dependencies:

    $ git clone git@github.com:singerla/pptx-automizer.git
    $ cd pptx-automizer
    $ yarn install
    

    You can now run

    $ yarn dev
    

    and see the most recent feature from src/dev.ts. Every time you change & save this file, you will see new console output and a pptx file in the destination folder. Take a look into __tests__-directory to see a lot of examples for several use cases!

    As a package

    If you are working on an existing project, you can add pptx-automizer to it using npm or yarn. Run

    $ yarn add pptx-automizer
    

    or

    $ npm install pptx-automizer
    

    in the root folder of your project. This will download and install the most recent version into your existing project.

    Example

    import Automizer, { modify } from "pptx-automizer"
    
    // First, let's set some preferences
    const automizer = new Automizer({
      templateDir: `my/pptx/templates`,
      outputDir: `my/pptx/output`
    })
    
    // Now we can start and load a pptx template.
    // Each addSlide will append to any existing slide in RootTemplate.pptx.
    let pres = automizer.loadRoot(`RootTemplate.pptx`)
      // We want to make some more files available and give them a handy label.
      .load(`SlideWithShapes.pptx`, 'shapes')
      .load(`SlideWithGraph.pptx`, 'graph')
      // Skipping the second argument will not set a label.
      .load(`SlideWithImages.pptx`)
    
    // addSlide takes two arguments: The first will specify the source 
    // presentation's label to get the template from, the second will set the 
    // slide number to require.
    pres.addSlide('graph', 1)
      .addSlide('shapes', 1)
      .addSlide(`SlideWithImages.pptx`, 2)
    
    // You can also select and import a single element from a template slide. 
    // The desired shape will be identified by its name from slide-xml's 
    // 'p:cNvPr'-element.
    pres.addSlide('SlideWithImages.pptx', 1, (slide) => {
      // Pass the template name, the slide number, the element's name and 
      // (optionally) a callback function to directly modify the child nodes 
      // of <p:sp>
      slide.addElement('shapes', 2, 'Arrow', (element) => {
        element.getElementsByTagName('a:t')[0]
          .firstChild
          .data = 'Custom content'
      })
    })
    
    // It is possible to modify an existing element on a newly added slide.
    pres.addSlide('shapes', 2, (slide) => {
      slide.modifyElement('Drum', [
        // You can use some of the builtin modifiers to edit a shape's xml:
        modify.setPosition({x: 1000000, h:5000000, w:5000000}),
        // Log your target xml into the console:
        modify.dump
      ])
    })
    
    // Modify an existing chart on an added slide.
    pres.addSlide('charts', 2, (slide) => {
      slide.modifyElement('ColumnChart', [
        // Use an object like this to inject the new chart data.
        // Additional series and categories will be copied from
        // previous sibling.
        modify.setChartData({
          series: [
            { label: 'series 1' },
            { label: 'series 2' },
            { label: 'series 3' },
          ],
          categories: [
            { label: 'cat 2-1', values: [ 50, 50, 20 ] },
            { label: 'cat 2-2', values: [ 14, 50, 20 ] },
            { label: 'cat 2-3', values: [ 15, 50, 20 ] },
            { label: 'cat 2-4', values: [ 26, 50, 20 ] }
          ]
        })
        // Please notice: If your template has more data than your data
        // object, automizer will remove these nodes.
      ])
    })
    
    // Finally, we want to write the output file.
    pres.write(`myPresentation.pptx`).then(summary => {
      console.log(summary)
    })

    Testing

    You can run all unit tests using these commands:

    yarn test
    yarn test-coverage
    

    Special Thanks

    This project is deeply inspired by:

    Install

    npm i pptx-automizer

    DownloadsWeekly Downloads

    43

    Version

    0.1.1

    License

    MIT

    Unpacked Size

    424 kB

    Total Files

    206

    Last publish

    Collaborators

    • singerla