Recherche avancée

Sur d’autres sites (8389)

• How to create a command – Introducing the Piwik Platform

  2 octobre 2014, par Thomas Steur — Development

  This is the next post of our blog series where we introduce the capabilities of the Piwik platform (our previous post was How to publish your plugin or theme on the Piwik Marketplace). This time you’ll learn how to create a new command. For this tutorial you will need to have basic knowledge of PHP.

  What is a command ?

  A command can execute any task on the command line. Piwik provides currently about 50 commands via the Piwik Console. These commands let you start the archiver, change the number of available custom variables, enable the developer mode, clear caches, run tests and more. You could write your own command to sync users or websites with another system for instance.

  Getting started

  In this series of posts, we assume that you have already set up your development environment. If not, visit the Piwik Developer Zone where you’ll find the tutorial Setting up Piwik.

  To summarize the things you have to do to get setup :

  • Install Piwik (for instance via git).
  • Activate the developer mode : ./console development:enable --full.
  • Generate a plugin : ./console generate:plugin --name="MyCommandPlugin". There should now be a folder plugins/MyCommandPlugin.
  • And activate the created plugin under Settings => Plugins.

  Let’s start creating a command

  We start by using the Piwik Console to create a new command. As you can see there is even a command that lets you easily create a new command :

  ./console generate:command

  The command will ask you to enter the name of the plugin the created command should belong to. I will simply use the above chosen plugin name “MyCommandPlugin”. It will ask you for a command name as well. I will use “SyncUsers” in this example. There should now be a file plugins/MyCommandPlugin/Commands/Syncusers.php which contains already an example to get you started easily :

  class Syncusers extends ConsoleCommand
  {
      protected function configure()
      {
          $this->setName('mycommandplugin:syncusers');
          $this->setDescription('MyCommandPlugin');
          $this->addOption('name', null, InputOption::VALUE_REQUIRED, 'Your name:');
      }
   
      /**
       * Execute command like: ./console mycommandplugin:syncusers --name="The Piwik Team"
       */
      protected function execute(InputInterface $input, OutputInterface $output)
      {
          $name    = $input->getOption('name');
   
          $message = sprintf('Syncusers: %s', $name);
   
          $output->writeln($message);
      }
  }
  Télécharger

  Any command that is placed in the “Commands” folder of your plugin will be available on the command line automatically. Therefore, the newly created command can now be executed via ./console mycommandplugin:syncusers --name="The Piwik Team".

  The code template explained

  protected function configure()
  {
      $this->setName('mycommandplugin:checkdatabase');
      $this->setDescription('MyCommandPlugin');
      $this->addOption('name', null, InputOption::VALUE_REQUIRED, 'Your name:');
  }
  Télécharger

  As the name says the method configure lets you configure your command. You can define the name and description of your command as well as all the options and arguments you expect when executing it.

  protected function execute(InputInterface $input, OutputInterface $output)
  {
      $name    = $input->getOption('name');
      $message = sprintf('Syncusers: %s', $name);
      $output->writeln($message);
  }
  Télécharger

  The actual task is defined in the execute method. There you can access any option or argument that was defined on the command line via $input and write anything to the console via $output argument.

  In case anything went wrong during the execution you should throw an exception to make sure the user will get a useful error message. Throwing an exception when an error occurs will make sure the command does exit with a status code different than 0 which can sometimes be important.

  Advanced features

  The Piwik Console is based on the powerful Symfony Console component. For instance you can ask a user for any interactive input, you can use different output color schemes and much more. If you are interested in learning more all those features have a look at the Symfony console website.

  How to test a command

  After you have created a command you are surely wondering how to test it. Ideally, the actual command is quite short as it acts like a controller. It should only receive the input values, execute the task by calling a method of another class and output any useful information. This allows you to easily create a unit or integration test for the classes behind the command. We will cover this topic in one of our future blog posts. Just one hint : You can use another command ./console generate:test to create a test. If you want to know how to test a command have a look at the Testing Commands documentation.

  Publishing your Plugin on the Marketplace

  In case you want to share your commands with other Piwik users you can do this by pushing your plugin to a public GitHub repository and creating a tag. Easy as that. Read more about how to distribute a plugin and best practices when publishing a plugin.

  Isn’t it easy to create a command ? We never even created a file ! If you have any feedback regarding our APIs or our guides in the Developer Zone feel free to send it to us.

• How to make your plugin multilingual – Introducing the Piwik Platform

  29 octobre 2014, par Thomas Steur — Development

  This is the next post of our blog series where we introduce the capabilities of the Piwik platform (our previous post was Generating test data – Introducing the Piwik Platform). This time you’ll learn how to equip your plugin with translations. Users of your plugin will be very thankful that they can use and translate the plugin in their language !

  Getting started

  In this post, we assume that you have already set up your development environment and created a plugin. If not, visit the Piwik Developer Zone where you’ll find the tutorial Setting up Piwik and other Guides that help you to develop a plugin.

  Managing translations

  Piwik is available in over 50 languages and comes with many translations. The core itself provides some basic translations for words like “Visitor” and “Help”. They are stored in the directory /lang. In addition, each plugin can provide its own translations for wordings that are used in this plugin. They are located in /plugins/*/lang. In those directories you’ll find one JSON file for each language. Each language file consists in turn of tokens that belong to a group.

  {
  
      "MyPlugin":{
  
          "BlogPost": "Blog post",
  
          "MyToken": "My translation",
  
          "InteractionRate": "Interaction Rate"
  
      }
  
  }

  A group usually represents the name of a plugin, in this case “MyPlugin”. Within this group, all the tokens are listed on the left side and the related translations on the right side.

  Building a translation key

  As you will later see to actually translate a word or a sentence you’ll need to know the corresponding translation key. This key is built by combining a group and a token separated by an underscore. You can for instance use the key MyPlugin_BlogPost to get a translation of “Blog post”. Defining a new key is as easy as adding a new entry to the “MyPlugin” group.

  Providing default translations

  If a translation cannot be found then the English translation will be used as a default. Therefore, you should always provide a default translation in English for all keys in the file en.json (ie, /plugins/MyPlugin/lang/en.json).

  Adding translations for other languages

  This is as easy as creating new files in the lang subdirectory of your plugin. The filename consists of a 2 letter ISO 639-1 language code completed by the extension .json. This means German translations go into a file named de.json, French ones into a file named fr.json. To see a list of languages you can use have a look at the /lang directory.

  Reusing translations

  As mentioned Piwik comes with quite a lot of translations. You can and should reuse them but you are supposed to be aware that a translation key might be removed or renamed in the future. It is also possible that a translation key was added in a recent version and therefore is not available in older versions of Piwik. We do not currently announce any of such changes. Still, 99% of the translation keys do not change and it is therefore usually a good idea to reuse existing translations. Especially when you or your company would otherwise not be able to provide them. To find any existing translation keys go to Settings => Translation search in your Piwik installation. The menu item will only appear if the development mode is enabled.

  Translations in PHP

  Use the Piwik::translate() function to translate any text in PHP. Simply pass any existing translation key and you will get the translated text in the language of the current user in return. The English translation will be returned in case none for the current language exists.

  $translatedText = Piwik::translate('MyPlugin_BlogPost');

  Translations in Twig Templates

  To translate text in Twig templates, use the translate filter.

  {{ 'MyPlugin_BlogPost'|translate }}

  Contributing translations to Piwik

  Did you know you can contribute translations to Piwik ? In case you want to improve an existing translation, translate a missing one or add a new language go to Piwik Translations and sign up for an account. You won’t need any knowledge in development to do this.

  Advanced features

  Of course there are more useful things you can do with translations. For instance you can use placeholders like %s in your translations and you can use translations in JavaScript as well. In case you want to know more about those topics check out our Internationalization guide. Currently, this guide only covers translations but we will cover more topics like formatting numbers and handling currencies in the future.

  Congratulations, you have learnt how to make your plugin multilingual !

  If you have any feedback regarding our APIs or our guides in the Developer Zone feel free to send it to us.

• Parsing The Clue Chronicles

  30 décembre 2018, par Multimedia Mike — Game Hacking

  A long time ago, I procured a 1999 game called Clue Chronicles : Fatal Illusion, based on the classic board game Clue, a.k.a. Cluedo. At the time, I was big into collecting old, unloved PC games so that I could research obscure multimedia formats.

  
  
  

  Surveying the 3 CD-ROMs contained in the box packaging revealed only Smacker (SMK) videos for full motion video which was nothing new to me or the multimedia hacking community at the time. Studying the mix of data formats present on the discs, I found a selection of straightforward formats such as WAV for audio and BMP for still images. I generally find myself more fascinated by how computer games are constructed rather than by playing them, and this mix of files has always triggered a strong “I could implement a new engine for this !” feeling in me, perhaps as part of the ScummVM project which already provides the core infrastructure for reimplementing engines for 2D adventure games.

  Tying all of the assets together is a custom high-level programming language. I have touched on this before in a blog post over a decade ago. The scripts are in a series of files bearing the extension .ini (usually reserved for configuration scripts, but we’ll let that slide). A representative sample of such a script can be found here :

  clue-chronicles-scarlet-1.txt

  What Is This Language ?
  At the time I first analyzed this language, I was still primarily a C/C++-minded programmer, with a decent amount of Perl experience as a high level language, and had just started to explore Python. I assessed this language to be “mildly object oriented with C++-type comments (‘//’) and reliant upon a number of implicit library functions”. Other people saw other properties. When I look at it nowadays, it reminds me a bit more of JavaScript than C++. I think it’s sort of a Rorschach test for programming languages.

  Strangely, I sort of had this fear that I would put a lot of effort into figuring out how to parse out the language only for someone to come along and point out that it’s a well-known yet academic language that already has a great deal of supporting code and libraries available as open source. Google for “spanish dolphins far side comic” for an illustration of the feeling this would leave me with.

  It doesn’t matter in the end. Even if such libraries exist, how easy would they be to integrate into something like ScummVM ? Time to focus on a workable approach to understanding and processing the format.

  Problem Scope
  So I set about to see if I can write a program to parse the language seen in these INI files. Some questions :

  1. How large is the corpus of data that I need to be sure to support ?
  2. What parsing approach should I take ?
  3. What is the exact language format ?
  4. Other hidden challenges ?

  To figure out how large the data corpus is, I counted all of the INI files on all of the discs. There are 138 unique INI files between the 3 discs. However, there are 146 unique INI files after installation. This leads to a hidden challenge described a bit later.

  What parsing approach should I take ? I worried a bit too much that I might not be doing this the “right” way. I’m trying to ignore doubts like this, like how “SQL Shame” blocked me on a task for a little while a few years ago as I concerned myself that I might not be using the purest, most elegant approach to the problem. I know I covered language parsing a lot time ago in university computer science education and there is a lot of academic literature to the matter. But sometimes, you just have to charge in and experiment and prototype and see what falls out. In doing so, I expect to have a better understanding of the problems that need to solved and the right questions to ask, not unlike that time that I wrote a continuous integration system from scratch because I didn’t actually know that “continuous integration” was the keyword I needed.

  Next, what is the exact language format ? I realized that parsing the language isn’t the first and foremost problem here– I need to know exactly what the language is. I need to know what the grammar are keywords are. In essence, I need to reverse engineer the language before I write a proper parser for it. I guess that fits in nicely with the historical aim of this blog (reverse engineering).

  Now, about the hidden challenges– I mentioned that there are 8 more INI files after the game installs itself. Okay, so what’s the big deal ? For some reason, all of the INI files are in plaintext on the CD-ROM but get compressed (apparently, according to file size ratios) when installed to the hard drive. This includes those 8 extra INI files. I thought to look inside the CAB installation archive file on the CD-ROM and the files were there… but all in compressed form. I suspect that one of the files forms the “root” of the program and is the launching point for the game.

  Parsing Approach
  I took a stab at parsing an INI file. My approach was to first perform lexical analysis on the file and create a list of 4 types : symbols, numbers, strings, and language elements ([]{}()=., :). Apparently, this is the kind of thing that Lex/Flex are good at. This prototyping tool is written in Python, but when I port this to ScummVM, it might be useful to call upon the services of Lex/Flex, or another lexical analyzer, for there are many. I have a feeling it will be easier to use better tools when I understand the full structure of the language based on the data available.
  
  The purpose of this tool is to explore all the possibilities of the existing corpus of INI files. To that end, I ran all 138 of the plaintext files through it, collected all of the symbols, and massaged the results, assuming that the symbols that occurred most frequently are probably core language features. These are all the symbols which occur more than 1000 times among all the scripts :

     6248 false
     5734 looping
     4390 scripts
     3877 layer
     3423 sequentialscript
     3408 setactive
     3360 file
     3257 thescreen
     3239 true
     3008 autoplay
     2914 offset
     2599 transparent
     2441 text
     2361 caption
     2276 add
     2205 ge
     2197 smackanimation
     2196 graphicscript
     2196 graphic
     1977 setstate
     1642 state
     1611 skippable
     1576 desc
     1413 delayscript
     1298 script
     1267 seconds
     1019 rect
  

  About That Compression
  I have sorted out at least these few details of the compression :

  bytes 0-3    "COMP" (a pretty strong sign that this is, in fact, compressed data)
  bytes 4-11   unknown
  bytes 12-15  size of uncompressed data
  bytes 16-19  size of compressed data (filesize - 20)
  bytes 20-    compressed payload
  

  The compression ratios are on the same order of gzip. I was hoping that it was stock zlib data. However, I have been unable to prove this. I wrote a Python script that scrubbed through the first 100 bytes of payload data and tried to get Python’s zlib.decompress to initialize– no luck. It’s frustrating to know that I’ll have to reverse engineer a compression algorithm that deals with just 8 total text files if I want to see this effort through to fruition.

  Update, January 15, 2019
  Some folks expressed interest in trying to sort out the details of the compression format. So I have posted a followup in which I post some samples and go into deeper details about things I have tried :

  Reverse Engineering Clue Chronicles Compression

  The post Parsing The Clue Chronicles first appeared on Breaking Eggs And Making Omelettes.